# Product Areas

**Purpose:** Product area overview index
**Detail Level:** Full reference

---

## [Annotation](product-areas/ANNOTATION.md)

> **How do I annotate code?**

The annotation system is the ingestion boundary — it transforms annotated TypeScript and Gherkin files into `ExtractedPattern[]` objects that feed the entire downstream pipeline. Two parallel scanning paths (TypeScript AST + Gherkin parser) converge through dual-source merging. The system is fully data-driven: the `TagRegistry` defines all tags, formats, and categories — adding a new annotation requires only a registry entry, zero parser changes.

**27 patterns** — 23 completed, 3 active, 1 planned

**Key patterns:** PatternRelationshipModel, ShapeExtraction, DualSourceExtraction, GherkinRulesSupport, DeclarationLevelShapeTagging, CrossSourceValidation, ExtractionPipelineEnhancementsTesting

## [Configuration](product-areas/CONFIGURATION.md)

> **How do I configure the tool?**

Configuration is the entry boundary — it transforms a user-authored `architect.config.ts` file into a fully resolved `ArchitectInstance` that powers the entire pipeline. The flow is: `defineConfig()` provides type-safe authoring (Vite convention, zero validation), `ConfigLoader` discovers and loads the file, `ProjectConfigSchema` validates via Zod, `ConfigResolver` applies defaults and merges stubs into sources, and `ArchitectFactory` builds the final instance with `TagRegistry` and `RegexBuilders`. Two presets define escalating taxonomy complexity — from 3 categories (`libar-generic`) to 21 (`ddd-es-cqrs`). `SourceMerger` computes per-generator source overrides, enabling generators like changelog to pull from different feature sets than the base config.

**11 patterns** — 8 completed, 0 active, 3 planned

**Key patterns:** ArchitectFactory, ConfigLoader, ConfigResolver, DefineConfig, ConfigurationPresets, SourceMerger

## [Generation](product-areas/GENERATION.md)

> **How does code become docs?**

The generation pipeline transforms annotated source code into markdown documents through a four-stage architecture: Scanner discovers files, Extractor produces `ExtractedPattern` objects, Transformer builds PatternGraph with pre-computed views, and Codecs render to markdown via RenderableDocument IR. Nine specialized codecs handle reference docs, planning, session, reporting, timeline, ADRs, business rules, taxonomy, and composite output — each supporting three detail levels (detailed, standard, summary). The Orchestrator runs generators in registration order, producing both detailed `docs-live/` references and compact `_claude-md/` summaries.

**96 patterns** — 82 completed, 6 active, 8 planned

**Key patterns:** ADR005CodecBasedMarkdownRendering, CodecDrivenReferenceGeneration, CrossCuttingDocumentInclusion, ArchitectureDiagramGeneration, ScopedArchitecturalView, CompositeCodec, RenderableDocument, ProductAreaOverview

## [Validation](product-areas/VALIDATION.md)

> **How is the workflow enforced?**

Validation is the enforcement boundary — it ensures that every change to annotated source files respects the delivery lifecycle rules defined by the FSM, protection levels, and scope constraints. The system operates in three layers: the FSM validator checks status transitions against a 4-state directed graph, the Process Guard orchestrates commit-time validation using a Decider pattern (state derived from annotations, not stored separately), and the lint engine provides pluggable rule execution with pretty and JSON output. Anti-pattern detection enforces dual-source ownership boundaries — `@architect-uses` belongs on TypeScript, `@architect-depends-on` belongs on Gherkin — preventing cross-domain tag confusion that causes documentation drift. Definition of Done validation ensures completed patterns have all deliverables marked done and at least one acceptance-criteria scenario.

**25 patterns** — 16 completed, 3 active, 6 planned

**Key patterns:** ProcessGuardLinter, PhaseStateMachineValidation, DoDValidation, StepLintVitestCucumber, ProgressiveGovernance

## [DataAPI](product-areas/DATA-API.md)

> **How do I query process state?**

The Data API provides direct terminal access to project state. It replaces reading generated markdown or launching explore agents — targeted queries use 5-10x less context. The `context` command assembles curated bundles tailored to session type (planning, design, implement).

**40 patterns** — 23 completed, 15 active, 2 planned

**Key patterns:** DataAPIContextAssembly, PatternGraphAPICLI, DataAPIDesignSessionSupport, DataAPIRelationshipGraph, DataAPIOutputShaping

