Architecture Diagrams Index

This directory contains comprehensive visual representations of DocBuilder’s architecture. Each diagram set has been verified against the current codebase implementation.

Last Updated: January 4, 2026 - All diagrams verified and split into focused documents.

Overview

The architecture diagrams are organized into separate documents by category:

1. High-Level System Architecture - Layered architecture view
2. Pipeline Flow - Sequential stage execution and detailed stage operations
3. Package Dependencies - Import relationships and dependency rules
4. Data Flow - Configuration, build execution, and state persistence flows
5. Component Interactions - Theme config, forge integration, change detection
6. State Machines - Build, repository, and theme configuration state transitions

Quick Navigation

By Use Case

Understanding the System:

• Start with High-Level System Architecture for overall structure
• Then review Package Dependencies for code organization

Build Pipeline Development:

• Review Pipeline Flow for stage details
• Check Data Flow for data movement
• Reference State Machines for state transitions

Integration Work:

• See Component Interactions for forge and theme integration
• Review Data Flow for configuration and metadata handling

Debugging:

• Check State Machines for valid state transitions
• Review Pipeline Flow for stage execution order
• See Data Flow for data transformation steps

By Component

Hugo Generator:

• Pipeline Flow: CopyContent Stage
• Component Interactions: Relearn Theme
• High-Level: Processing Layer

Git Operations:

• Data Flow: Repository Metadata
• State Machines: Repository State
• Component Interactions: Change Detection

Build Service:

• Pipeline Flow: Sequential Execution
• State Machines: Build State
• Data Flow: Build Execution

Forge Integration:

• Component Interactions: Forge Integration
• Data Flow: Repository Metadata

Diagram Verification Status

All diagrams have been verified against the current codebase (January 4, 2026):

Key Architecture Changes Reflected

These diagrams reflect the following architectural decisions:

1. ADR-003: Fixed 12-step transform pipeline (not 11)
2. Relearn Theme Only: No multi-theme system, hardcoded Relearn defaults
3. Unified Error Handling: All errors use internal/foundation/errors
4. Layer Architecture: Strict dependency flow (command → service → domain → infrastructure → foundation)
5. State Decomposition: BuildState split into GitState, DocsState, PipelineState

Diagram Conventions

Layer Diagrams:

• Boxes represent components
• Arrows show dependencies (A → B means “A depends on B”)
• Layers are horizontal (upper layers depend on lower layers)

Flow Diagrams:

• Rectangles represent processes/stages
• Diamonds represent decisions
• Arrows show execution flow
• Dashed lines show optional flows

State Machines:

• Circles/rounded boxes represent states
• Arrows show transitions
• Notes explain transition conditions

Sequence Diagrams:

• Vertical lines represent components
• Horizontal arrows show interactions
• Time flows top-to-bottom

Maintenance

When updating architecture:

1. Check All Affected Diagrams: Changes may impact multiple diagram sets
2. Verify Implementation: Ensure diagrams match actual code behavior
3. Update Verification Date: Update “Last Updated” timestamp
4. Cross-Reference: Update related documentation links

Common Update Triggers:

• Adding/removing pipeline stages
• Changing package dependencies
• Adding new components
• Modifying state transitions
• Changing configuration structure

Related Documentation

• Comprehensive Architecture - Detailed architecture guide
• Architecture Overview - High-level architecture concepts
• Package Architecture Guide - Package-level documentation
• Namespacing Rationale - Design decisions for namespace structure