Technical System Architecture: [System name]

Owner: [Name / team] Status: [Draft / Reviewed / Approved] Last reviewed: [Date] Related documents: [Links to data model, integration spec, deployment plan]

---

1. Overview and goals

[In a short paragraph, state what this system does and who it serves. Then list the quality goals that shape the architecture — the things this design is deliberately optimised for.]

• Primary goal: [e.g., serve customer-facing traffic with sub-300ms responses]
• Quality goals (in priority order): [e.g., availability, then maintainability, then cost]
• Explicit non-goals: [What this system is deliberately NOT trying to do]

2. Context and system boundary

[Describe, in prose, the system as a single unit. Who and what sits outside the boundary, and how do they interact with it? Name each external actor and dependency and the direction of the relationship.]

• Users / actors: [Who uses the system and what they do with it]
• Upstream dependencies (the system calls out to): [External services it relies on]
• Downstream consumers (things that call the system): [Other systems that depend on it]
• Out of scope: [Anything inside the wider product that this document does not cover]

3. Components

[List the major building blocks. Each row names a component, states the single responsibility it owns, and notes the technology it is built with. A reader should be able to find the owner of any behaviour here.]

Component	Responsibility	Tech
[Web client]	[What it is accountable for]	[Framework / language]
[API service]	[What it is accountable for]	[Framework / language]
[Primary datastore]	[What it stores and serves]	[Database]
[Background worker]	[What it processes asynchronously]	[Runtime / language]
[Message queue / bus]	[What it decouples]	[Technology]

4. Key data flows

[Walk the reader through the most important paths through the system as numbered steps. Describe the flow in words — what enters, what each component does, what is persisted, what is returned.]

Flow A — [name, e.g., "user submits a request"]:

1. [The actor does X, which arrives at component Y over which protocol.]
2. [Component Y validates / authenticates and then does Z.]
3. [Data is read from / written to which store.]
4. [An event is published / a response is returned to the actor.]

Flow B — [name, e.g., "asynchronous processing"]:

1. [What triggers the flow and where the work is enqueued.]
2. [Which component picks it up and what it does.]
3. [What the end state is and how the actor learns about it.]

5. Technology choices and rationale

[For each significant choice, name the technology, the main alternatives considered, and the reason for the decision. This is the section future readers will thank you for.]

• [Layer, e.g., API framework]: chose [X] over [Y] because [reason tied to a quality goal].
• [Layer, e.g., primary database]: chose [X] over [Y] because [reason].
• [Layer, e.g., hosting / platform]: chose [X] over [Y] because [reason].

6. Scalability and reliability

Scalability

• [Which components scale horizontally, and what triggers scaling.]
• [The known bottleneck and the plan for when it is reached.]

Reliability

• Failure handling: [Timeouts, retries, circuit breakers, idempotency.]
• Redundancy: [What is replicated or run in multiple instances.]
• Degradation: [What the system does when a dependency is down — fail open, fail closed, queue, etc.]
• Targets: [Availability target / SLO, recovery objectives — or a link to the disaster-recovery plan.]

7. Security

• Authentication: [How users and services prove who they are.]
• Authorisation: [How access is decided once identity is known.]
• Secrets and data: [Where secrets live, what data is sensitive, and how it is protected in transit and at rest.]
• Trust boundaries: [Where the system stops trusting input and starts validating it.]

8. Key risks and trade-offs

[State the decisions that bought one quality at the cost of another, honestly. Each row should make the cost explicit so a future reader understands the deal that was struck.]

Decision	What it buys	What it costs	Mitigation
[Decision 1]	[Benefit]	[Cost / risk]	[How the cost is managed]
[Decision 2]	[Benefit]	[Cost / risk]	[How the cost is managed]