## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

# ADR-027: Three-Layer Documentation System

Status: Accepted | Implemented Date: 2024-11-01 Deciders: Documentation & Architecture Team Technical Story: Separating session work from permanent documentation to avoid confusion

## Decision

Implementar three-layer documentation system: `.coder/` (session), `.claude/` (operational), `docs/` (product).

## Rationale

1. Session Work ≠ Permanent Docs: Claude Code sessions are temporary, not product docs
2. Clear Boundaries: Different audiences (devs, users, operations)
3. Git Structure: Natural organization via directories
4. Maintainability: Easy to distinguish what's authoritative

## Alternatives Considered

### ❌ Single Documentation Folder

- Pros: Simple
- Cons: Session files mixed with product docs, confusion

### ❌ Documentation Only (No Session Tracking)

- Pros: Clean product docs
- Cons: No record of how decisions were made

### ✅ Three Layers (CHOSEN)

- Separates concerns, clear boundaries

## Trade-offs

Pros:

- ✅ Clear separation of concerns
- ✅ Session files don't pollute product docs
- ✅ Different retention/publication policies
- ✅ Audit trail of decisions

Cons:

- ⚠️ More directories to manage
- ⚠️ Naming conventions required
- ⚠️ NO cross-layer links allowed (complexity)

## Implementation

Layer 1: Session Files (`.coder/`):

    .coder/
    ├── 2026-01-10-agent-coordinator-refactor.plan.md
    ├── 2026-01-10-agent-coordinator-refactor.done.md
    ├── 2026-01-11-bug-analysis.info.md
    ├── 2026-01-12-pr-review.review.md
    └── 2026-01-12-backup-recovery-automation.done.md

Naming Convention: `YYYY-MM-DD-description.{plan|done|info|review}.md`

Content: Claude Code interaction records, not product documentation.

    # Agent Coordinator Refactor - COMPLETED

    **Date**: January 10, 2026
    **Status**: ✅ COMPLETE
    **Task**: Refactor agent coordinator to reduce latency

    ---

    ## What Was Done

    1. Analyzed current coordinator performance
    2. Identified bottleneck: sequential task assignment
    3. Implemented parallel task dispatch
    4. Benchmarked: 50ms → 15ms latency

    ---

    ## Key Decisions

    - Use `tokio::spawn` for parallel dispatch
    - Keep single source of truth (still in Arc<RwLock>)

    ## Next Steps

    (User's choice)

Layer 2: Operational Files (`.claude/`):

    .claude/
    ├── CLAUDE.md                      # Project-specific Claude Code instructions
    ├── guidelines/
    │   ├── rust.md
    │   ├── nushell.md
    │   └── nickel.md
    ├── layout_conventions.md
    ├── doc-config.toml
    └── project-settings.json

Content: Claude Code configuration, guidelines, conventions.

    # CLAUDE.md - Project Guidelines

    Senior Rust developer mode. See guidelines/ for language-specific rules.

    ## Mandatory Guidelines

    @guidelines/rust.md
    @guidelines/nushell.md

Layer 3: Product Documentation (`docs/`):

    docs/
    ├── README.md                      # Main documentation index
    ├── architecture/
    │   ├── README.md
    │   ├── overview.md
    │   └── design-patterns.md
    ├── adrs/
    │   ├── README.md                  # ADRs index
    │   ├── 0001-cargo-workspace.md
    │   └── ... (all 27 ADRs)
    ├── operations/
    │   ├── README.md
    │   ├── deployment.md
    │   └── monitoring.md
    ├── api/
    │   ├── README.md
    │   └── endpoints.md
    └── guides/
        ├── README.md
        └── getting-started.md

Content: User-facing, permanent, mdBook-compatible documentation.

    # VAPORA Architecture Overview

    This is permanent product documentation.

    ## Core Components

    - Backend: Axum REST API
    - Frontend: Leptos WASM
    - Database: SurrealDB

Linking Rules:

    ✅ ALLOWED:
    - docs/ → docs/ (internal links)
    - docs/ → external sites
    - .claude/ → .claude/
    - .coder/ → .coder/

    ❌ FORBIDDEN:
    - docs/ → .coder/ (product docs can't reference session files)
    - docs/ → .claude/ (product docs shouldn't reference operational files)
    - .coder/ → docs/ (session files can reference product docs though)

Files and Locations:

    #![allow(unused)]
    fn main() {
    // crates/vapora-backend/src/lib.rs
    //! Product documentation in docs/
    //! Operational guidelines in .claude/guidelines/
    //! Session work in .coder/

    // Example in code:
    // See: docs/adrs/0002-axum-backend.md (✅ OK: product doc)
    // See: .claude/guidelines/rust.md (✅ OK: within operational layer)
    // See: .coder/2026-01-10-notes.md (❌ WRONG: session file in product context)
    }

Documentation Naming:

    docs/
    ├── README.md                  ← UPPERCASE (GitHub convention)
    ├── guides/
    │   ├── README.md
    │   ├── installation.md        ← lowercase kebab-case
    │   ├── deployment-guide.md    ← lowercase kebab-case
    │   └── multi-agent-workflows.md

    .coder/
    ├── 2026-01-12-description.done.md   ← YYYY-MM-DD-kebab-case.extension

    .claude/
    ├── CLAUDE.md                  ← Mixed case (project instructions)
    ├── guidelines/
    │   ├── rust.md               ← lowercase (language-specific)
    │   └── nushell.md

mdBook Configuration:

    # mdbook.toml
    [book]
    title = "VAPORA Documentation"
    authors = ["VAPORA Team"]
    language = "en"
    src = "docs"

    [build]
    create-missing = true

    [output.html]
    default-theme = "light"

Key Files:

- `.claude/CLAUDE.md` (project instructions)
- `.claude/guidelines/` (language guidelines)
- `docs/README.md` (documentation index)
- `docs/adrs/README.md` (ADRs index)
- `.coder/` (session files)

## Verification

    # Check for broken doc layer links
    grep -r "\.coder" docs/ 2>/dev/null  # Should be empty (❌ if not)
    grep -r "\.claude" docs/ 2>/dev/null # Should be empty (❌ if not)

    # Verify session files don't pollute docs/
    ls docs/ | grep -E "^[0-9]"  # Should be empty (❌ if not)

    # Check documentation structure
    [ -f docs/README.md ] && echo "✅ docs/README.md exists"
    [ -f .claude/CLAUDE.md ] && echo "✅ .claude/CLAUDE.md exists"
    [ -d .coder ] && echo "✅ .coder directory exists"

    # Verify naming conventions
    ls .coder/ | grep -v "^[0-9][0-9][0-9][0-9]-"  # Check format

Expected Output:

- No links from docs/ to .coder/ or .claude/
- No session files in docs/
- All documentation layers present
- Naming conventions followed

## Consequences

### Documentation Maintenance

- Session files: temporary (can be archived/deleted)
- Operational files: stable (part of Claude Code config)
- Product docs: permanent (published via mdBook)

### Publication

- Only `docs/` published to users
- `.claude/` and `.coder/` never published
- mdBook builds from docs/ only

### Collaboration

- Team knows where to find what
- No confusion between session work and permanent docs
- Clear ownership: product docs vs operational

### Scaling

- Add new documents naturally
- Layer separation doesn't break as project grows
- mdBook generation automatic

## References

- `.claude/layout_conventions.md` (comprehensive layout guide)
- `.claude/CLAUDE.md` (project-specific guidelines)
- mdBook Documentation

Related ADRs: ADR-024 (Service Architecture), All ADRs (documentation)