In this guide (17 items)
Architecture Document Spec
Architecture Document Guideline
FOR ALL AI AGENTS: This guideline defines the standard structure, content depth, and visual conventions for a professional software architect deliverable — a single HTML document with embedded Mermaid diagrams that serves as the source of truth for an entire platform’s architecture.
Document Version: 1.0 Last Updated: 2026-05-12 Audience: Architects, senior engineers, security, ops, compliance.
1. Purpose
A platform architecture document is the executive contract between engineering, security, compliance, and business. It must:
- Explain what the platform does and for whom.
- Document decisions with rationale (ADRs).
- Visualize structure at multiple zoom levels (C4 Levels 1–3).
- Map business domains to bounded contexts (DDD context map).
- Catalog events that cross service boundaries.
- Model threats explicitly (STRIDE).
- Track risks with owners and mitigations.
- Specify NFRs and SLOs measurably.
- Plan roadmap with dates.
- Be printable, versioned, and signable.
2. Mandatory sections (in this order)
| # | Section | Required content |
|---|---|---|
| 01 | Executive Summary | Business context, doc objectives, architectural KPIs (availability, latency, RTO/RPO, coverage) |
| 02 | Functional & NFR | RF table by service, NFR table with measurable targets, prioritized use cases |
| 03 | Compliance Framework | Local regulation, international standards, control → architecture mapping |
| 04 | ADRs | One block per decision: Context · Decision · Alternatives · Consequences. Accepted ADRs are immutable. |
| 05 | C4 L1 Context | System and its environment (people + external systems) |
| 06 | C4 L2 Containers | Deployable units, protocols, data stores |
| 07 | C4 L3 Components | At least one service decomposed; catalog per service |
| 08 | DDD Context Map | Bounded contexts classified (core / supporting / generic), inter-context patterns (ACL, OHS, Published Language), ubiquitous language excerpt |
| 09 | Hexagonal Model | Layers, dependency rule, package structure |
| 10 | Infrastructure | Topology, networking, compute, storage |
| 11 | Integration Patterns | Patterns applied + dynamic views (sequence diagrams) for critical flows |
| 12 | Event Catalog | Broker topology, event inventory with producer/consumer/payload, schema policy |
| 13 | Security End-to-End | Defense in depth, encryption, IAM |
| 14 | Threat Model (STRIDE) | Assets, attack surface, STRIDE matrix, prioritized mitigations |
| 15 | Observability & CI/CD | Pipeline (DevSecOps), three pillars + SLO |
| 16 | HA & DR | Strategy, RTO/RPO per resource, auto-healing |
| 17 | Testing Strategy | Pyramid, levels with tech, coverage gates |
| 18 | Cost Estimation | Volumetrics, monthly costs, optimization levers |
| 19 | Risk Register | Top N risks with prob × impact × score × owner × mitigation; governance |
| 20 | Roadmap | Gantt or table; 12–24 month horizon |
| 21 | Glossary & References | Terms + sign-off block |
3. Format and tooling
3.1 Delivery format
- Single HTML file (standalone). No external assets required.
- Mermaid as the diagramming language — rendered client-side via CDN.
- Print-friendly CSS — must produce a coherent PDF via browser
Cmd+P.
3.2 Why Mermaid over PNG
- Diagrams stay editable in the doc itself; no asset drift.
- Renders crisp at any zoom level.
- Reviewable as text in PR.
- Falls back to
<pre>if JS disabled.
3.3 Diagram types per section
| Section | Diagram type |
|---|---|
| C4 L1, L2, L3 | flowchart with subgraphs + custom classDef |
| Integration sequences | sequenceDiagram with autonumber |
| Hexagonal layers | flowchart LR with subgraphs for driving/driven sides |
| Infrastructure | flowchart TB with VPC/AZ subgraphs |
| Threat model summary | flowchart with defense-in-depth layers |
| DevSecOps pipeline | flowchart LR linear |
| Roadmap | gantt |
| Risk matrix | quadrantChart |
| Event catalog topology | flowchart with exchanges + queues + DLX |
3.4 Visual palette (must match C4 conventions)
| Element | Color | Hex |
|---|---|---|
| Person | Dark blue | #08427b |
| Software System | Primary blue | #1168bd |
| External | Gray | #999999 |
| Container | Medium blue | #3498db |
| Component | Light blue | #85bbf0 |
| Entry Point | Green | #2ecc71 |
| Application | Medium blue | #3498db |
| Domain | Red | #e74c3c |
| Driven Adapter | Orange | #f39c12 |
| Database | Pink | #f5b7b1 |
4. Authoring rules
4.1 Section style
- Lead-in paragraph under every
h2: one or two sentences explaining what the reader will get from the section. Italicized, serif font. - Tables before prose for catalogs (ADRs, events, risks, RF/NFR).
- No long prose paragraphs. Prefer short paragraphs + lists.
- Spanish or English consistent throughout. The team’s working language wins.
4.2 Content depth
- ADRs: minimum 4 fields (Context, Decision, Alternatives, Consequences).
Each ADR has an immutable ID (
ADR-001…) and a status. - Event Catalog: every event must show producer, routing key, consumers, payload summary. Schema policy documented once.
- STRIDE: per-asset row including category tag (
S/T/R/I/D/E) and named mitigation. No generic “input validation” — must be specific. - Risk register: every risk has an owner and a mitigation in progress with a date or status. No risk without owner.
4.3 What never goes in the doc
- Implementation code (link to the repo).
- Step-by-step runbooks (link to runbook repo).
- Sensitive credentials, IPs, or hostnames (use placeholders).
- Decisions that haven’t been made (capture as ADR draft separately).
5. Lifecycle
5.1 Version control
- Document lives next to the codebase:
global-architecture/platform-architecture.html(or equivalent path per project). - Increment version on every published change:
0.xfor drafts,1.0+for approved baselines. - Maintain a document control table (version, date, author, changes) inside the cover section.
5.2 Approval
- Final version must include a sign-off block with slots for: Lead Architect · CISO · Head of Engineering · CTO (adapt to org structure).
- Sign-off captured outside the HTML (PDF + signatures or wet-ink).
5.3 Review cadence
- Quarterly review by the Architecture Committee.
- Annual full-doc refresh; minor updates with version bump.
- Risk register revisited monthly; STRIDE revisited per major release.
6. Reusable skeleton
A working reference document exists at:
{repo}/global-architecture/platform-architecture.html
Clone it as the starting point for new platforms. Replace:
- Brand identifiers and titles.
- KPI values to match the new project’s commitments.
- ADRs to reflect actual decisions.
- Diagrams to mirror the new system’s services and flows.
- Catalog tables (events, risks, RF/NFR) with the new data.
A command exists to scaffold this: /arch-doc (see
commands/arch-doc.md). Use it instead of copying by hand.
7. Related skills and guidelines
skills/software-architect/SKILL.md— when to author or update this doc.guidelines/adr.md— ADR authoring rules.guidelines/ddd.md— bounded context and ubiquitous language.guidelines/diagrams.md— diagram catalog and Structurizr DSL workflow.guidelines/hexagonal-architecture.md— hexagonal architecture rules.guidelines/observability.md— three pillars and SLO definitions.