Who the System Report is for
- An existing backend system where the product works, but changing it has become slow, risky, or hard to reason about.
- 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 — until no single place clearly owns a rule. Smallbox calls that responsibility drift. 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.
The System Report is a written technical map of your product: what the system is trying to do, where the important rules live, what is fragile, what is unclear, what lacks tests, and what should be fixed first. The point is better decisions before more money goes into development.
It starts from the business, not from the code: the domain language, the main flows, the responsibilities the system carries. Only then does it map where each responsibility actually lives today — and where one has drifted across controllers, background jobs, admin tools, database shape, and team memory until no single place owns it.
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. And sometimes the honest recommendation is the opposite: do not restructure this yet. That answer is part of the product.
Smallbox works inside the access boundary you choose. Full read-only repository access gives the sharpest report, but the work can also start from documentation, screenshots, selected files, schema notes, or a walkthrough. Access is not binary: more access means stronger evidence, and limited access means a report with clearer confidence boundaries. Either way, every important claim carries its evidence level — runtime-verified, observed in code, documented, or assumed — so no finding claims more certainty than the access supports.
From first answer to delivered report
A typical engagement flow.
Typically four to six weeks from payment to delivered report. You answer at your own pace first; the clock starts when you pay. Clarification questions and the finished report all live in your private workspace, with an open follow-up after you’ve read it.
At your pace
Answer the guided steps
in your workspaceFive short steps about your product, its flows, what it is responsible for, and what feels risky to change. Partial answers are genuinely fine — a thin answer shows where shared understanding is thin, and that is itself a finding. Everything saves as you go and stays editable until you pay.
Sample report — content is illustrative; titles mirror the playbook.
Inside the report.
- Typically 30+ pages, plus appendix where useful. PDF + Markdown.
- Our current understanding of the system, stated up front — what is confirmed, what is assumed, what is still unclear.
- The business in plain English, a working domain dictionary, and the main flows traced end to end.
- A responsibility map: which responsibilities the system carries, and where each one lives in the code today.
- 6–10 ranked findings with evidence, severity, confidence, and a recommended action.
- Every important claim tagged by evidence level — runtime-verified, observed in code, documented, or assumed.
- Plain-English and technical voice for each finding.
- What can be built directly, what needs cleanup first, and what should not move yet.
- Change-safety plan: tests, boundaries, and behaviours needing confirmation.
- Recommended next implementation package, if one follows from the evidence.
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
€4,000
Founding discount: €1,500 for the first five clients. Our standard price is €4,000; while the report format is still being refined and we learn from these first engagements, early clients pay less. One payment, upfront.
Payment. One payment, upfront — fixed scope, not hourly billing. You start the moment it clears, with no scheduling back-and-forth and no waiting on us.
Your time during the report. A few clarification questions arrive in your workspace as we read your system — the ones only your team can answer: which rules are still active, which are historical, which behaviours are deliberate. Usually a few hours from operations or finance across the whole engagement, not full-time involvement.
Access you grant. You set the boundary — what we may read, run, and inspect, and what stays off-limits. Nothing is opened before you pay, read-only access is all we need, and the agreement you sign puts the confidentiality in writing.
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.
Start the System ReportPrefer to talk first? Send your system context → — nothing is charged until you choose to start.
Stack fit. The System Report works across normal backend stacks — .NET / C#, JavaScript / TypeScript and Node, Rails, Python, Java, PHP — because the work starts from the business and its rules, then maps how the code supports or distorts them. Smallbox is strongest in .NET / C# backends (ASP.NET Core, Entity Framework, PostgreSQL or MSSQL), so that is the surest fit; a very unusual stack, or a system outside what we can review well, is flagged before you pay — 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.