Software Architecture

---
name: software-architecture
description: >-
  Designs the software architecture for a new application, service, or major
  feature through a structured interview, then produces an architecture
  document (arc42-style, with C4 diagrams in Mermaid and Architecture Decision
  Records). Use this whenever the user is starting a greenfield system or a
  significant new feature and would benefit from thinking through structure,
  quality attributes, tech stack, and trade-offs before writing code. Trigger
  on phrases like "design the architecture for", "I'm building a new app",
  "help me architect", "set up a new project/service", "what should the
  architecture be", "create an architecture doc/diagram", or any greenfield
  system-design discussion — even when the user does not say the word
  "architecture" explicitly but is clearly about to start building something
  new. If an SRS (docs/srs.md) exists, it designs from those requirements and
  NFRs, interviewing only for gaps. Prefer this skill over answering from memory
  whenever real architectural trade-offs are in play.
---

# Software Architecture

This skill turns a vague "I want to build X" into a grounded architecture: it
**elicits the things that actually drive architectural decisions**, then
produces a right-sized architecture document with C4 diagrams and decision
records that capture the *why*, not just the *what*.

The single most important idea: **architecture is driven by quality attributes
and constraints, not by technology.** A junior approach jumps straight to "use
Next.js + Postgres on AWS." A senior approach first asks "how many users, how
much can it be down, how consistent must the data be, what's the team, what's
the lock-in tolerance" — and *derives* the stack from the answers. This skill
enforces that order: **understand → decide → document.**

## Input

This skill consumes the requirements artifacts produced upstream, when they
exist.

- **SRS (primary)** — if the user provides a path, use it; **otherwise default to
  `docs/srs.md`.** When found, it is the primary source: read the requirements and
  NFRs and design against them, shrinking the interview to confirmation plus the
  architecture-specific gaps (see Phase 1).
- **Use cases (secondary)** — default `docs/use-cases.md`. When found, read it to
  inform the **runtime view** (each significant use case becomes a runtime
  scenario / sequence diagram) and the **resilience and security** decisions (the
  exception/alternate flows reveal failure-handling needs; the actor-to-use-case
  mapping reveals trust boundaries). It refines *how* the design realizes the
  requirements; it does not replace the SRS as the driver of *what*.
- **RTM** — not consumed as input (it re-indexes the SRS and use cases without
  adding information), but **written back to at delivery**: this skill fills the
  Design ref column for the requirements its ADRs address (see Phase 5).
- **If no SRS is found**, fall back gracefully to the full elicitation interview
  (all seven rounds in `references/elicitation-guide.md`) — the skill stays fully
  usable standalone, for quick architecture work without a prior requirements
  phase.

**Source-gated traceability (one rule, applied per source).** Cite an ID only
when the document that defines it is present: SRS requirement IDs when `srs.md`
exists, use-case IDs when `use-cases.md` exists. When a source is absent, state
the driver in plain prose instead — **never fabricate an ID.** In the common
cases both documents are present (full pipeline) or neither is (standalone
fallback, prose drivers throughout); the rule handles any mix automatically.

The boundary: the SRS states *what* (requirements); architecture still decides
*how* (technology stack, data stores, deployment). Read any *mandated* technology
from the SRS constraints section, but the stack is otherwise an architecture
decision.

## Workflow

Follow these phases in order. Do not skip straight to a document — designing from
unconfirmed assumptions is the failure mode this skill exists to prevent.

### Phase 1 — Ingest the requirements, then elicit the gaps

1. **Ingest.** Read `docs/srs.md` (per **Input**). Extract the architecture-
   relevant content: purpose and scope (§1.2), product perspective and system
   boundary (§2.1), user classes (§2.3), the functional requirements and their
   capability areas (§3.1, which become candidate building blocks), the external
   interfaces (§3.2), the constraints (§2.5), and — most importantly — the
   **non-functional requirements (§3.3), which are the architecture drivers**.
   Note each NFR's ID; you'll cite them in decisions and ADRs.

   Then read `docs/use-cases.md` if present: note the significant use cases (they
   become runtime scenarios), and scan the **exception/alternate flows** for
   resilience requirements (e.g., "processor unavailable → queue and retry"
   implies an async boundary) and the **actors** for trust/authorization
   boundaries. Keep each use case's ID for the runtime view.

   If no SRS exists, skip to running the full interview in
   `references/elicitation-guide.md`, then continue at Phase 2.

2. **Play back the drivers.** Summarize the top quality attributes (by NFR ID),
   the hard constraints, and the capability areas you'll design toward, and get a
   quick nod. Trust the SRS — this is a confirmation, not a re-interview. Flag any
   architecture-driving NFR that's missing or vague (e.g., no concrete
   scalability target); ask about the few that would change the design, and
   assume-and-note the rest.

