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.

```markdown
# 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.

```markdown
# 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.

```markdown
# 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**:
```rust
// 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**:
```toml
# 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

```bash
# 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](https://rust-lang.github.io/mdBook/)

---

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