From playbook-dev
This skill should be used when the user asks to "document system architecture", "describe domain structure", "map system components", "create architecture reference", or needs to document the domain system being analyzed by the playbook.
How this skill is triggered — by the user, by Claude, or both
Slash command
/playbook-dev:architecture-docThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Document domain system structure for complex system analysis in playbooks.
Document domain system structure for complex system analysis in playbooks.
Architecture documentation helps analysts understand:
Create architecture documentation when:
# {System} Architecture
## Overview
{2-3 paragraph description of what the system does and its main components}
## System Diagram
[Component A] ─────> [Component B] ─────> [Component C] │ │ │ ↓ ↓ ↓ [Data Store] [External API] [Output]
## Components
### Component A: {Name}
**Purpose:** {What this component does}
**Location:** `{path/to/code}`
**Key files:**
- `{file1.ext}` - {Purpose}
- `{file2.ext}` - {Purpose}
**Interfaces:**
- Input: {What it receives}
- Output: {What it produces}
**Dependencies:**
- {Dependency 1}
- {Dependency 2}
### Component B: {Name}
...
## Data Flow
### {Flow Name}
**Key transformation points:**
- At step 2: {What happens}
- At step 3: {What happens}
## Code Patterns
### {Pattern Name}
**Files:** `{pattern}*.ext`
**Purpose:** {What these files do}
**Example:**
```{language}
// Typical structure
{code example}
Purpose: {What this integration does}
Endpoint: {URL or path}
Data exchanged:
Failure modes:
{Explanation of domain concept relevant to analysis}
{Explanation of domain concept relevant to analysis}
| Issue | Symptoms | Typical Cause |
|---|---|---|
| {Issue 1} | {What you see} | {Root cause} |
| {Issue 2} | {What you see} | {Root cause} |
For analysis purposes, key code is at:
| Purpose | Location |
|---|---|
| {Purpose 1} | {path} |
| {Purpose 2} | {path} |
| {Purpose 3} | {path} |
## Component Documentation
### Required Information
For each component:
| Field | Description |
|-------|-------------|
| Purpose | What it does in 1-2 sentences |
| Location | Path to source code |
| Key files | Most important files |
| Interfaces | What goes in/out |
| Dependencies | What it relies on |
### Optional Information
| Field | When to Include |
|-------|-----------------|
| Configuration | If configurable behavior |
| State | If maintains state |
| Concurrency | If parallel execution |
| Error handling | If complex failure modes |
## Data Flow Documentation
### Flow Diagrams
Use ASCII art for simplicity:
[Input] ──> [Process A] ──> [Process B] ──> [Output] │ ↓ [Side Effect]
### Sequence Diagrams
For temporal flows:
Client Server Database │ │ │ │──req──> │ │ │ │──query──>│ │ │<─result──│ │<─resp───│ │
## Code Pattern Documentation
### Pattern Format
```markdown
### {Pattern Name}
**Files matching:** `{glob pattern}`
**Purpose:** {What these files do}
**Typical structure:**
- {Section 1}: {Purpose}
- {Section 2}: {Purpose}
**Analysis focus:**
- Look for: {What to examine}
- Common issues: {What goes wrong}
| Pattern | Example | Purpose |
|---|---|---|
| Handlers | handle_*.go | Request processing |
| Models | model_*.py | Data structures |
| Services | *_service.ts | Business logic |
| Tests | *_test.* | Test coverage |
Document each external dependency:
### {Service Name}
**Type:** {API/Database/Queue/etc}
**Purpose:** {Why we integrate}
**Access pattern:**
- Protocol: {HTTP/gRPC/etc}
- Authentication: {Method}
- Rate limits: {If any}
**Data format:**
- Request: {Schema/format}
- Response: {Schema/format}
**Failure handling:**
- Timeout: {Behavior}
- Error: {Behavior}
- Retry: {Policy}
Before finalizing:
For architecture documentation patterns:
${CLAUDE_PLUGIN_ROOT}/references/playbook-pattern.md - Section 4.2npx claudepluginhub tgvashworth/agent-plugins --plugin playbook-devGenerates system architecture docs with overview, components list, Mermaid diagrams for components and data flows, external dependencies, ADRs links, and dev setup instructions.
Documents system architecture with component diagrams, data flows, ADRs, deployment views, and templates. Analyzes patterns and maintains living docs for team communication.
Generates architecture documentation using arc42 or C4 models with Mermaid diagrams for system context, containers, components, plus narrative on structure, dependencies, and flows.