--- name: setup-architecture-as-code description: Establish architecture-as-code practice using C4 modeling and Structurizr DSL. Use after bootstrap-project, when establishing architecture documentation, or when migrating from diagram-based to code-based architecture. metadata: author: "Georges Martin <jrjsmrtn@gmail.com>" version: "0.1.34" license: MIT ---

# Setup Architecture-as-Code

Establish architecture-as-code practice using C4 modeling and Structurizr DSL.

## When to Use

- After running `bootstrap-project` skill - When establishing architecture documentation for a project - When migrating from diagram-based to code-based architecture documentation - When you need version-controlled, validated architecture models

## What is Architecture-as-Code?

Architecture-as-Code treats architecture documentation like source code:

| Traditional Diagrams | Architecture-as-Code | |---------------------|---------------------| | Draw in GUI tools | Define in text/DSL | | Manual updates | Automated validation | | Binary files (PNG, VSDX) | Text files (version control friendly) | | Diagrams diverge from reality | Single source of truth | | Hard to review changes | PR-reviewable changes | | No validation | Syntax + semantic validation |

**Implementation Stack**: - **Modeling Approach**: C4 Model (Context, Container, Component, Code) - **Definition Language**: Structurizr DSL - **Validation & Inspection**: structurizr/structurizr (consolidated image, replaces deprecated `structurizr/cli` and `structurizr/lite`) - **Visualization**: structurizr/structurizr `local` subcommand or Structurizr Cloud

## Required Inputs

1. **Project/System name** 2. **System description** (1-2 sentences) 3. **Key users/personas** (who interacts with the system) 4. **External systems** (what the system integrates with) 5. **Main containers** (applications, databases, services) 6. **Technology stack** (languages, frameworks, databases)

## C4 Model Overview

The C4 model provides four levels of abstraction (zoom levels):

| Level | Name | Purpose | Audience | |-------|------|---------|----------| | 1 | System Context | System in its environment | Everyone | | 2 | Container | Deployable units | Technical staff | | 3 | Component | Internal structure | Developers | | 4 | Code | Class/module level | Developers (often generated) |

**Key Principle**: Start with Level 1-2, add Level 3 only when needed. Level 4 is usually generated from code.

## Workflow

### Step 1: Create Directory Structure

```bash mkdir -p architecture/shared mkdir -p docs/architecture # Structurizr-specific docs (h2-first, numbered files) # Symlink so !adrs and !docs directives can reach docs/ from architecture/ ln -s ../docs architecture/docs ```

The symlink is required because Structurizr restricts `!adrs` and `!docs` paths to the same directory or subdirectories of the DSL file — it cannot traverse parent directories.

**Why `docs/architecture/` and not `docs/explanation/`?** Structurizr silently strips h1 headings (it auto-generates h1 from the element name). Diátaxis docs use h1 as their title, so pointing `!docs` at a Diátaxis directory would lose those titles. Keep Structurizr docs in a dedicated directory with h2-first files.

### Step 2: Create Workspace File

Create `architecture/workspace.dsl`:

```dsl workspace "[Project Name]" "[Brief description]" {

!identifiers hierarchical !adrs docs/adr !docs docs/architecture

model { # ===== USERS/ACTORS ===== user = person "User" "Primary user of the system" "User"

# Add other personas as needed: # admin = person "Administrator" "System administrator" "Admin" # developer = person "Developer" "API consumer" "Developer"

# ===== EXTERNAL SYSTEMS ===== # externalSystem = softwareSystem "External System" "Description" "External"

# ===== THE SYSTEM ===== system = softwareSystem "[System Name]" "[System description]" {

# ----- CONTAINERS -----

# Web Application (if applicable) webApp = container "Web Application" "Provides user interface" "[Framework]" "Web"

# API Service (if applicable) api = container "API Service" "Provides REST/GraphQL API" "[Framework]" "API"

# Database database = container "Database" "Stores application data" "[Database Technology]" "Database"

# Background Workers (if applicable) # worker = container "Background Worker" "Processes async tasks" "[Technology]" "Worker"

# ----- COMPONENTS (for main container) ----- # Uncomment and customize for your architecture:

# api { # authComponent = component "Authentication" "Handles user auth" "[Module]" # businessComponent = component "Business Logic" "Core domain logic" "[Module]" # dataComponent = component "Data Access" "Database operations" "[Module]" # } }

# ===== RELATIONSHIPS =====

# User interactions user -> system "Uses" user -> system.webApp "Interacts with" "HTTPS"

# Internal relationships system.webApp -> system.api "Makes API calls to" "HTTP/JSON" system.api -> system.database "Reads from and writes to" "SQL"

# External system relationships (if any) # system.api -> externalSystem "Integrates with" "HTTPS" }

views { # ===== SYSTEM CONTEXT VIEW ===== systemContext system "SystemContext" { include * autoLayout description "System Context diagram showing [System Name] and its environment" }

# ===== CONTAINER VIEW ===== container system "Containers" { include * autoLayout description "Container diagram showing the main deployable units" }

# ===== COMPONENT VIEW (optional) ===== # Uncomment when you have components defined: # component system.api "Components" { # include * # autoLayout # description "Component diagram for the API service" # }

# ===== STYLES ===== styles { element "Person" { shape Person background #08427B color #ffffff } element "Software System" { background #1168BD color #ffffff } element "External" { background #999999 color #ffffff } element "Container" { background #438DD5 color #ffffff } element "Component" { background #85BBF0 color #000000 } element "Database" { shape Cylinder } element "Web" { shape WebBrowser } element "API" { shape Hexagon } element "Worker" { shape Robot } } } } ```