## [CoreTypes](product-areas/CORE-TYPES.md)

> **What foundational types exist?**

CoreTypes provides the foundational type system used across all other areas. Three pillars enforce discipline at compile time: the Result monad replaces try/catch with explicit error handling — functions return `Result.ok(value)` or `Result.err(error)` instead of throwing. The DocError discriminated union provides structured error context with type, file, line, and reason fields, enabling exhaustive pattern matching in error handlers. Branded types create nominal typing from structural TypeScript — `PatternId`, `CategoryName`, and `SourceFilePath` are compile-time distinct despite all being strings. String utilities handle slugification and case conversion with acronym-aware title casing.

**11 patterns** — 7 completed, 4 active, 0 planned

**Key patterns:** ResultMonad, ErrorHandlingUnification, ErrorFactories, StringUtils, KebabCaseSlugs

## [Process](product-areas/PROCESS.md)

> **How does the session workflow work?**

Process defines the USDP-inspired session workflow that governs how work moves through the delivery lifecycle. Three session types (planning, design, implementation) have fixed input/output contracts: planning creates roadmap specs from pattern briefs, design produces code stubs and decision records, and implementation writes code against scope-locked specs. Git is the event store — documentation artifacts are projections of annotated source code, not hand-maintained files. The FSM enforces state transitions (roadmap → active → completed) with escalating protection levels, while handoff templates preserve context across LLM session boundaries. ADR-003 established that TypeScript source owns pattern identity; tier 1 specs are ephemeral planning documents that lose value after completion.

**11 patterns** — 4 completed, 0 active, 7 planned

**Key patterns:** ADR001TaxonomyCanonicalValues, ADR003SourceFirstPatternArchitecture, MvpWorkflowImplementation, SessionHandoffs

---

## Progress Overview

| Area                                            | Patterns | Completed | Active | Planned |
| ----------------------------------------------- | -------- | --------- | ------ | ------- |
| [Annotation](product-areas/ANNOTATION.md)       | 27       | 23        | 3      | 1       |
| [Configuration](product-areas/CONFIGURATION.md) | 11       | 8         | 0      | 3       |
| [Generation](product-areas/GENERATION.md)       | 96       | 82        | 6      | 8       |
| [Validation](product-areas/VALIDATION.md)       | 25       | 16        | 3      | 6       |
| [DataAPI](product-areas/DATA-API.md)            | 40       | 23        | 15     | 2       |
| [CoreTypes](product-areas/CORE-TYPES.md)        | 11       | 7         | 4      | 0       |
| [Process](product-areas/PROCESS.md)             | 11       | 4         | 0      | 7       |
| **Total**                                       | **221**  | **163**   | **31** | **27**  |

---

## System Architecture

Scoped architecture diagram showing component relationships:

