Architecture-as-Code

Manage software architecture artefacts as code — ADRs, C4 diagrams, and slide decks — all in Git, all reviewable via pull request, all AI-assisted.

---

Why Architecture-as-Code?

Traditional Approach	Architecture-as-Code
Decisions made in meetings, never written down	Every decision captured in an ADR with full rationale
Diagrams in shared drives, outdated within weeks	Diagrams in Git, updated alongside the code
New engineers spend days getting context	Structured onboarding path from the repository itself
Architecture review happens informally	PR-based review with inline comments
AI assistant can't access the documentation	Claude reads and writes all artefacts natively

---

Quick Start

git clone <this-repo>
cd Architecture-as-Code
./init.sh

Then open Claude Code and use the slash commands:

/new-adr           # Document an architecture decision
/new-diagram       # Create a C4 diagram
/create-slides     # Generate a presentation deck
/review-architecture  # Audit your architecture docs
/document-system   # Generate system overview & onboarding guide

---

Repository Structure

Architecture-as-Code/
├── architecture/              # C4 diagrams and structural documentation
│   ├── system-context.md      # Level 1: System Context (start here)
│   ├── containers/            # Level 2: Container diagrams
│   └── components/            # Level 3: Component diagrams
├── docs/adrs/                 # Architecture Decision Records
│   ├── README.md              # Auto-generated ADR index
│   └── 0001-*.md              # Sequential ADRs
├── slides/                    # Marp presentation decks
├── templates/                 # Templates for ADRs, diagrams, and slides
│   ├── adr/NNNN-template.md
│   ├── diagrams/              # C4 Context, Container, Component, Sequence
│   └── slides/                # Architecture Overview, ADR Presentation
├── scripts/                   # Automation scripts
├── CLAUDE.md                  # Claude project conventions (read by Claude automatically)
└── init.sh                    # One-command bootstrap

---

Slash Commands

Command	Description
/new-adr	Create the next ADR with proper numbering and index update
/new-diagram	Create a Mermaid C4 diagram (Context / Container / Component / Sequence)
/create-slides	Generate a Marp slide deck from ADRs or architecture diagrams
/review-architecture	Audit all artefacts for gaps, inconsistencies, and missing documentation
/document-system	Generate a system overview and optional onboarding guide

---

Automation Scripts

Script	Usage	Description
init.sh	./init.sh	Bootstrap: create directories, install Marp, make scripts executable
scripts/new-adr.sh	./scripts/new-adr.sh <title>	Create next ADR from template
scripts/export-slides.sh	./scripts/export-slides.sh [deck.md]	Export slide decks to export/*.pdf and export/*.html
scripts/generate-index.sh	./scripts/generate-index.sh	Regenerate docs/adrs/README.md from frontmatter
scripts/validate.sh	./scripts/validate.sh	Validate ADR format and slide frontmatter (CI-ready, exit 1 on errors)

---

Example Workflow

Scenario: Your team decides to use GraphQL for the API layer.

# 1. Document the decision
./scripts/new-adr.sh use-graphql-for-api
# → creates docs/adrs/0002-use-graphql-for-api.md

# 2. Fill in the ADR — or ask Claude:
#    /new-adr
#    "We decided to use GraphQL for our API because..."

# 3. Update the container diagram to reflect the new API type
#    /new-diagram → Container level

# 4. Regenerate the index
./scripts/generate-index.sh

# 5. Create a slide deck for the team meeting
#    /create-slides → ADR Presentation

# 6. Export to PDF
./scripts/export-slides.sh slides/adr-0002-graphql.md

# 7. Open a PR — the team reviews the ADR and diagram together

---

Live Architecture Diagram

C4Context
  title System Context — [Your System Here]

  Person(user, "End User", "Uses the system to achieve their goal")
  Person(admin, "Administrator", "Manages the system")

  System(system, "[Your System]", "Delivers value to users")

  System_Ext(ext1, "External System", "Provides data or services")

  Rel(user, system, "Uses", "HTTPS")
  Rel(admin, system, "Administers", "HTTPS")
  Rel(system, ext1, "Integrates with", "REST / HTTPS")

Loading

Replace the placeholders above with your actual system. Use /new-diagram to generate a real diagram from a description.

---

Technology Stack

Concern	Tool	Why
Diagrams	Mermaid	Native GitHub rendering, no server required
Architecture model	C4 Model via Mermaid C4	Industry standard, Claude-native
Slides	Marp	Markdown-native, PDF/HTML export
ADR format	Nygard Extended	Widely adopted, proven structure
Scripting	Bash	Zero dependencies, runs everywhere
AI assistant	Claude Code	Reads and writes all formats natively

---

Prerequisites

Tool	Minimum Version	Required For
Git	2.x	Everything
Node.js	18+	Marp slide export
npm	8+	Marp installation
Claude Code	Latest	Slash commands

Marp CLI is installed automatically by ./init.sh:

npm install -g @marp-team/marp-cli

---

ADR Format

All ADRs follow the Nygard extended format with YAML frontmatter:

---
id: "0001"
title: "Use Architecture-as-Code"
date: "2026-07-10"
status: "Accepted"
deciders: ["Architecture Guild"]
tags: ["process", "tooling"]
---

Required sections: Status · Context · Decision Drivers · Considered Options · Decision Outcome · Consequences · Pros and Cons of the Options

See templates/adr/NNNN-template.md for the full template.

---

License

MIT — see LICENSE.