Skip to main content
The system-architecture-document skill produces a System Architecture Document (SAD) — the definitive reference for how a software system is organized, why key architectural choices were made, and how the system connects to the world around it. It maps the full structural picture across multiple levels of abstraction using the C4 model and five architectural views, serving onboarding engineers, architects reviewing change impact, security auditors, and operators planning infrastructure changes.
At a glance

​
Best for

New system documentation

Documenting the architecture of a new system before implementation begins — establishing the structural blueprint teams build against.

Existing system archaeology

Producing architectural documentation for an existing system that lacks it, reflecting reality (including tech debt) rather than aspirations.

Compliance and security review

Preparing architecture documentation for a security or compliance review — trust boundaries, data flow, and threat model coverage included.

Senior engineer onboarding

Giving new senior engineers or architects a structured overview of how the system works and why it was built this way.

​
What it produces

The skill generates a 10–20 page SAD (excluding appendices) with these major artifacts:
  • Architecture principles — guiding principles that govern all decisions and act as tie-breakers during trade-offs
  • C4 model diagrams — System Context (Level 1), Container (Level 2), and Component (Level 3) in Mermaid
  • Process view — sequence diagrams for critical runtime flows including error paths
  • Deployment view — infrastructure topology with network tiers, regions, and managed services
  • Integration map — every external integration with protocol, auth, error handling, and SLA dependency
  • Data flow and trust boundaries — where data crosses trust zones, sensitive data classification
  • Security architecture — STRIDE threat model summary, security controls by trust zone, secrets management, network security
  • Disaster recovery — RPO/RTO targets, backup strategy, and failover procedure
  • Observability architecture — structured logging, metrics, distributed tracing, and alerting severity levels
  • Data architecture — schema overview, partitioning strategy, caching strategy, data lifecycle
  • API governance — versioning policy, rate limiting tiers, API gateway configuration
  • Cost model — monthly infrastructure cost breakdown with 10x and 100x scaling cost curves
  • Testing architecture — environment matrix, CI/CD pipeline gates, contract testing
  • Development view — code organization, module boundaries, dependency rules
  • Architecture Decision Record log — every significant architectural decision with full MADR-format entries
  • Known technical debt — deliberate compromises with remediation paths

​
How to invoke it

​
Example scenarios

  • “Document the system architecture for our payment gateway platform”
  • “Create a SAD for our new microservices-based notification system”
  • “I need a C4 diagram and architecture overview for our SaaS billing platform”

​
Key concepts

​
C4 model — four zoom levels

The C4 model (Simon Brown) provides a hierarchical approach to architecture documentation — like Google Maps with multiple zoom levels. All diagrams are produced in Mermaid for version control.
Audience: All stakeholders, including non-technical product leadership.Shows the system’s place in the world: who uses it and what external systems it depends on or serves.
Agents often produce a container diagram and stop. The C4 model requires multiple zoom levels. Skipping Level 1 forces non-technical stakeholders to read a technical diagram. Skipping Level 3 leaves developers without implementation guidance for complex containers.

​
Diagram model selection

The skill selects the diagramming approach based on team size and system complexity:

​
4+1 view model (Kruchten)

The SAD documents five complementary views of the same architecture:

​
Architecture Decision Records (ADRs) in the SAD

Every significant architectural decision must be recorded as an immutable ADR inline in the SAD. The document includes an ADR log summary table plus full MADR-format entries for each decision. ADR states follow the lifecycle: Proposed → Accepted → Deprecated → Superseded by ADR-XXX Each inline ADR captures: context, decision, alternatives considered (with pros/cons and rejection reason), and consequences (positive and negative). For standalone ADRs created outside the SAD, see the architecture-decision-record skill.

​
Security architecture

The SAD includes a dedicated security section with:
  • STRIDE threat model summary — key threat categories (Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, Elevation of Privilege) mapped to architectural controls
  • Security controls by trust zone — external (WAF, TLS termination), DMZ (auth enforcement, CORS), internal (service-to-service auth, parameterized queries), data (encryption at rest, access logging)
  • Secrets management — how secrets are stored, rotated, and accessed (never in code or config files)
  • Sensitive data classification — Restricted, Confidential, Internal, Public with storage and transmission requirements per category

​
Observability architecture

The SAD specifies the full observability stack before implementation:
  • Logging — structured JSON format, correlation IDs, log levels, aggregation pipeline, retention
  • Metrics — request rate, error rate, latency percentiles (p50/p95/p99), queue depth, DB connection pool utilization
  • Distributed tracing — W3C Trace Context or B3 propagation, sampling rate, trace storage
  • Alerting — severity levels P1 (Critical) through P4 (Info) with response time targets and escalation paths

​
Interview process