3. **Interview only the gaps.** Read `references/elicitation-guide.md` and ask
   only what the SRS doesn't answer — technology preferences and any mandated
   stack, lock-in tolerance, team skills, data-store-relevant access patterns,
   and the deployment/cloud target. Same technique throughout: batch related
   questions, infer aggressively and state inferences, offer one-word-acceptable
   defaults. Keep it short — most of the picture is already in the SRS.

### Phase 2 — Decide

Derive the architecture from what you learned. Read
`references/decision-guide.md` for how to reason about the recurring forks
(monolith vs services, sync vs async, SQL vs NoSQL, serverless vs containers,
vendor-managed vs portable). For each significant fork, **record what drives it,
source-gated**: cite SRS requirement IDs when `srs.md` exists (e.g., a scaling
fork driven by NFR-SCAL-001), cite use-case IDs where an exception flow or actor
boundary drove a resilience/security fork (e.g., UC-007), and when neither source
document exists, state the driver in plain prose ("driven by: peak load ~5k
concurrent users") — never invent an ID. This is what makes the decision
traceable and lets a later requirements change point back to the architecture it
affects. You will write an ADR per fork in Phase 4, so note the options you
weighed and *why* you chose. Resist the urge to over-engineer: the right
architecture for most new apps is simpler than the architecture people reach for.

### Phase 3 — Document and diagram

1. Read `references/document-template.md` and write the architecture document.
   **Right-size it** — the template marks which sections are essential and which
   scale with complexity. A small app gets a tight doc; a distributed system
   gets the full treatment.

2. Read `references/diagram-guide.md` and produce the diagrams as **Mermaid
   embedded directly in the document**, so the whole thing is one portable
   artifact. At minimum produce a **System Context** diagram and a **Container**
   diagram (the two C4 levels that earn their keep almost every time). Add a
   sequence diagram for the most important runtime flow — when `use-cases.md`
   exists, the significant use cases are the natural choice for these runtime
   scenarios; cite their UC IDs — and a deployment diagram when the
   infrastructure is non-trivial.

### Phase 4 — Capture decisions

Read `references/adr-template.md` and write one ADR per significant decision
from Phase 2. ADRs are what separate a real architecture from a tech-stack list:
they record the context, the options, the choice, and the consequences, so that
six months later nobody has to reverse-engineer why the system is the way it is.
Each ADR's **"Requirements addressed"** field is source-gated: cite SRS IDs (and
any use-case IDs) the decision addresses when those documents exist, otherwise
state the driver in prose — never fabricate an ID. With a real SRS this gives
requirement → decision traceability both ways. Embed the ADRs in the document's
"Architecture Decisions" section (or as separate files under `docs/adr/` if the
user prefers — ask).

### Phase 5 — Deliver

Save the document to the repo (default `docs/architecture.md`, or wherever the
user wants).

**RTM write-back** (if `docs/rtm.md` exists; skip silently otherwise): fill the
**Design ref** column for the requirements this architecture designed, per the
layer rule — for **NFR rows**, the ADR(s) addressing them (an NFR's design *is*
usually its ADR); for **FR rows**, an ADR ref **only** when that ADR's
"Requirements addressed" field cites the FR (a genuine design response, not a
mention — concrete per-slice refs come later from detailed-design). **Append
into cells, never overwrite** other entries, and touch no other column — rows
and requirement columns belong to requirements-engineering, Plan ref to
planning, Test ref to testing.

Summarize the key decisions and the main risks in a few sentences in chat, and
point to the diagrams. Offer concrete next steps: a `.docx` export for
stakeholders, a deeper dive on any one decision, or scaffolding the initial
project structure to match the architecture.

## Output format

Default to a single Markdown file with embedded Mermaid diagrams and inline
ADRs. This is repo-native, diff-able, and renders on GitHub. Switch formats only
when asked:
- **Word document** (`.docx`) — when the deliverable is for non-technical
  stakeholders. Use the `docx` skill for this.
- **Separate ADR files** — when the user wants a growing `docs/adr/` log over
  the life of the project.

## What good looks like

- Every major technology choice traces back to a requirement or constraint the
  user actually stated — never "because it's popular."
- The document is right-sized: no 40-page treatise for a CRUD app, no one-pager
  for a payment platform.
- Diagrams render on the first try (see the reliability notes in the diagram
  guide — prefer `flowchart`/`graph` with subgraphs over experimental C4 syntax
  when portability matters).
- Trade-offs are named honestly, including the downsides of the chosen path.
- A new engineer could read it and understand both how the system is shaped and
  why.