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