### Step 3: Create Technology-Specific Templates

#### Elixir/Phoenix Template

```dsl workspace "[Project Name]" "Elixir/Phoenix application" {

!identifiers hierarchical !adrs docs/adr !docs docs/architecture

model { user = person "User" "Application user" "User"

system = softwareSystem "[System Name]" "Phoenix web application" {

phoenix = container "Phoenix Application" "Web application and API" "Elixir/Phoenix" "Web"

liveview = container "LiveView UI" "Real-time user interface" "Phoenix LiveView" "Web"

# If using Ash Framework: # ash = container "Ash Resources" "Domain logic and resources" "Ash Framework" "Component"

postgres = container "PostgreSQL" "Primary data store" "PostgreSQL 16" "Database"

# Optional: Background jobs # oban = container "Oban Workers" "Background job processing" "Oban" "Worker" }

user -> system.liveview "Uses" "HTTPS" system.liveview -> system.phoenix "LiveView connections" "WebSocket" system.phoenix -> system.postgres "Queries" "Ecto" }

views { systemContext system "SystemContext" { include * autoLayout }

container system "Containers" { include * autoLayout }

styles { element "Person" { shape Person background #08427B color #ffffff } element "Software System" { background #6B4C9A color #ffffff } element "Container" { background #9B59B6 color #ffffff } element "Database" { shape Cylinder background #336791 } element "Web" { shape WebBrowser } } } } ```

#### Python/FastAPI Template

```dsl workspace "[Project Name]" "Python FastAPI application" {

!identifiers hierarchical !adrs docs/adr !docs docs/architecture

model { user = person "User" "API consumer" "User"

system = softwareSystem "[System Name]" "FastAPI service" {

api = container "FastAPI Service" "REST API" "Python/FastAPI" "API"

postgres = container "PostgreSQL" "Primary data store" "PostgreSQL 16" "Database"

# Optional: Redis for caching/sessions # redis = container "Redis" "Cache and session store" "Redis" "Database"

# Optional: Celery workers # celery = container "Celery Workers" "Async task processing" "Celery" "Worker" }

user -> system.api "Calls" "HTTPS/JSON" system.api -> system.postgres "Queries" "SQLAlchemy" }

views { systemContext system "SystemContext" { include * autoLayout }

container system "Containers" { include * autoLayout }

styles { element "Person" { shape Person background #08427B color #ffffff } element "Software System" { background #306998 color #ffffff } element "Container" { background #FFD43B color #000000 } element "Database" { shape Cylinder background #336791 } element "API" { shape Hexagon } } } } ```

### Step 4: Create Model Overview

Create `architecture/README.md`:

```markdown # [Project Name] Architecture-as-Code

## What is Architecture-as-Code?

This project uses **Architecture-as-Code**: architecture models defined in text files (Structurizr DSL), version-controlled alongside source code, and validated automatically.

**Benefits**: - **Version Control**: Architecture changes tracked in git history - **Code Review**: Architecture changes reviewable in PRs - **Validation**: Syntax and semantic errors caught automatically - **Single Source of Truth**: Model generates diagrams, not vice versa - **AI-Friendly**: Text-based format readable by AI assistants

## Model Structure

``` architecture/ ├── workspace.dsl # C4 model definition (THE source of truth) ├── shared/ # Shared DSL fragments (!include targets) │ └── _styles.dsl # Unified element/relationship styles ├── docs -> ../docs # Symlink (enables !adrs and !docs directives) ├── README.md # This file └── diagrams/ # Generated exports (optional, gitignored) ```

The `docs` symlink allows workspace files to use `!adrs docs/adr` and `!docs docs/architecture` — Structurizr requires these