setup-architecture-as-code
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.
jrjsmrtn · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add jrjsmrtn/project-orchestration-skills --skill setup-architecture-as-code技能说明
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-projectskill - 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/cliandstructurizr/lite) - Visualization: structurizr/structurizr
localsubcommand or Structurizr Cloud
Required Inputs
- Project/System name
- System description (1-2 sentences)
- Key users/personas (who interacts with the system)
- External systems (what the system integrates with)
- Main containers (applications, databases, services)
- 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
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:
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 c
阅读完整来源 ↗