Explanation Documentation

This directory contains comprehensive architecture documentation for DocBuilder. The documentation is organized to provide different views and levels of detail for various audiences.

Documentation Structure

High-Level Overview

Architecture Overview (architecture.md)

• Quick reference for the staged pipeline
• Key components and responsibilities
• Namespacing and idempotence strategies
• Design rationale highlights
• Audience: New developers, product managers, technical leads

Comprehensive Documentation

Comprehensive Architecture (comprehensive-architecture.md)

• Complete system architecture with all layers
• Core principles (clean architecture, event sourcing, typed state)
• Detailed package structure and responsibilities
• Data flow diagrams and sequences
• Key subsystems deep dive (Relearn configuration, forges, change detection)
• Extension points and operational considerations
• Migration status summary
• Audience: Senior engineers, architects, contributors

Architecture Diagrams (architecture-diagrams.md)

• Visual representations using ASCII and Mermaid
• System architecture diagrams
• Pipeline flow visualizations
• Package dependency graphs
• Component interaction sequences
• State machine diagrams
• Deployment architectures
• Audience: Visual learners, architects, documentation reviewers

Package Architecture Guide (package-architecture.md)

• Detailed package-by-package documentation
• Key types and interfaces for each package
• Usage patterns and code examples
• Design rationale for architectural decisions
• Dependency rules and import matrix
• Testing support infrastructure
• Audience: Contributors, maintainers, package users

Specialized Topics

Namespacing Rationale (namespacing-rationale.md)

• Forge-level namespacing design
• Collision prevention strategies
• Configuration options
• Audience: Users configuring multi-forge setups

Renderer Testing (renderer-testing.md)

• Hugo rendering test strategies
• Golden test patterns
• Audience: Contributors working on Hugo integration

Quick Navigation

By Role

New Developer Getting Started:

1. Start with Architecture Overview
2. Review Architecture Diagrams for visual understanding
3. Deep dive into Package Architecture Guide for code structure

Contributing to Core Pipeline:

1. Read Comprehensive Architecture - Pipeline Flow section
2. Study Package Architecture Guide - Pipeline section
3. Review Architecture Diagrams - Pipeline Flow

Adding New Theme Support:

1. Read Comprehensive Architecture - Theme System
2. Review Package Architecture Guide - internal/hugo section
3. Follow How-To Guide

Implementing Forge Integration:

1. Read Comprehensive Architecture - Forge Integration
2. Study Package Architecture Guide - internal/forge section
3. Review Namespacing Rationale

Understanding State Management:

1. Review Comprehensive Architecture - State Management
2. Study Package Architecture Guide - internal/state section
3. Check Architecture Diagrams - State Persistence Flow

By Topic

Configuration System:

• Comprehensive Architecture
• Package Architecture Guide
• Configuration Reference

Pipeline Stages:

• Architecture Overview
• Architecture Diagrams
• Package Architecture Guide

Event Sourcing:

• Comprehensive Architecture
• Package Architecture Guide

Error Handling:

• Comprehensive Architecture
• Package Architecture Guide
• ADR-000: Uniform Error Handling

Relearn Configuration:

• Comprehensive Architecture
• Architecture Diagrams
• How-To: Use Relearn Theme

Change Detection:

• Comprehensive Architecture
• Architecture Diagrams
• Package Architecture Guide

Testing Infrastructure:

• Package Architecture Guide
• Renderer Testing

Architecture Evolution

The architecture has undergone significant evolution documented in:

• Architecture Migration Plan (2025) - Completed
  • 19 completed phases (A-M, O-P, R-S-T-U)
  • 2 deferred phases (Q, J)
  • ~1,290 lines eliminated
  • Zero breaking changes

Architecture Decision Records (ADRs)

For detailed architectural decisions, see the ADR directory:

• ADR-000: Uniform Error Handling
• ADR-001: Forge Integration Daemon

Visual Reference

System Layers

┌─────────────────────────┐
│   Presentation Layer    │  cmd/docbuilder/commands, server/
├─────────────────────────┤
│   Application Layer     │  build/, services/, daemon/
├─────────────────────────┤
│     Domain Layer        │  config/, state/, docs/, hugo/, forge/
├─────────────────────────┤
│  Infrastructure Layer   │  git/, workspace/, eventstore/, auth/
├─────────────────────────┤
│   Foundation Layer      │  foundation/errors, logfields/, metrics/
└─────────────────────────┘

Pipeline Stages

PrepareOutput → CloneRepos → DiscoverDocs → GenerateConfig →
Layouts → CopyContent → Indexes → RunHugo (optional)

Key Principles

1. Clean Architecture - Clear dependency direction
2. Event Sourcing - Immutable event log
3. Typed State - No map[string]any in primary paths
4. Unified Errors - Single error type system
5. Observable - Logging, metrics, tracing

Contributing to Architecture

When making architectural changes:

1. Update relevant documentation in this directory
2. Add ADR for significant decisions
3. Update diagrams if structure changes
4. Update migration plan if part of migration
5. Update package guide for API changes

Questions and Feedback

For questions about the architecture:

• Check existing documentation first
• Review ADRs for historical context
• Open discussion in GitHub issues
• Tag architecture-related PRs with architecture label

Related Documentation

• Getting Started Tutorial
• How-To Guides
• Reference Documentation
• Contributing Guide
• Changelog

Last Updated: December 2025

Architecture Status: Migration complete (19 phases), production-ready