arc42 Architecture Templates

arc42 Architecture Templates

Purpose

arc42 is a template for architecture documentation. This skill provides patterns and structure for documenting software architecture in a standardized, stakeholder-friendly way.

When to Use This Skill

• Creating initial architecture documentation
• Documenting component boundaries
• Describing system interfaces
• Recording architectural decisions
• Communicating with stakeholders

Core Concepts

• 12 Sections: arc42 organizes architecture into 12 standardized sections covering context, building blocks, runtime, deployment, and quality
• Decomposition Levels: Systems decompose into Context (L0) → Containers (L1) → Components (L2)
• Black/White Box: External view (interfaces only) vs internal view (structure revealed)
• Stakeholder Focus: Documentation tailored for different audiences (developers, operators, business)

arc42 Sections Quick Reference

#	Section	Purpose	When to Use
1	Introduction	Goals, stakeholders, constraints	Project setup
2	Constraints	Technical/organizational limits	Initial design
3	Context	System boundaries, external interfaces	System scoping
4	Solution Strategy	Key decisions, technology choices	Architecture decisions
5	Building Blocks	Components, modules, structure	Design documentation
6	Runtime View	Scenarios, sequences, flows	Behavior documentation
7	Deployment	Infrastructure, nodes, mapping	Operations planning
8	Crosscutting	Security, logging, error handling	Quality implementation
9	Decisions	ADRs, rationale	Decision tracking
10	Quality	Quality goals, scenarios	Quality assurance
11	Risks	Technical risks, debt	Risk management
12	Glossary	Terms, definitions	Communication

Building Blocks Structure

Level 0: System Context
├── Your System (white box)
├── External System A
├── External System B
└── User

Level 1: Container View
├── Web Application
├── API Service
├── Database
└── Message Queue

Level 2: Component View (per container)
├── Controller Layer
├── Service Layer
├── Repository Layer
└── Domain Models

Quick Templates

Component Documentation

### {Component Name}

**Purpose**: {one-line description}

**Responsibilities**:
- {responsibility 1}
- {responsibility 2}

**Interfaces**:
- `{interface}`: {description}

**Dependencies**:
- Uses: {component names}
- Used by: {component names}

Interface Documentation

### {Interface Name}

**Type**: {REST API | Event | gRPC | etc.}
**Protocol**: {HTTP | AMQP | etc.}

**Operations**:
| Operation | Input | Output | Description |
|-----------|-------|--------|-------------|
| {name} | {type} | {type} | {description} |

References

For detailed patterns and examples, see:

• references/building-blocks.md
• references/runtime-view.md
• references/deployment-view.md
• examples/sample-component.md

Integration with S2S

In Spec2Ship projects:

• Architecture goes in .s2s/architecture.md (single consolidated file)
• ADRs go in .s2s/decisions/ (Section 9)