Architecture as Code

C4 diagrams generated from source code, updated on every commit. PlantUML and Mermaid rendered in CI/CD and deployed to GitHub Pages.

Why Architecture as Code?

Diagrams live in your codebase, version-controlled and auto-generated. They evolve with your system instead of rotting in outdated PowerPoints.

- Updated on every commit - npm run docs:arch regenerates C4 diagrams from source
- Version controlled - Track architecture changes in Git, see diffs in PRs
- Reviewed like code - Architecture changes go through pull requests with team visibility
- Published in CI/CD - Diagrams render and deploy automatically (this site uses GitHub Actions)

C4 Model: 4 Levels of Architecture Diagrams

Progressive zoom from system context down to code level. Each level can be automatically generated from your infrastructure and application code.

Level 1: System Context

System

Big picture: your system, users, and external dependencies

User -> Web App -> Database
Web App -> Payment API
Web App -> Email Service

How It Works:

Parse deployment pipelines and infrastructure configs to extract external systems

Real Example:

Parse .github/workflows/cd.yml to extract Cloudflare Pages, deployment triggers, and external services

Level 2: Container

Container

Applications, databases, microservices, file systems

React SPA
Node.js API
Redis Cache
PostgreSQL DB

How It Works:

Parse Infrastructure as Code to extract resources and dependencies

Real Example:

inframap generate terraform/ generates PlantUML from Terraform state, or parse package.json dependencies

Level 3: Component

Component

Services, controllers, repositories within a container

UserService
OrderController
PaymentGateway
DatabaseRepository

How It Works:

Scan source code directory structure and module organization

Real Example:

Recursively scan src/services/, src/components/ directories and parse index.ts exports

Level 4: Code

Code

Classes, methods, functions, interfaces

class UserService {
  getUser(id)
  updateUser(id, data)
  deleteUser(id)
}

How It Works:

Use AST parsers to extract class structures, method signatures, and dependencies

Real Example:

Use acorn or @babel/parser to parse TypeScript files and extract class methods, or use typedoc for full API docs

This Portfolio: All 4 C4 levels are auto-generated from code using npm run docs:arch

Level 1 System Context Example

High-level view of this portfolio site and its external dependencies, auto-generated from GitHub Actions workflows.

Generated from: .github/workflows/cd.yml and ci.yml

Level 2 Container Example: Microservices Architecture

Event-driven microservices with Kafka showing containers (services, databases, message queues) and their interactions.

Source: docs/architecture/examples/microservices.mmd

Level 2 Container Example: Data Pipeline Architecture

Real-time and batch data processing containers showing data flow from ingestion through transformation to consumption.

Source: docs/architecture/examples/data-pipeline.mmd

Level 3 Component Example: Order Service

Zooming into the Order Service container to show its internal components, controllers, and repositories.

Source: docs/architecture/examples/order-service.puml

Level 4 Code Example: ThemeManager Class

Zooming into a component to show class structure and method signatures, auto-generated from TypeScript source code. Note: Level 4 diagrams are optional. They're great for critical algorithms, security components, or complex business logic that needs detailed documentation. But avoid generating them for entire systems - they quickly become overwhelming and unmaintainable at scale.

Generated from: src/services/ThemeManager.ts using AST parsing

Want This for Your Systems?

Architecture that lives with code. Documentation that evolves with your team.

Let's Talk