archidoc

archidoc pulls your architecture — module boundaries, dependency edges, and GoF pattern contracts — straight from comments in your code, turns them into docs and LLM context, and fails your CI build if they fall out of sync.

What It Does

Archidoc gives AI and humans high-level intent, mid-level structure, and links to details all in one enforcible file. Archidoc pulls your architecture — module boundaries, dependency edges, and GoF pattern contracts — straight from comments in your code, turns them into docs and LLM context, and fails your CI build if they fall out of sync.

Developers annotate module entry files (mod.rs, index.ts, __init__.py) with structured comments containing C4 markers, GoF pattern labels, and file-level responsibility tables. archidoc compiles these annotations into a single ARCHITECTURE.md containing:

• Inline Mermaid C4 diagrams (container and component levels)
• Component index table (linking directly to source files)
• Relationship map (dependency arrows with labels and protocols)
• AI context file (ARCHITECTURE.ai.md) — token-optimized tree format for LLM consumption (~75% fewer tokens)
• JSON IR (portable intermediate representation for cross-language pipelines)

Optional sidecar outputs: PlantUML (--plantuml) and draw.io CSV (--drawio). The AI context file is generated by default (suppress with --no-ai).

It also detects architecture drift (docs out of sync with code), validates file tables (ghost/orphan detection), and reports architecture health (pattern confidence, file maturity).

Install

# From crates.io
cargo install archidoc-cli

# Or from source
cargo install --path core/archidoc-cli

# Or build locally
cargo build --release
# Binary at target/release/archidoc

# TypeScript adapter (npm)
npm install archidoc-ts

Usage

# Generate ARCHITECTURE.md + ARCHITECTURE.ai.md from source annotations
archidoc .

# Custom output path
archidoc . -o docs/ARCHITECTURE.md

# Skip AI context generation
archidoc . --no-ai

# Also generate PlantUML and/or draw.io sidecar files
archidoc . --plantuml --drawio

# Scaffold root-level lib.rs template for a new project
archidoc init

# Scaffold with explicit language (if auto-detection fails)
archidoc init --lang rust
archidoc init --lang ts

# Generate annotation template for a module directory
archidoc suggest src/api/

# Write the template directly into a module entry file
archidoc suggest src/api/ >> src/api/mod.rs

# Check for documentation drift (CI gate — exits non-zero on drift)
archidoc --check .

# Print architecture health report
archidoc --health .

# Validate file tables (ghost/orphan detection)
archidoc --validate .

# Export JSON IR for cross-language pipelines
archidoc --emit-ir .

# Generate ARCHITECTURE.md from JSON IR (any language adapter)
archidoc --from-json-file ir.json .

# Merge IR from multiple adapters (polyglot projects)
archidoc --merge-ir --from-json-file rust.json --from-json-file ts.json .

Annotation Convention

Container-level (mod.rs):

//! @c4 container
//!
//! # Bus Module
//!
//! Central messaging and caching backbone.
//!
//! @c4 uses agents_internal "Processed market data" "crossbeam channel"
//!
//! | File | Pattern | Purpose | Health |
//! |------|---------|---------|--------|
//! | `lanes.rs` | Observer | Event routing channels | active |
//! | `store.rs` | Repository | Lock-free cache | stable |

TypeScript (index.ts):

/**
 * @c4 container
 *
 * Central messaging and caching backbone.
 *
 * @c4 uses agents_internal "Processed market data" "WebSocket"
 *
 * | File | Pattern | Purpose | Health |
 * |------|---------|---------|--------|
 * | `core.ts` | Facade | Entry point | stable |
 */

C4 Markers

• @c4 container — marks a C4 container
• @c4 component — marks a C4 component
• @c4 uses target "label" "protocol" — declares a dependency

File Table

Each row declares a file in the module with its GoF pattern, purpose, and health status:

Pattern Confidence

Pattern labels have two tiers:

• planned — developer's stated intent
• verified — structurally confirmed by heuristic analysis (Observer, Strategy, Facade)

Getting Started

Greenfield (new project)

