Software & TechnicalFree
Solution Architecture Document From Specs
The solution architecture document built from your existing diagrams and specs, with each requirement mapped to the component that satisfies it.
River's architecture tool reads what you already have. The diagrams inherited from whoever drew them, the OpenAPI specs, the infrastructure configuration, the constraints written in an email. Out comes the document: scope and context, the functional requirements, the quality requirements as scenarios with measures, the design decisions, security considerations, and the assumptions and risks. Alongside it, a context and a container view, and a sheet mapping every requirement to the component that satisfies it, in both directions. Where security is the whole question, the threat model pack counts what STRIDE makes applicable.
Every result for this query is a set of headings. Download the template, fill fifteen sections, deliver a document that describes the system accurately and cannot be reviewed. Description is the failure mode: a reader can tell you the diagram looks right and cannot tell you whether anything the client asked for is actually built. The map that makes review possible runs in two directions, and no template ships it because it can only be derived from the artifacts.
Built for the solutions architect delivering to a client, the engineer handed an audit question, and whoever has to onboard the next team. Reach for it when the artifacts exist and the document does not. The decisions that come out of it belong in the architecture decision record pack, which tracks which of them still hold. For a greenfield design with no artifacts to read yet, the system design document starts from the problem instead.
A non-functional requirement without a measure is an adjective
arc42's introduction and goals section is unusually strict about one thing: the top three, maximum five, quality goals for the architecture. It adds that these are goals for the architecture and must not be confused with project goals. That cap is the useful part. A document listing every desirable quality has not told the reader which two the design was actually optimized for, and that is the answer a reviewer needs before anything else in the document means much.
Section 10 of the same template supplies the test. Quality requirements are written as scenarios that make them concrete enough to decide whether they are fulfilled, and it says in as many words to ensure they are specific and measurable. Two shapes are called out as most useful: a usage scenario describing the system's runtime reaction to a stimulus, and a change scenario describing a modification. Scalable is neither. Four thousand concurrent devices with position updates arriving inside thirty seconds is both.
The views need the same discipline. The C4 model defines a container as an application or a data store, something that has to be running for the system to work, and leads with a warning that it does not mean Docker. Get that wrong and the container view becomes a deployment diagram, which answers a different question. Then trace the map both ways: a requirement with no component is a gap, and a component with no requirement is scope nobody asked for.
How it works
Paste the artifacts
Drop in the diagrams, API specs, infrastructure configuration and whatever states the constraints.
River builds the map
Every requirement matched to a component, and every component checked for a requirement behind it.
Read the document
The architecture document, the context and container views, and the traceability sheet under both.
Close the gaps
It lists the requirements nothing satisfies and the questions only a person can answer.
What you get
- Scope, context, requirements, decisions, security and risks, assembled from the artifacts rather than an interview
- Quality requirements rewritten as scenarios with a stimulus, a response and a measure
- A requirement-to-component map traced both ways, so gaps and orphan components both surface
- Context and container views drawn at the right level, with every relationship labelled
- The constraints and the assumptions separated, because one is imposed and the other is a bet
- Every claim tagged with the artifact it was read from, so the review is checkable
Common questions
What does it need from me?
Whatever exists. Old diagrams in any form, an OpenAPI or Swagger file, Terraform or Kubernetes configuration, a requirements document, the email thread that set the constraints. It works from a subset and says what each missing artifact would have settled. The infrastructure configuration is the highest-value input, because it is least likely to disagree with what is actually running. That OpenAPI file on its own feeds the API design review.
How does it handle a diagram that is wrong?
It says so. Where the configuration shows a component the diagram does not, or the diagram shows a link nothing in the code or config supports, both versions go into the document with the artifact each came from. You get the disagreement rather than a silent choice, because the disagreement is usually the most interesting page. When most of the artifacts are unreliable, the architecture reconstruction runs first.
Does it produce the diagrams too?
Context and container views, at those two levels specifically. Component level is worth drawing only for the part of the system under discussion, and code level goes stale before the document is read. Every relationship gets a label describing its intent and the technology behind it, which is what makes a diagram reviewable rather than decorative.
What if the requirements were never written down?
Then the map starts from what the system does and works backwards, and every inferred requirement is marked inferred. That list is often the most useful output, because it is the first time anyone has written down what the system is actually promising. You get one column of confirmed and one of inferred, never a merge.
Is this a solution architecture document or a system design document?
In practice the same artifact with different audiences. A solution architecture document faces a client, an auditor or a review board, so it leads with scope, context and constraints. If you are designing something new rather than documenting what exists, the system design document starts from the problem rather than the artifacts.
Will it hold up in a client or architecture review?
The traceability is what makes it hold up. A reviewer takes any requirement and lands on the component that satisfies it and the artifact that proves it, which is a different conversation from reading prose and nodding. The gaps are listed rather than buried, so the review argues about the open items instead of hunting for them.
How much of this will I have to rewrite?
The judgement calls, which is the right place to spend your time. The quality goals need your ranking, the risks need your appetite, and the assumptions need confirming or killing. Everything mechanical is already done: the inventory, the traceability, the views, and the list of things the artifacts contradict each other about.
Solution Architecture Document From Specs
Fill in the form and your workspace opens with the work already underway.