# System Architecture Specification

Turns a scope and its measured requirements into an architecture someone can build from — with every component traced to a requirement and every decision carrying the alternatives it beat.

## Deliverable

One Markdown document, `architecture-specification.md`, in the structure set out under **Output** below. It takes the output of **Non-Functional Requirements Definition** and feeds **API Contract Design** and **Data Model & Migration Plan**.

## Required inputs

- **The scope** — the capabilities the system must provide, as a list. A scope definition is the expected form; any list of separately describable capabilities will do.
- **The non-functional requirements** — the measured constraints the design must satisfy, each with its metric and the condition it holds under.
- **A named decision owner** — the person who can accept an architectural decision and the alternatives it rejects. Without one, the decisions section is a suggestion.

If the scope is absent, stop and report it. Never derive the scope from an existing system: a running system records what was built and what was abandoned halfway, and neither is a requirement.

## Optional inputs

- Access to the existing system: repositories, schemas, configuration, operational documentation
- The operating environment and its constraints: isolation rules, regions, network boundaries, hosting model
- The conventions the team already follows and the systems it already runs
- Integration points outside the boundary, and who owns each of them
- Compliance, residency or retention obligations that apply to the data
- Earlier architecture documents for the same system, and what has changed since

Every optional input that is absent becomes an entry under **Open questions**. It never becomes a guess. Where the operating environment was not supplied, the deployment shape is described in runtime units and its placement is recorded `unknown`.

## Execution

**1 — Fix the boundary.** Name the system, what is inside it and what is outside. List every external actor — people, systems, scheduled processes — and what each one wants from the system. Anything that cannot be placed on one side is a boundary question, recorded as one rather than decided quietly.

**2 — Derive the components from the capabilities.** For each capability in the scope, name the component that owns it. Give each component one sentence of what it owns and one of what it explicitly does not. Two components that own the same thing are one component with an unresolved name; a component that owns nothing is deleted.

**3 — Define the interfaces.** For every pair of components that must communicate: the direction, what is exchanged, whether the call is synchronous or asynchronous, and what the caller does when the far side is unavailable. Interfaces are named and bounded here; they are specified field by field by **API Contract Design**.

**4 — Name the data that crosses each boundary.** For each interface and each external actor: what data crosses, its classification, who owns it, and how long it may be kept. Data whose classification was not supplied is recorded `unknown` and raised as a question; it is never assigned a classification by this skill.

**5 — Shape the deployment.** The runtime units, how many of each, what state each holds, how each is reached, and where the boundaries of failure lie. Build this from the stated environment only. Where none was stated, describe the units and their relationships and mark their placement `unknown`.

**6 — Record the decisions.** For every choice that is expensive to reverse: what was decided, what forced it, the alternatives considered and why each was rejected, and the condition that would reverse it. A decision with no rejected alternative was not a decision; it was the first idea, and it is recorded as one.

**7 — Trace and prune.** Every component must trace to a capability or to a non-functional requirement. A component that traces to nothing is flagged in the traceability section, not kept on the diagram. Every capability must reach at least one component; a capability that reaches none is a gap and is raised as blocking.

## Output

`architecture-specification.md`, in this order:

- **1. Input and date** — which scope and which requirement set this specification is built from, who supplied each, and when
- **2. System context** — the system, its external actors, and what each exchanges with it
- **3. Components** — per component: name, what it owns, what it explicitly does not own, and what it traces to
- **4. Interfaces** — per interface: the two sides, direction, what is exchanged, synchronous or asynchronous, and the behaviour when the far side is unavailable
- **5. Data across boundaries** — per boundary: the data, its classification, its owner, and its retention
- **6. Deployment shape** — runtime units, their multiplicity, the state each holds, how each is reached, and the failure boundaries
- **7. Architectural decisions** — the decision, what forced it, the alternatives rejected and why, and what would reverse it
- **8. Traceability** — component to requirement and requirement to component, with the unmatched entries on both sides listed
- **9. Open questions** — the question, what it blocks, who can answer it

## Validation

The specification is ready when all of these hold:

- Every component in section 3 traces to a capability or a requirement in section 8, or is flagged there as tracing to nothing
- Every capability in the input scope reaches at least one component
- Every interface in section 4 states what the caller does when the far side is unavailable
- Every decision in section 7 names at least one rejected alternative and the reason it was rejected
- Every item in section 5 carries a classification or the literal `unknown`
- Section 9 is either non-empty or states explicitly that nothing is outstanding

Fail the run if a component traces to nothing and is not flagged, or if a decision is recorded with no alternative considered.

## Failure handling

- **No scope supplied** — stop. Report that the specification has no capabilities to allocate, and that a component list assembled without them describes a preference rather than a system.
- **No non-functional requirements** — produce sections 1 to 5 and 7 to 9, mark section 6 `UNCONSTRAINED`, and state that a deployment shape resting on no stated load, availability or latency requirement may not be used to size anything.
- **No access to the existing system** — build sections 2 and 3 from the reported material alone, mark every element `reported`, and state plainly that nothing was verified against a running system.
- **Contradictory inputs** — record both, name both sources, and raise the contradiction in section 9 as blocking. Do not resolve it by choosing.
- **Partial material** — produce every section the material supports, mark the rest `INCOMPLETE — pending <question>`, and deliver. A specification honest about its gaps can be reviewed; a complete-looking one that filled them cannot.