Authoring Architecture Docs Action

Produces architecture decision records, design documents, and C4 Model diagrams scoped to the appropriate level for the current SDLC phase and audience — the understanding-oriented quadrant of the Diátaxis framework. Diagrams are scoped to the appropriate level for the current SDLC phase and audience.

Load authoring-technical-docs first for the multi-pass workflow, style rules, and quality framework. This action provides the templates and architecture-specific rules.

References

Read these before executing any step.

File Contains

references/notation.md

C4 abstractions, Mermaid element types, verb bank

references/level-rules.md

Per-level rules and forbidden elements

references/sdlc-mapping.md

SDLC phase → diagram selection, audience decision tree

references/anti-patterns.md

Mistakes to detect and avoid

Assets

Use these as output scaffolding.

File Use for

assets/architecture-doc.md

Top-level ARCHITECTURE.md structure

assets/diagram-templates.md

Per-level section templates (fill in placeholders)

assets/Architecture_Decision_Record_(ADR)_template.md

Template for Architecture Decision Records (ADRs)

assets/Design_document_template.md

Template for technical design documents

assets/System_architecture_template.md

Template for system architecture overviews

Workflow

Step 1 — Read references

Read all four files in references/ before any other action.

Step 2 — Gather project context

Extract from input. Ask only if a required field is missing.

Field Required for

System name and purpose All levels

Users / personas L1+

External integrations L1+

Tech stack L2+

SDLC phase Selecting diagram levels

Target container name + source structure L3 only

Flow name and step-by-step description Dynamic only

Step 3 — Select diagram levels

Consult references/sdlc-mapping.md → Phase Matrix and Audience Decision Tree. State the selection and rationale before proceeding.

Step 4 — Produce each diagram

For each selected level, in order:

• Open assets/diagram-templates.md and copy the matching template section

• Fill every {{placeholder}} — leave none blank

• Apply all rules from references/level-rules.md for that level

• Scan output against references/anti-patterns.md

• Self-check against the Review Checklist in assets/architecture-doc.md

Step 5 — Assemble output document

Open assets/architecture-doc.md as the document scaffold. Insert completed diagram sections in level order: L1 → L2 → L3 → Deployment → Dynamic. Complete the Key Architectural Decisions table and Change Log.

Step 6 — Save files

docs/architecture/ARCHITECTURE.md docs/architecture/diagrams/context.mermaid docs/architecture/diagrams/container.mermaid docs/architecture/diagrams/component-{{container_name}}.mermaid docs/architecture/diagrams/deployment.mermaid docs/architecture/diagrams/dynamic-{{flow_name}}.mermaid

Save only the files corresponding to the levels actually produced.

Inputs

• Project description, README, or source code

• SDLC phase (required)

• Target container name and source structure (L3 only)

• Flow name and steps (Dynamic only)

Outputs

• ARCHITECTURE.md — full assembled documentation package

• diagrams/*.mermaid — one file per diagram level produced

Architecture docs rules

• Separate "what is" from "what should be." Overviews describe current state. Design docs describe proposed future.

• Diagrams are not optional. Use Mermaid — it's version-controllable.

• Include the "why." Link to ADRs.

• Write for the new team member.

• Be honest about trade-offs. Every architecture has weaknesses. Document them.

• Link to code. When describing a component, link to the relevant repo or entry point.

Using Mermaid for diagrams

Accompany each diagram with a brief prose summary (2–4 sentences) explaining the key relationships shown.

System overview:

graph TB User[User] --> WebApp[Web Application] WebApp --> API[API Service] API --> DB[(Database)] API --> Queue[Message Queue] Queue --> Worker[Background Worker] Worker --> DB

Sequence diagram:

sequenceDiagram participant Client participant API participant DB Client->>API: POST /resources API->>DB: INSERT resource DB-->>API: resource_id API-->>Client: 201 Created

Example Triggers

• "Generate a C4 context diagram for this project"

• "Show me the container architecture"

• "Document the components in the auth service"

• "Create a class diagram for the payment module"