Software & TechnicalFree
Inherited System Architecture Rebuild Report
The person who designed it has gone. River reconstructs how it works now and states its confidence on every component.
River's reconstruction tool starts from what is running rather than from what somebody drew. The repository, the infrastructure configuration, the surviving diagrams and whatever dashboards you can reach all go in. Out comes an account of the architecture as it stands today, a context and container view rebuilt from evidence, and a component register carrying a confidence level and the class of evidence behind every single entry. The parts nobody can establish are listed as unresolved rather than drawn in.
Page one for this search is a shelf of best-practice guides: choose a template, pick your views, add a glossary, keep it current. Every one of them is written for somebody who understands the system and needs a format. That is the opposite of the situation. The template is not the hard part. The hard part is that a confident diagram of a system nobody understands gets trusted, and the first person to act on a wrong arrow finds out at three in the morning.
Built for the team that absorbed a platform in an acquisition, the engineer who owns a service whose author left, and the consultant on day one of an unfamiliar estate. Reach for it before you promise anything about the system. For module-level detail inside a single repository, the inherited codebase documentation goes deeper on the code itself. Once enough of the register reads confirmed, the solution architecture document is what you hand a client, and any reasoning you recover belongs in an architecture decision record.
A missing arrow is not evidence of a missing call
The instinct is to run blame and find whoever understands each file. Git documents the limit itself: the report does not tell you anything about lines which have been deleted or replaced. In a reconstruction that is the whole game. The abandoned approach, the ripped-out fallback, the queue replaced by a direct call are what explain the shape of the code in front of you, and every one is invisible to blame. Searching the diffs for the vanished string is the only way back.
The diagram's arrows are a wish list. Kubernetes states the default plainly: a pod is non-isolated for egress and all outbound connections are allowed, and ingress works the same way, so in a namespace with no policy every workload can reach every other one. The same page adds that a policy resource created without a controller that implements it has no effect at all. Two conclusions follow. A missing arrow proves nothing, and a policy file in the repository is not a boundary until something enforces it.
Everyone reaching for C4 to draw the inherited system heads straight for the component level, and the model itself says not to. Asked whether component diagrams are recommended, it answers no, only create them if you feel they add value, and consider automating their creation. Context and container are where the evidence lives, because deployments, data stores and running services all leave traces. Component level is reconstructed only for the container you are about to change, and it is regenerated rather than maintained.
How it works
Say what you have
Point at the repository, the infrastructure configuration, the old diagrams and whatever dashboards you can reach.
River reconciles them
Code against config against runtime, so a component's evidence and its confidence level come out together.
Read the register
The architecture as it stands, the rebuilt views, and every component's confidence stated in a column.
Work the unresolved
Each unresolved row names the check that would settle it, so confidence climbs as you go.
What you get
- A component register with a confidence level and the class of evidence behind every entry
- The repository reconciled against what is actually deployed, so dead code and hidden services separate
- Context and container views rebuilt from evidence, with the unproven edges marked as unproven
- The unresolved list, each entry with the one check that would settle it
- The reasoning recovered from commit messages, pull requests and the code that got deleted
- What the old diagram got right and wrong, both recorded rather than quietly overwritten
Common questions
The person who designed it has gone. What can you actually recover?
What the system does, with evidence. What it was for, sometimes, from commit messages, pull request threads, ticket links and the code that got removed. Why a particular tradeoff was chosen, rarely, and that gap is stated rather than filled. The register separates the three, because a reader who cannot tell them apart will trust all of it equally.
What does a confidence level actually mean here?
It names the class of evidence, not a feeling. Observed serving real traffic is the top of the scale. Declared in infrastructure that is actually applied comes next, then present in the code and consistent with the config, then named in a document and corroborated by nothing. The class travels with the row, so a reader can requalify it themselves.
The only diagram we have is two years old. Is it worth anything?
It is worth a lot, as a claim rather than a source. Every element in it becomes a row to confirm or refute, and the refutations are the findings: the box that no longer exists, the arrow the platform never permitted, the store that got replaced. Both the diagram's version and the evidence go into the document, dated.
How is this different from documenting the codebase?
Scope and unit. The inherited codebase documentation works inside one repository and its unit is a module. This works across an estate and its unit is a running component, which is why the repository is only one of its inputs. On a system that is one service in one repo, run that one first and this one after.
I have the repository but not production access. Does it still work?
Yes, and the confidence column tells you exactly what the missing access cost. Without runtime evidence the top of the scale is empty, so rows land at declared or inferred instead of observed. The unresolved list then names the specific thing to look at once someone grants access, which is a useful ask to walk in with.
What do I do with the components nobody can account for?
Treat them as the work queue. Each unresolved row carries the one check that would settle it: a log to search, a load balancer to look behind, a bill line to trace to a resource, a person who might remember. Working the list in order is how the register moves from mostly inferred to mostly confirmed.
When is the reconstruction finished enough to publish?
When the confidence column carries no surprises for the audience reading it. An onboarding map for the next engineer ships with inferred rows still in it, which is fine for that purpose. Anything a client or auditor accepts wants the solution architecture document built on top, and that one wants the register mostly confirmed first, which is the honest sequence.
Inherited System Architecture Rebuild Report
Fill in the form and your workspace opens with the work already underway.