Who the System Report is for
- A .NET / C# backend that has been running in production for years.
- A small or mid-size engineering team (roughly 2–15) with no one left who fully built it.
- Real business depends on it — revenue, operations, customer support, or compliance flow through it.
- A planned change that feels too risky to start without understanding the system end-to-end first.
Why this work is difficult
The hard part is not finding messy code.
The hard part is knowing what the mess protects.
Inherited systems become risky because business behaviour spreads across code, database shape, old rules, admin workarounds, background jobs, vendor integrations, deployment habits, and team memory. The report exists to find that shape before anyone changes it.
Rules vs. accidents
The report separates rules from accidents.
Some strange code is a business rule. Some is dead. Some is unsafe. Some is accidental but relied upon. The report labels the difference before recommending a change.
Reality, not green ticks
The report tests against reality.
A green test is only useful if it proves something real: a database state, an API response, a confirmed business example, or a production-shaped workflow. The report separates real safety from false confidence.
A ranked next move
The report ranks the next move.
You do not get forty disconnected observations. You get the findings that matter most to the stated outcome, ranked by business impact and change risk.
What coherence makes possible
When the system cooperates with itself,
the same effort starts producing more.
A report does not exist only to remove problems. The deeper job is to find the structures everything else depends on — the load-bearing concepts and flows — and make them hold. Once they hold, the same structures begin supporting many workflows at once. Improvement starts to compound instead of fragment.
One structure, many workflows
One concept stops costing you everywhere.
One identity model carries auth, billing, onboarding, and permissions. One operational-event system carries retries, debugging, audit, and visibility. When the same word means the same thing across the system, the system stops paying interest on its own confusion.
Reduce contradiction
Simplification removes contradiction, not capability.
The problem is often not complexity. It is contradiction — duplicated rules, exceptions to exceptions, behaviour that is one thing in code and another in the database. The cleanup work is finding those contradictions and resolving them in one place, so the system can stop disagreeing with itself.
Load-bearing first
Identify what must hold before changing the system.
Not the loudest feature, not the newest one — the structures the rest of the system rests on staying coherent. When those are made strong before scale, future movement becomes cheaper. When they are skipped, every later change pays for them with friction.
Hidden coupling is future cost already accumulated. Reduce contradiction before adding capability — and the same effort starts producing more.
When understanding must come first
The System Report.
Software systems contain business rules, old decisions, deployment assumptions, third-party dependencies, and parts that work only because nobody has touched them recently. When that hidden shape is what makes change risky, the report makes it visible before any new work begins.
Findings are ranked by business relevance — revenue, customer experience, operational risk, support burden, delivery speed, reliability, compliance, onboarding, and the ability to safely ship the next valuable change — not by technical ugliness. The goal is the next move that creates the most useful change for the money spent.
Sometimes one feature can be forced through a fragile foundation. If the business plans to keep building, the better first move may be cleanup — tests, boundaries, clarified ownership, and a safer place for future work to land.
From first email to delivered report
A typical engagement flow.
Roughly four to six weeks from first email to delivered report. Four to five weeks of focused engineering inside that, with written touchpoints at each stage and an open follow-up after the report is read.
Day 1–2
Engagement start & access
€1,500 · access grantedEngagement memo signed. The agreed access boundary opens — what can be read, run, and inspected, and what is off-limits. The more access, the sharper the findings.
- Repository
- Deployment notes
- Database / schema
- Test or staging
- Existing tests
- Technical contact
- Product contact
Sample report — content is illustrative; titles mirror the playbook.
Inside the report.
- Typically 30+ pages, plus appendix where useful. PDF + Markdown.
- 6–10 ranked findings with evidence, severity, confidence, and a recommended action.
- Plain-English and technical voice for each finding.
- What can be built directly, what needs cleanup first, and what remains uncertain.
- Change-safety plan: tests, boundaries, and behaviours needing confirmation.
- Recommended next implementation package, if one follows from the evidence.
- Focused-question list and appendix material.
A sample finding — how each one is written
Auth and billing share a service
Plain English
Login and payment changes are tied together in the same code. A change to one can quietly break the other. Before the new feature lands, this area needs a wall between them so future work in either part of the system stays safe.
Technical
AuthService and BillingFacade both mutate UserSubscription in overlapping methods. Recommend extracting a SubscriptionStateService with single-writer ownership, and adding facade-level integration tests covering both auth and billing paths before the new feature lands.
System Report
€3,000
Four to five weeks of focused engineering. Fixed scope, not hourly billing.
Payment. €3,000 fixed price, split into two payments — €1,500 before the review begins, €1,500 on delivery.
Scheduling. The review starts on an agreed date after scope, access, and first payment are confirmed.
Your time during the report. A focused-question list arrives around day 10. The answers come from the people who know which rules are still active, which are historical, and which behaviours are deliberate — usually operations or finance, not engineering. A few hours across the engagement, not full-time involvement.
What you receive: a written System Report with ranked findings, the evidence behind them, the main risks, open questions, and a recommended first implementation package if one makes sense.
What this is not: implementation work, a retainer, emergency support, or a promise to change production code. The next phase is decided only after both sides have read the report.
Send your system contextNot ready to commit? Start with a free Orientation Report → — a short, free, AI-assisted reading of where the pressure is.
Stack fit. Smallbox is at home in .NET / C# backends — ASP.NET Core, Entity Framework, REST API design — with PostgreSQL or MSSQL, and Next.js or Vue frontends when the project needs them. Very large systems or unusual stacks are flagged as out-of-scope before the engagement starts, not after.
Implementation
After the report: a bounded implementation path.
The report decides the path. If it finds controlled twin replacement is the right fit, the next step can be a bounded implementation package — not committed up front, decided after the report is read.
Stage 2
Parallel Replacement Beta
Build the replacement candidate beside the old system. The old system keeps running. The beta includes mapped business rules, a clean application spine, first usable modules, seeded or mirrored data, documentation, and a deployable non-production environment the client can inspect and test.
The client owns the beta even if they stop.
Stage 3 — only if Stage 2 is accepted
Parity + Transition
Prove the candidate. Migration scripts, old/new comparison reports, staff scenario testing, parity verification, bug fixing, cutover planning, rollback planning.
The Beta builds the replacement candidate. The Transition proves whether it can safely replace the old system.
If the report recommends gradual extraction or stabilise-first instead, the first package changes. Gradual extraction is slice-based. Stabilise-first is staging, snapshots, characterisation tests, and deployment safety. The report is the decision gate.