1. Scaffold the root template — generates a lib.rs / index.ts doc comment with TODO sections for purpose, C4 context, data flow, concurrency patterns, deployment, and external dependencies:

   archidoc init                   # auto-detects Rust/TS from Cargo.toml or package.json
   archidoc init --lang rust       # explicit
   

   Paste the output into your root entry file (lib.rs or index.ts) and fill in the TODOs.

2. Add module annotations — as you create modules, scaffold their annotations:

   archidoc suggest src/api/       # generates a @c4 container/component template
   archidoc suggest src/api/ >> src/api/mod.rs
   

3. Generate docs:

   archidoc .
   

   This produces ARCHITECTURE.md (human-readable) and ARCHITECTURE.ai.md (token-optimized for LLMs).

Brownfield (existing project)

1. Pick your top-level modules — identify the 3-5 directories that represent your system's major containers (e.g. api/, core/, database/)

2. Scaffold annotations for each module:

   archidoc suggest src/api/       # prints a ready-to-paste annotation block
   

3. Add a C4 marker to each module's entry file (mod.rs, index.ts, or __init__.py):

   //! @c4 container
   //!
   //! # Api
   //!
   //! REST API gateway — handles authentication and request routing.
   

4. Run archidoc to generate your first diagrams:

   archidoc .
   

5. Optionally scaffold the root — if you want data flow, concurrency, and deployment sections in your docs:

   archidoc init >> src/lib.rs     # append the template, then fill in the TODOs
   

6. Add relationships between containers:

   //! @c4 uses database "Persists user data" "sqlx"
   

7. Gate your CI to prevent architecture drift:

   archidoc --check .
   

Start with containers only. Add components, file tables, and relationships as the architecture stabilizes. See Annotating Your Project for the full step-by-step guide.

Project Structure

Cargo.toml              Workspace root
core/
  archidoc-types/       Shared types (ModuleDoc, C4Level, FileEntry, Relationship, etc.)
  archidoc-engine/      Language-agnostic generator (ARCHITECTURE.md, ai context, mermaid, plantuml, draw.io, IR, drift, health)
  archidoc-cli/         CLI binary: archidoc
  spec/                 JSON IR schema
  tests/                BDD test infrastructure (DSL, protocol drivers, fakes)
adapters/
  archidoc-rust/        Rust adapter (//! doc comments -> ModuleDoc)
  archidoc-ts/          TypeScript adapter (@c4 JSDoc -> JSON IR)
docs/                   Guides (annotation spec, getting started, LLM context)
examples/               Example annotated projects

Architecture

archidoc follows a three-layer architecture:

1. Types (archidoc-types) — shared domain model: ModuleDoc, C4Level, FileEntry, Relationship, PatternStatus, HealthStatus
2. Adapters (archidoc-rust, archidoc-ts) — language-specific parsers that extract annotations and emit ModuleDoc arrays
3. Engine (archidoc-engine) — language-agnostic generators that consume ModuleDoc and produce ARCHITECTURE.md, diagrams, IR, drift reports, and health summaries

The CLI orchestrates: adapter parses source -> engine generates ARCHITECTURE.md.

JSON IR

The intermediate representation (ModuleDoc[] as JSON) is the contract between adapters and the engine. Any language adapter that emits conforming JSON can use the full engine pipeline. See core/spec/archidoc-ir-schema.json for the schema.

Writing a Language Adapter

To add support for a new language:

1. Scaffold with archidoc init-adapter --lang python
2. Implement a parser that extracts annotations from your language's comment format
3. Implement a walker that traverses source directories and collects ModuleDoc entries
4. Emit ModuleDoc[] JSON to stdout — the engine handles the rest

See the archidoc-rust and archidoc-ts adapters for reference implementations.

Tests

# Run all Rust tests
cargo test

# Run TypeScript adapter tests
cd adapters/archidoc-ts && npm test

The test suite uses Dave Farley-style BDD: declarative test cases specify WHAT (behavior), protocol drivers translate to HOW (implementation). When the implementation changes, update drivers — not tests.

License

MIT