Technical System Architecture

What a system architecture document is

A technical system architecture document is the single, authoritative description of how a software system is put together: the major parts it is made of, how those parts talk to each other, where the data lives and moves, the technologies chosen to build it, and — crucially — why each of those decisions was made. It is the map a new engineer reads on day one and the reference an experienced one returns to before making a change that crosses module boundaries.

A good architecture document does three jobs at once. It gives a shared mental model so the whole team reasons about the system the same way. It records the trade-offs behind each decision so future readers understand the why, not just the what. And it makes the system's quality attributes — how it scales, how it stays available, how it stays secure — explicit rather than accidental.

What it captures

The document should cover, at minimum:

• Components. The named building blocks of the system (services, modules, stores, queues, jobs) and the single responsibility each one owns. A reader should be able to point at any behaviour and know which component is accountable for it.
• Data flows. How a request or an event travels through the components — what enters, what each step does, what is persisted, and what comes back. Describe these as numbered steps, not just a picture.
• Technology choices and rationale. The languages, frameworks, databases, and platforms in use, each paired with the reason it was chosen over the alternatives. A choice without a reason is a future argument waiting to happen.
• Scalability. How the system grows with load — what scales horizontally, what is a bottleneck, and what the plan is when a component runs out of headroom.
• Reliability. What happens when a part fails — redundancy, retries, timeouts, graceful degradation, and the recovery story.
• Security. How identity, authorisation, secrets, and sensitive data are handled, and where the trust boundaries sit.
• Trade-offs. The decisions that bought one quality at the cost of another, stated honestly. These age the best of all the content here.

Describing diagrams in words

Architecture is usually drawn, but a document that only contains pictures rots quickly and is unreadable to anyone using a screen reader or a small screen. Always pair (or replace) a diagram with prose. To describe a structure in words, name each box, state its responsibility, and then describe each arrow as a sentence: "the web app calls the API over HTTPS; the API reads and writes the primary database; the API publishes an event to the queue, which the worker consumes." A markdown table is often the clearest way to list components and their responsibilities, and a numbered list is the clearest way to walk a reader through a data flow. If you keep a drawn diagram alongside, treat the prose as the source of truth — the picture is a convenience, not the record.

The C4 idea, in plain terms

A common and useful way to organise an architecture document is to describe the system at a few zoom levels, an approach popularised as the C4 model. The idea is simple: do not try to show everything on one picture. Instead, describe the system at increasing levels of detail.

1. Context — the system as a single box, the people who use it, and the external systems it depends on. This is the "10,000-foot view" that a non-technical stakeholder can follow.
2. Containers — the separately deployable or runnable parts (a web app, an API, a database, a worker). Note that "container" here means a runtime boundary, not specifically a Docker container.
3. Components — the major internal pieces inside one container and how they collaborate.
4. Code — the class- or module-level detail, usually only worth documenting for the trickiest areas.

Most architecture documents live happily at the context and container levels, dropping to component level only where the design is genuinely complex. You do not need to use C4 by name to use the idea: write the big picture first, then zoom in only as far as the reader actually needs.

Views: the same system from different angles

A single picture cannot answer every question, so it helps to describe the system through a few views, each answering one concern:

• A logical/structural view answers "what are the parts and how are they related?"
• A runtime/behavioural view answers "what happens when a request comes in?" — this is your data-flow section.
• A deployment view answers "what runs where?" — which is often where this document hands off to a dedicated deployment plan.

Keeping these views separate stops a single overloaded diagram from trying to say everything and saying nothing clearly.

Common mistakes to avoid

• Recording the what but not the why. Six months later nobody remembers why the queue is there; the rationale is the part that earns its keep.
• Only pictures, no prose. Diagrams drift out of date and exclude readers who cannot see them. Write the structure and flows in words.
• One mega-diagram. Trying to show context, containers, components, and deployment on one canvas produces something impressive and useless. Split by zoom level and by view.
• Documenting the org chart instead of the system. Describe components by responsibility, not by which team happens to own them this quarter.
• Hiding the trade-offs. Pretending a design has no downsides destroys trust. State what each decision cost, plainly.
• Letting it go stale. An architecture document that does not match reality is worse than none, because people trust it. Review it on a cadence and on every significant change.