Software Architecture Documentation

Document system architecture using a root ARCHITECTURE.md with detailed component docs in docs/*.md.

Structure

project/
├── ARCHITECTURE.md      # High-level system overview
└── docs/
    ├── <component>.md   # Detailed component documentation
    └── ...

Proactive Usage

When ARCHITECTURE.md exists in project root:

1. Before major changes: Read ARCHITECTURE.md to understand system structure
2. After structural changes: Update diagrams and entry points
3. When adding components: Create new docs/*.md file and link from ARCHITECTURE.md
4. During refactoring: Update affected diagrams and file references

Creating Architecture Documentation

Initial Setup Workflow

1. Analyze codebase structure

   • Identify entry points (main, CLI, API handlers)
   • Map major components and their responsibilities
   • Trace key data flows

2. Create ARCHITECTURE.md

   • Write system overview (1-2 paragraphs)
   • Add C4 Context diagram showing system boundaries
   • Document entry points table
   • List key abstractions
   • Add testing overview
   • Link to detail docs (create docs/ section even if empty initially)

3. Create detail docs for major components

   • One file per logical component in docs/
   • Name files to match component names (flexible convention)
   • Include component-level diagrams

See references/document-templates.md for complete templates.

ARCHITECTURE.md Sections

Required Sections

Optional Sections

Detail Documents (docs/*.md)

Create a detail doc when a component:

• Has 3+ key files or abstractions
• Contains complex internal logic
• Interacts with multiple other components
• Needs sequence diagrams to explain flows

Naming Convention

Flexible. Match the component's identity:

• docs/auth.md for authentication component
• docs/data-pipeline.md for data pipeline
• docs/cli.md for CLI handling

Required Content

Optional Content

Diagram Selection

Start minimal (3-5 nodes). Add detail only when it improves clarity.

See references/mermaid-patterns.md for diagram templates.

Entry Points and Abstractions

Entry Points Table

Document files that serve as starting points for understanding the codebase:

| File | Description |
|------|-------------|
| `src/main.py` | Application entry point |
| `src/core/engine.py` | Core processing engine |
| `tests/conftest.py` | Test fixtures and setup |

Include:

• Application entry points (main, CLI, handlers)
• Core domain logic locations
• Configuration files
• Test setup and fixtures

Key Abstractions Table

Document important classes, interfaces, and functions:

| Abstraction | Location | Purpose |
|-------------|----------|---------|
| `Engine` | `src/core/engine.py` | Orchestrates processing |
| `Handler` | `src/api/base.py` | Request handling interface |

Focus on:

• Base classes and interfaces
• Core domain objects
• Public API surfaces
• Extension points

Maintaining Documentation

When to Update

Update Checklist

After structural changes:

1. Verify entry points table is accurate
2. Check diagram nodes match actual components
3. Confirm file paths in tables are valid
4. Update any affected detail docs