```mermaid
C4Context
    title System Architecture
    Boundary(config, "Config") {
        System(ConfigResolver, "ConfigResolver")
        System(ConfigurationPresets, "ConfigurationPresets")
        System(SourceMerger, "SourceMerger")
        System(ArchitectFactory, "ArchitectFactory")
        System(DefineConfig, "DefineConfig")
        System(ConfigLoader, "ConfigLoader")
    }
    Boundary(renderer, "Renderer") {
        System(CompositeCodec, "CompositeCodec")
    }
    System(ADR003SourceFirstPatternArchitecture, "ADR003SourceFirstPatternArchitecture")
    System(ADR001TaxonomyCanonicalValues, "ADR001TaxonomyCanonicalValues")
    System(ShapeExtraction, "ShapeExtraction")
    System(ScopedArchitecturalView, "ScopedArchitecturalView")
    System(DeclarationLevelShapeTagging, "DeclarationLevelShapeTagging")
    System(DataAPIDesignSessionSupport, "DataAPIDesignSessionSupport")
    System(DataAPIOutputShaping, "DataAPIOutputShaping")
    System(DataAPIContextAssembly, "DataAPIContextAssembly")
    System(CrossCuttingDocumentInclusion, "CrossCuttingDocumentInclusion")
    System(CodecDrivenReferenceGeneration, "CodecDrivenReferenceGeneration")
    System(StringUtils, "StringUtils")
    System(ResultMonad, "ResultMonad")
    System(ErrorFactories, "ErrorFactories")
    System(ExtractionPipelineEnhancementsTesting, "ExtractionPipelineEnhancementsTesting")
    System(KebabCaseSlugs, "KebabCaseSlugs")
    System(ErrorHandlingUnification, "ErrorHandlingUnification")
    System_Ext(ConfigurationTypes, "ConfigurationTypes")
    System_Ext(RegexBuilders, "RegexBuilders")
    System_Ext(ProjectConfigTypes, "ProjectConfigTypes")
    System_Ext(ConfigurationDefaults, "ConfigurationDefaults")
    System_Ext(ReferenceDocShowcase, "ReferenceDocShowcase")
    System_Ext(DocGenerationProofOfConcept, "DocGenerationProofOfConcept")
    System_Ext(DataAPIStubIntegration, "DataAPIStubIntegration")
    Rel(ConfigResolver, ProjectConfigTypes, "uses")
    Rel(ConfigResolver, ArchitectFactory, "uses")
    Rel(ConfigResolver, ConfigurationDefaults, "uses")
    Rel(ConfigurationPresets, ConfigurationTypes, "uses")
    Rel(SourceMerger, ProjectConfigTypes, "uses")
    Rel(ArchitectFactory, ConfigurationTypes, "uses")
    Rel(ArchitectFactory, ConfigurationPresets, "uses")
    Rel(ArchitectFactory, RegexBuilders, "uses")
    Rel(DefineConfig, ProjectConfigTypes, "uses")
    Rel(ConfigLoader, ArchitectFactory, "uses")
    Rel(ConfigLoader, ConfigurationTypes, "uses")
    Rel(CompositeCodec, ReferenceDocShowcase, "implements")
    Rel(ADR003SourceFirstPatternArchitecture, ADR001TaxonomyCanonicalValues, "depends on")
    Rel(ScopedArchitecturalView, ShapeExtraction, "depends on")
    Rel(DeclarationLevelShapeTagging, ShapeExtraction, "depends on")
    Rel(DeclarationLevelShapeTagging, ReferenceDocShowcase, "depends on")
    Rel(DataAPIDesignSessionSupport, DataAPIContextAssembly, "depends on")
    Rel(DataAPIDesignSessionSupport, DataAPIStubIntegration, "depends on")
    Rel(DataAPIContextAssembly, DataAPIOutputShaping, "depends on")
    Rel(DataAPIContextAssembly, DataAPIStubIntegration, "depends on")
    Rel(CrossCuttingDocumentInclusion, DeclarationLevelShapeTagging, "depends on")
    Rel(CrossCuttingDocumentInclusion, ReferenceDocShowcase, "depends on")
    Rel(CodecDrivenReferenceGeneration, DocGenerationProofOfConcept, "depends on")
    Rel(CodecDrivenReferenceGeneration, ScopedArchitecturalView, "depends on")
    Rel(ExtractionPipelineEnhancementsTesting, ReferenceDocShowcase, "implements")
    Rel(KebabCaseSlugs, StringUtils, "depends on")
    Rel(ErrorHandlingUnification, ResultMonad, "depends on")
    Rel(ErrorHandlingUnification, ErrorFactories, "depends on")
    Rel(RegexBuilders, ConfigurationTypes, "uses")
    Rel(ProjectConfigTypes, ConfigurationTypes, "uses")
    Rel(ProjectConfigTypes, ConfigurationPresets, "uses")
    Rel(ReferenceDocShowcase, CodecDrivenReferenceGeneration, "depends on")
    Rel(ReferenceDocShowcase, ScopedArchitecturalView, "depends on")
    Rel(ReferenceDocShowcase, ShapeExtraction, "depends on")
    Rel(DocGenerationProofOfConcept, ShapeExtraction, "depends on")
```

---

## Cross-Area Pattern Relationships

Scoped architecture diagram showing component relationships:

