Documentation Consolidation - Quick Reference¶

Date: 2025-11-12 Full Plan: Documentation Consolidation Assessment (archived)

TL;DR¶

Goal: Create living documentation using MkDocs Material where documentation lives primarily in source code and is auto-generated.

Current State: 60 markdown files (28,000 lines) in .claude/ Target State: ~10-15 essential guides + auto-generated content from code

Effort: 12-18 days (90 hours) ROI: 93% reduction in handwritten docs, always up-to-date, single source of truth

Core Principle¶

Documentation should live in the source code and be auto-generated, with minimal handwritten guides only where necessary.

What Gets Auto-Generated¶

✅ API Reference - From FastAPI OpenAPI spec (192 endpoints) ✅ Module Documentation - From Python docstrings via mkdocstrings ✅ Database Schema - From SQLAlchemy models + ER diagrams ✅ Configuration Reference - From Pydantic Settings models ✅ Type Reference - From Pydantic models and type hints

What Stays as Markdown¶

Only essential guides (~2,100 lines total):

1. Getting Started (~200 lines)
2. User Guides (~800 lines) - User Management, N8N Integration, Branding
3. Developer Guides (~600 lines) - Architecture, Testing, Deployment
4. Operations (~300 lines) - Troubleshooting, Production Checklist
5. Project (~200 lines) - Roadmap, Contributing, Changelog

Technology Stack¶

Core: MkDocs Material (industry-standard docs framework)

Plugins: - mkdocstrings-python - Generate docs from docstrings - mkdocs-swagger-ui-tag - Embed OpenAPI/Swagger UI - mkdocs-mermaid2-plugin - Diagrams (architecture, ER diagrams) - mkdocs-git-revision-date-localized-plugin - Last updated dates

Documentation Structure¶

docs/
├── getting-started/          # Quick start, installation, first presentation
├── user-guide/               # User management, N8N, branding
├── developer-guide/          # Architecture, testing, deployment
├── api-reference/            # 🤖 Auto-generated API docs (Swagger UI)
├── code-reference/           # 🤖 Auto-generated module docs
├── database/                 # 🤖 Schema + ER diagrams
├── configuration/            # 🤖 Environment variables reference
├── operations/               # Troubleshooting, monitoring
├── project/                  # Roadmap, changelog, contributing
└── archive/                  # Historical reports (51 files)

🤖 = Auto-generated from source code

Implementation Phases¶

Phase 1: Foundation (2-3 days)¶

Set up MkDocs, create core pages, configure auto-generation

Phase 2: Auto-Generated Docs (3-4 days)¶

API docs, module docs, database schema, config reference

Phase 3: Consolidate Existing Docs (2-3 days)¶

Migrate and consolidate .claude docs (28,000 → 2,100 lines)

Phase 4: Improve Source Code Docs (3-5 days)¶

Fill docstring gaps in context, auth, util modules

Phase 5: Polish & Deploy (1-2 days)¶

Custom CSS (Shadcn-inspired), diagrams, CI/CD integration

Phase 6: Maintenance (1 day)¶

Archive reports, documentation guidelines, update CLAUDE.md

Quick Start Commands¶

# Install dependencies
pip install -r requirements-docs.txt

# Serve locally
mkdocs serve
# Open http://127.0.0.1:8000

# Build static site
mkdocs build

# Deploy to GitHub Pages
mkdocs gh-deploy

Success Metrics¶

Quantitative: - ✅ 93% reduction in handwritten docs (28,000 → 2,100 lines) - ✅ 80%+ docstring coverage across all modules - ✅ Build time < 60 seconds - ✅ Page load < 2 seconds

Qualitative: - ✅ Developers find API docs in < 30 seconds - ✅ New users get started in < 10 minutes - ✅ Docs stay up-to-date automatically - ✅ Single source of truth (no duplicates)

Key Benefits¶

1. Always Up-to-Date - Auto-generated from code
2. Single Source of Truth - Documentation lives in codebase
3. Less Maintenance - 93% fewer handwritten docs to maintain
4. Better DX - Interactive API docs, code examples, type hints
5. CI/CD Integration - Deploys automatically on commit

Current Documentation Health¶

Well-Documented (80%+ coverage): - ✅ API Endpoints (192 endpoints via FastAPI) - ✅ Workflow Engine (98%) - ✅ File Manager (98%) - ✅ N8N Manager (100%)

Needs Work (<50% coverage): - ❌ Context Module (9.1%) - RAG/vector search - ❌ Auth Module (15%) - Session management - ❌ Util Module (26%) - 23 utility files - ❌ Main Application (31%)

Priority: Phase 4 will improve these modules to 80%+

Archive Strategy¶

Implementation Reports (51 files, 23,713 lines): - Keep in .claude/../reports/technical/ for Claude Code context - Create searchable index in docs/archive/ - Link to GitHub tree view - These are historical notes, not user-facing docs

Next Steps¶

1. Review Plan - Get stakeholder approval
2. Create docs/ Directory - Set up MkDocs structure
3. Install Plugins - MkDocs Material + plugins
4. Test Auto-Generation - Start with one module (e.g., app.ai)
5. Iterate - Build incrementally, phase by phase

Questions?¶

See full plan with detailed implementation steps, examples, and configuration: 📖 Documentation Consolidation Assessment (archived)

Recommendation: Start with Phase 1-2 (auto-generation) for immediate value, then consolidate existing docs in Phase 3.