1

Context loading

Reads all existing .engineering-docs/ files. Extracts tech stack, team structure, existing constraints, and NFR targets from prior documents without re-asking.
2

Socratic clarification (max 2–3 questions)

Asks: (1) What are the estimated concurrent users, transaction throughput (TPS), or data storage scale targets? (2) What are the target uptime SLAs, disaster recovery goals (RPO/RTO), or multi-region requirements? Questions are tool calls with multiple-choice options.
3

System context (60 min)

Defines system boundaries, actors, external system dependencies. Produces Level 1 C4 diagram.
4

Container architecture (2 hrs)

Decomposes into deployable units. Produces Level 2 C4 diagram with technology choices for each container.
5

Component architecture (2–4 hrs)

Decomposes critical containers into major internal components. Produces Level 3 C4 diagrams for the most complex containers only.
6

Deployment view (90 min)

Maps containers to infrastructure. Documents network topology, tiers, regions, and external managed services.
7

Integration and data flow (60 min)

Maps all integration points. Documents data flow, trust boundaries, and sensitive data classification.
8

NFR and quality attributes (60 min)

Documents architectural decisions driven by performance, scalability, security, and reliability NFRs with measurable targets.
9

ADR log (60 min per ADR)

Documents each significant architectural decision with full MADR-format content and alternatives considered.

​
Output structure

System purpose, architectural style (monolith, microservices, event-driven, layered), the key NFR drivers that shaped the architecture, and the most important decisions made.
Guiding principles that govern all decisions — for example: “Simplicity over sophistication,” “Explicit over implicit,” “Data integrity over performance.” Each with rationale and practical implication.
Mermaid C4Context diagram. External system dependencies table with direction, protocol, purpose, and SLA dependency flag.
Mermaid C4Container diagram. Container inventory with technology, responsibility, and scalability strategy.
Mermaid C4Component diagrams for critical containers. Not required for every container.
Mermaid graph showing web tier, application tier, and data tier with network zones. Infrastructure inventory table with component type, specs, count, region, and ownership.
Mermaid sequence diagrams for critical runtime flows (e.g., payment processing, webhook delivery). Error paths documented, not just happy paths.
Every integration with direction, protocol, auth method, data format, error handling strategy, and SLA.
Mermaid diagram showing data movement across trust zones. Sensitive data classification table: category, classification level, storage controls, transmission controls, retention.
STRIDE threat model summary, security controls by trust zone, secrets management table, network security specification.
RPO/RTO targets, backup strategy per component (frequency, retention, encryption), failover procedure with numbered steps, DR testing schedule.
Logging spec, metrics collection table, distributed tracing configuration, alerting severity matrix with escalation paths.
Schema overview, partitioning strategy per large table, caching strategy (what is cached, TTL, invalidation), data lifecycle per category.
Versioning policy, deprecation headers, rate limiting tiers, API gateway responsibilities.
Monthly cost per component. Scaling cost curve at 1x/10x/100x traffic with key cost drivers.
Environment matrix (local/CI/staging/production), CI/CD pipeline gates, contract testing coverage.
Repository structure (monorepo vs polyrepo), module boundaries, dependency rules.
ADR log summary table. Full MADR-format entries for each decision: context, decision, alternatives considered with rejection reasons, consequences (positive and negative). Use the standalone architecture-decision-record skill for decisions created ad-hoc.
Table mapping each quality attribute (availability, performance, security, scalability, maintainability) to its measurable target, the architectural decision that satisfies it, and the ADR reference.
At least two rejected architectural alternatives with pros, cons, and specific rejection reasons — preventing future engineers from re-investigating already-evaluated paths.
Deliberate architectural compromises: what, why accepted, remediation path, priority level.

​
Handoff

Reads from:
  • technical-specification — functional and non-functional requirements that drive architectural decisions
  • technical-feasibility-study — technology constraints, integration feasibility, risk mitigations
  • 2-project-plan — delivery timeline, team structure, dependencies
  • ux-flow-specification — frontend component structure and API interaction points
Feeds into:
  • Implementation — architectural structure guiding code organization and module boundaries
  • infrastructure-specification — deployment topology, scaling strategy, monitoring needs
  • Security review — trust boundaries, data flow, and threat model foundation

​
Quality gate

Before marking the document final, verify:
  • C4 diagrams exist at Level 1 (System Context) and Level 2 (Container), with Level 3 (Component) for critical containers
  • The Alternatives Considered table documents at least two rejected alternatives with specific, evidence-based reasoning
  • Trust boundaries and data flow are explicitly mapped with sensitive data classification
  • Every significant architectural decision has a corresponding ADR in the log
  • Non-functional requirements have measurable targets linked to architectural decisions