Vapora/docs/adrs/0027-documentation-layers.md

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:

// 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)