```mermaid
graph LR
    subgraph config["Config"]
        ConfigResolver("ConfigResolver")
        ConfigurationPresets["ConfigurationPresets"]
        SourceMerger("SourceMerger")
        ArchitectFactory("ArchitectFactory")
        DefineConfig[/"DefineConfig"/]
        ConfigLoader[/"ConfigLoader"/]
    end
    subgraph renderer["Renderer"]
        CompositeCodec[("CompositeCodec")]
    end
    ADR003SourceFirstPatternArchitecture["ADR003SourceFirstPatternArchitecture"]
    ADR001TaxonomyCanonicalValues["ADR001TaxonomyCanonicalValues"]
    ShapeExtraction["ShapeExtraction"]
    ScopedArchitecturalView["ScopedArchitecturalView"]
    DeclarationLevelShapeTagging["DeclarationLevelShapeTagging"]
    DataAPIDesignSessionSupport["DataAPIDesignSessionSupport"]
    DataAPIOutputShaping["DataAPIOutputShaping"]
    DataAPIContextAssembly["DataAPIContextAssembly"]
    CrossCuttingDocumentInclusion["CrossCuttingDocumentInclusion"]
    CodecDrivenReferenceGeneration["CodecDrivenReferenceGeneration"]
    StringUtils["StringUtils"]
    ResultMonad["ResultMonad"]
    ErrorFactories["ErrorFactories"]
    ExtractionPipelineEnhancementsTesting["ExtractionPipelineEnhancementsTesting"]
    KebabCaseSlugs["KebabCaseSlugs"]
    ErrorHandlingUnification["ErrorHandlingUnification"]
    subgraph related["Related"]
        ConfigurationTypes["ConfigurationTypes"]:::neighbor
        RegexBuilders["RegexBuilders"]:::neighbor
        ProjectConfigTypes["ProjectConfigTypes"]:::neighbor
        ConfigurationDefaults["ConfigurationDefaults"]:::neighbor
        ReferenceDocShowcase["ReferenceDocShowcase"]:::neighbor
        DocGenerationProofOfConcept["DocGenerationProofOfConcept"]:::neighbor
        DataAPIStubIntegration["DataAPIStubIntegration"]:::neighbor
    end
    ConfigResolver -->|uses| ProjectConfigTypes
    ConfigResolver -->|uses| ArchitectFactory
    ConfigResolver -->|uses| ConfigurationDefaults
    ConfigurationPresets -->|uses| ConfigurationTypes
    SourceMerger -->|uses| ProjectConfigTypes
    ArchitectFactory -->|uses| ConfigurationTypes
    ArchitectFactory -->|uses| ConfigurationPresets
    ArchitectFactory -->|uses| RegexBuilders
    DefineConfig -->|uses| ProjectConfigTypes
    ConfigLoader -->|uses| ArchitectFactory
    ConfigLoader -->|uses| ConfigurationTypes
    CompositeCodec ..->|implements| ReferenceDocShowcase
    ADR003SourceFirstPatternArchitecture -.->|depends on| ADR001TaxonomyCanonicalValues
    ScopedArchitecturalView -.->|depends on| ShapeExtraction
    DeclarationLevelShapeTagging -.->|depends on| ShapeExtraction
    DeclarationLevelShapeTagging -.->|depends on| ReferenceDocShowcase
    DataAPIDesignSessionSupport -.->|depends on| DataAPIContextAssembly
    DataAPIDesignSessionSupport -.->|depends on| DataAPIStubIntegration
    DataAPIContextAssembly -.->|depends on| DataAPIOutputShaping
    DataAPIContextAssembly -.->|depends on| DataAPIStubIntegration
    CrossCuttingDocumentInclusion -.->|depends on| DeclarationLevelShapeTagging
    CrossCuttingDocumentInclusion -.->|depends on| ReferenceDocShowcase
    CodecDrivenReferenceGeneration -.->|depends on| DocGenerationProofOfConcept
    CodecDrivenReferenceGeneration -.->|depends on| ScopedArchitecturalView
    ExtractionPipelineEnhancementsTesting ..->|implements| ReferenceDocShowcase
    KebabCaseSlugs -.->|depends on| StringUtils
    ErrorHandlingUnification -.->|depends on| ResultMonad
    ErrorHandlingUnification -.->|depends on| ErrorFactories
    RegexBuilders -->|uses| ConfigurationTypes
    ProjectConfigTypes -->|uses| ConfigurationTypes
    ProjectConfigTypes -->|uses| ConfigurationPresets
    ReferenceDocShowcase -.->|depends on| CodecDrivenReferenceGeneration
    ReferenceDocShowcase -.->|depends on| ScopedArchitecturalView
    ReferenceDocShowcase -.->|depends on| ShapeExtraction
    DocGenerationProofOfConcept -.->|depends on| ShapeExtraction
    classDef neighbor stroke-dasharray: 5 5
```

---
