MBPanel Documentation System User Guide¶

Version: 2.1 | Last Updated: 2026-01-06 | Status: Stable

Overview¶

The MBPanel documentation system provides automated documentation generation for architecture decisions, product requirements, tasks, implementation notes, test reports, and error tracking. Built on MkDocs with Material theme and mkdocstrings for Python API documentation.

Key capabilities: - Create ADRs, PRDs, ADDs, Tasks, and implementation notes from templates - Generate test reports from pytest JSON output - Track errors with status and resolution - Build cross-reference index for all documents - Git hooks for validation and automatic updates

Architecture¶

graph TB
    CLI[tools/docs/cli.py] --> Agent[DocumentationAgent]
    CLI --> Generators[Document Generators]
    Generators --> Core[Core Generator]
    Core --> Cache[Build Cache]
    Generators --> Templates[Jinja2 Templates]
    CLI --> Indexer[Cross-Reference Indexer]

    MkDocs[MkDocs Build] --> API[mkdocstrings Python API]
    MkDocs --> Static[Static HTML Output]

    Git[Git Hooks] --> PreCommit[pre-commit validation]
    Git --> PostMerge[post-merge index update]

    PreCommit --> CLI
    PostMerge --> CLI

    style CLI fill:#e1f5ff
    style Generators fill:#fff4e1
    style MkDocs fill:#e8f5e9

Prerequisites¶

Required Dependencies¶

Python 3.12+
MkDocs Material >= 9.5.0
mkdocstrings[python] >= 0.24.0
mkdocs-section-index >= 0.3.0
ijson >= 3.3 (for large test files)
PyYAML >= 6.0
jinja2 >= 3.1.2
click >= 8.1.0

Installation¶

# Install backend dependencies (includes documentation tools)
cd backend
pip install --no-deps -c constraints.txt -e .

# Install documentation tools
pip install -e .

# Install git hooks
./tools/hooks/install.sh

Environment Setup¶

# Set Python binary (optional)
export PYTHON_BIN=python3.12

# Verify installation
python -m tools.docs.cli --version
# Output: Version 2.1

Quick Start¶

Create an Architecture Decision Record (ADR)¶

# Interactive mode
python -m tools.docs.cli create-adr

# Prompts for:
# - ADR Title: Use PostgreSQL for session storage
# - Context/Background: Current Redis-based sessions...
# - Decision: Migrate to PostgreSQL
# - Consequences: Migration required, improved durability...

Output: Creates docs/architecture/adr/001-2026-01-06-use-postgresql.md

Generate Test Report¶

# From pytest JSON output
python -m tools.docs.cli document-tests \
    backend/test-results.json \
    --coverage backend/coverage.json

# Output: docs/operations/test-reports/2026-01-06-test-report.md

Build Cross-Reference Index¶

# Full index rebuild
python -m tools.docs.cli build-index

# Incremental update (after git pull)
python -m tools.docs.cli build-index --incremental

View Build Cache Information¶

python -m tools.docs.cli cache-info
# Output:
# Cache version: 2.1
# Indexed at: 2026-01-06T12:00:00Z
# Files tracked: 42
# Templates tracked: 8
# Configs tracked: 1

CLI Command Reference¶

`create-adr`¶

Create an Architecture Decision Record interactively.

Usage:

python -m tools.docs.cli create-adr

Prompts: - --title: ADR title (required) - --context: Background and context (required) - --decision: The decision being made (required) - --consequences: Consequences of this decision (required)

Example:

python -m tools.docs.cli create-adr \
    --title "Use PostgreSQL for sessions" \
    --context "Current Redis-based sessions lack durability..." \
    --decision "Migrate to PostgreSQL with JSONB column" \
    --consequences "Migration required, improved durability"

Output: docs/architecture/adr/{number}-{date}-{slug}.md

`create-prd`¶

Create a Product Requirements Document.

Usage:

python -m tools.docs.cli create-prd

Prompts: - --title: PRD title (required) - --problem: Problem statement (required) - --solution: Proposed solution (required) - --success-metrics: Success criteria (required)

Example:

python -m tools.docs.cli create-prd \
    --title "Multi-region deployment" \
    --problem "Customers need data locality..." \
    --solution "Deploy to multiple AWS regions..." \
    --success-metrics "Latency < 100ms, 99.9% uptime"

Output: docs/prd/{number}-{date}-{slug}.md

`create-task`¶

Create a task document.

Usage:

python -m tools.docs.cli create-task

Prompts: - --title: Task title (required) - --description: Task description (required) - --status: Status (default: "backlog") - --assignee: Assigned to (optional)

Example:

python -m tools.docs.cli create-task \
    --title "Implement session migration" \
    --description "Migrate existing sessions from Redis to PostgreSQL" \
    --status "active" \
    --assignee "team-backend"

Output: docs/task/{status}/{number}-{date}-{slug}.md

`document-tests`¶

Generate test execution report from pytest JSON output.

Usage:

python -m tools.docs.cli document-tests TEST_RESULTS [--coverage COVERAGE]

Parameters:

Name	Type	Required	Description	Default
TEST_RESULTS	Path	Yes	Path to pytest JSON report	-
--coverage	Path	No	Path to coverage JSON file	None

Example:

# Run pytest with JSON output
pytest --json-report --json-report-file=test-results.json

# Generate documentation
python -m tools.docs.cli document-tests \
    backend/test-results.json \
    --coverage backend/coverage.json

Output: docs/operations/test-reports/{date}-test-report.md

Features: - Streaming for files > 10MB (uses ijson) - Graceful handling of truncated data - Coverage summary integration - Failure analysis and recommendations

`build-index`¶

Build cross-reference index for all documentation.

Usage:

python -m tools.docs.cli build-index [--incremental]

Parameters:

Name	Type	Required	Description	Default
--incremental	flag	No	Update only changed files	False

Example:

# Full rebuild
python -m tools.docs.cli build-index

# Incremental update (faster)
python -m tools.docs.cli build-index --incremental

Output: docs/.index/cross_refs.json

Index structure:

{
  "version": "2.1",
  "documents": {
    "path/to/doc.md": {
      "title": "Document Title",
      "type": "adr",
      "components": ["sites", "api"],
      "references": [],
      "status": "Accepted",
      "date": "2026-01-06"
    }
  },
  "by_component": {
    "sites": ["doc1.md", "doc2.md"]
  },
  "by_type": {
    "adr": [],
    "prd": [],
    "add": [],
    "task": []
  },
  "indexed_at": "2026-01-06T12:00:00Z"
}

`generate-api-docs`¶

Generate API documentation from Python docstrings.

Usage:

python -m tools.docs.cli generate-api-docs -m MODULE [-m MODULE ...]

Parameters:

Name	Type	Required	Description	Default
-m, --module	string	Yes	Python module path (repeatable)	-

Example:

# Generate docs for specific modules
python -m tools.docs.cli generate-api-docs \
    -m app.domains.sites.service \
    -m app.domains.environments.service

# Output: docs/api/reference/app_domains_sites_service.md

Features: - Automatic fallback for parse errors - Circular import detection - Success/error summary - mkdocstrings-compatible output

`cache-clear`¶

Clear build cache to force full rebuild.

Usage:

python -m tools.docs.cli cache-clear

Use when: - Cache corruption detected - Template changes not reflected - Stale build artifacts

`cache-info`¶

Display build cache statistics.

Usage:

python -m tools.docs.cli cache-info

Output:

Cache version: 2.1
Indexed at: 2026-01-06T12:00:00Z
Files tracked: 42
Templates tracked: 8
Configs tracked: 1

`context`¶

Get documentation context for a component (experimental).

Usage:

python -m tools.docs.cli context COMPONENT

Example:

python -m tools.docs.cli context sites

# Returns JSON with:
# - Related ADRs
# - API documentation
# - Test results
# - Error documentation
# - Implementation notes

Document Types¶

Architecture Decision Record (ADR)¶

Purpose: Record significant architectural decisions

Location: docs/architecture/adr/{number}-{date}-{slug}.md

Required fields: - status: Proposed, Accepted, Deprecated, Superseded - date: ISO format date - context: Background and problem statement - decision: The decision made - consequences: Impact of this decision

Optional fields: - alternatives: List of considered alternatives - related_documents: Links to related docs

Example:

# ADR 001: Use PostgreSQL for Sessions

**Status:** Accepted
**Date:** 2026-01-06

## Context
Current Redis-based sessions lack durability...

## Decision
Migrate to PostgreSQL with JSONB column...

## Consequences
Migration required, improved durability...

## Alternatives Considered
### Memcached
Faster but less durable...

## Related Documents
- [Session Management](../implementation/sessions.md) (implementation)

Product Requirements Document (PRD)¶

Purpose: Define product features and requirements

Location: docs/prd/{number}-{date}-{slug}.md

Required fields: - status: Draft, Review, Approved, Implemented - priority: P0, P1, P2, P3 - stakeholders: List of stakeholders

Example:

# PRD 001: Multi-Region Deployment

**Status:** Draft
**Priority:** P0
**Stakeholders:** Product, Engineering, DevOps

## Problem Statement
Customers need data locality...

## Proposed Solution
Deploy to multiple AWS regions...

## Success Metrics
- Latency < 100ms for 95% of requests
- 99.9% uptime SLA
- Zero data loss in failure scenarios

Architecture Design Document (ADD)¶

Purpose: Detailed technical design for architecture

Location: docs/architecture/add/{domain}/{slug}.md

Required fields: - status: Draft, Review, Approved, Implemented - author: Document author - last-reviewed: Review date

Example:

# ADD: Session Storage Architecture

**Status:** Review
**Author:** Jane Doe <jane@example.com>
**Last Reviewed:** 2026-01-06

## Overview
Design for PostgreSQL-based session storage...

## Architecture Diagram
```mermaid
...diagram code...

Data Model¶

CREATE TABLE sessions (...);

API Design¶

POST /api/v1/sessions GET /api/v1/sessions/{id}

### Task Document

**Purpose:** Track development tasks

**Location:** `docs/task/{status}/{number}-{date}-{slug}.md`

**Status values:**
- `backlog`: Not started
- `active`: In progress
- `completed`: Done
- `blocked`: Waiting on dependency

**Required fields:**
- `status`: Task status
- `assignee`: Who is assigned
- `priority`: P0, P1, P2, P3

**Example:**
```markdown
# Task 001: Implement Session Migration

**Status:** active
**Assignee:** team-backend
**Priority:** P0

## Description
Migrate existing sessions from Redis to PostgreSQL...

## Acceptance Criteria
- [ ] All existing sessions migrated
- [ ] Zero downtime during migration
- [ ] Rollback procedure tested

## Related Documents
- [ADR 001](../../architecture/adr/001-2026-01-06-use-postgresql.md)
- [PRD 001](../../prd/001-2026-01-06-multi-region.md)

Implementation Note¶

Purpose: Document implementation details and learnings

Location: docs/implementation/{domain}/{slug}.md

Example:

# Implementation: PostgreSQL Session Storage

**Component:** sessions
**Date:** 2026-01-06
**Author:** Jane Doe

## Approach
Used JSONB column for session data...

## Challenges
- Large session objects caused slow queries
- Solved with partial indexes

## Lessons Learned
- Always index on user_id
- Consider session size limits

Error Documentation¶

Purpose: Track recurring errors and resolutions

Location: docs/operations/errors/{status}/{slug}.md

Status values: - active: Unresolved - monitoring: Watching for recurrence - resolved: Fixed and verified

Example:

# Error: Database Connection Pool Exhaustion

**Status:** resolved
**First Seen:** 2026-01-06
**Last Seen:** 2026-01-07
**Occurrences:** 12

## Symptoms
- API timeouts during peak load
- "Pool exhausted" errors in logs

## Root Cause
Connection pool size too small for traffic spike

## Resolution
Increased pool size from 10 to 50

## Prevention
- Add connection pool metrics
- Set up alerts for pool exhaustion

Test Report¶

Purpose: Document test execution results

Location: docs/operations/test-reports/{date}-test-report.md

Generated automatically from pytest JSON output.

Example:

# Test Report: 2026-01-06

## Summary
- **Total Tests:** 1,234
- **Passed:** 1,230 (99.7%)
- **Failed:** 4 (0.3%)
- **Skipped:** 0
- **Duration:** 5m 23s

## Coverage
- **Overall:** 87.3%
- **Core:** 95.1%
- **Domains:** 82.4%

## Failures
### test_session_migration
**Error:** AssertionError: Session not migrated
**File:** tests/unit/domains/test_sessions.py:42
**Fix:** Migration script missing for expired sessions

## Recommendations
- Increase coverage in domains/ to 85%
- Add integration tests for migration

Using the AI Agent Interface¶

The DocumentationAgent class provides a Python API for AI agents to create documentation programmatically.

Quick Start¶

from pathlib import Path
from tools.docs.agents import DocumentationAgent
from tools.docs.generators import ADRGenerator, PRDGenerator

# Initialize agent
docs_root = Path("/path/to/docs")
agent = DocumentationAgent(docs_root)

# Register generators
agent.register_generator("adr", ADRGenerator(docs_root))
agent.register_generator("prd", PRDGenerator(docs_root))

# Create an ADR
adr_path = agent.create_adr(
    title="Use PostgreSQL",
    context="Need relational database...",
    decision="Adopt PostgreSQL",
    consequences="Migration required"
)
print(f"Created: {adr_path}")

Agent Methods¶

`create_adr()`¶

Create an Architecture Decision Record.

Parameters:

Name	Type	Required	Description	Default
title	str	Yes	ADR title	-
context	str	Yes	Background and context	-
decision	str	Yes	The decision	-
consequences	str	Yes	Consequences	-
status	str	No	ADR status	"Proposed"
alternatives	List[Dict]	No	Alternatives considered	[]
related_documents	List[Dict]	No	Related docs	[]

Returns: Path - Path to created ADR

Example:

adr = agent.create_adr(
    title="Use PostgreSQL for sessions",
    context="Current Redis lacks durability",
    decision="Migrate to PostgreSQL",
    consequences="Migration required, improved durability",
    status="Accepted",
    alternatives=[
        {
            "name": "Memcached",
            "description": "Faster but less durable",
            "pros": ["Lower latency", "Simpler"],
            "cons": ["No persistence", "Limited features"]
        }
    ]
)

`create_prd()`¶

Create a Product Requirements Document.

Parameters:

Name	Type	Required	Description	Default
title	str	Yes	PRD title	-
problem	str	Yes	Problem statement	-
solution	str	Yes	Proposed solution	-
success_metrics	List[str]	Yes	Success criteria	-
status	str	No	PRD status	"Draft"
priority	str	No	Priority level	"P2"
stakeholders	List[str]	No	Stakeholders	[]

Example:

prd = agent.create_prd(
    title="Multi-region deployment",
    problem="Customers need data locality",
    solution="Deploy to multiple AWS regions",
    success_metrics=[
        "Latency < 100ms for 95% requests",
        "99.9% uptime SLA",
        "Zero data loss"
    ],
    status="Draft",
    priority="P0",
    stakeholders=["Product", "Engineering", "DevOps"]
)

`create_task()`¶

Create a task document.

Parameters:

Name	Type	Required	Description	Default
title	str	Yes	Task title	-
description	str	Yes	Task description	-
status	str	No	Task status	"backlog"
assignee	str	No	Assigned to	None
priority	str	No	Priority	"P2"

Example:

task = agent.create_task(
    title="Implement session migration",
    description="Migrate sessions from Redis to PostgreSQL",
    status="active",
    assignee="team-backend",
    priority="P0"
)

`document_test_run()`¶

Generate test report from pytest JSON.

Parameters:

Name	Type	Required	Description	Default
test_results_path	str	Yes	Path to pytest JSON	-
coverage_path	str	No	Path to coverage JSON	None

Example:

report = agent.document_test_run(
    test_results_path="backend/test-results.json",
    coverage_path="backend/coverage.json"
)

`get_context()`¶

Get documentation context for a component.

Parameters:

Name	Type	Required	Description	Default
component	str	Yes	Component name	-

Returns: Dict[str, Any] - Context with ADRs, API docs, tests, errors

Example:

context = agent.get_context("sites")

# Returns:
# {
#     "adrs": [{"title": "...", "status": "..."}],
#     "api_docs": [{"title": "...", "path": "..."}],
#     "test_results": {"passed": 100, "failed": 0},
#     "errors": [],
#     "implementation_notes": []
# }

Error Handling¶

from tools.docs.agents import (
    GeneratorNotFoundError,
    InvalidMetadataError,
    FileLoadError
)

# Generator not registered
try:
    agent.create_document("unknown", {})
except GeneratorNotFoundError as e:
    print(f"Error: {e}")
    print(f"Available: {e.available_generators}")

# Invalid metadata
try:
    agent.create_adr("", "", "", "")
except InvalidMetadataError as e:
    print(f"Error: {e}")
    print(f"Missing: {e.missing_fields}")

# File load error
try:
    agent.document_test_run("/nonexistent.json")
except FileLoadError as e:
    print(f"Error: {e}")
    print(f"File: {e.file_path}")

Best Practices¶

ADR Best Practices¶

Write ADRs early - Document decisions before implementation
Be specific - Include concrete details, not vague intentions
Document alternatives - Show why other options were rejected
Update status - Mark as Accepted, Deprecated, or Superseded
Link related docs - Connect to PRDs, ADDs, tasks

PRD Best Practices¶

Focus on outcomes - Describe what, not how
Define success - Include measurable success criteria
Identify stakeholders - List who needs to review/approve
Set priority - P0 (critical) to P3 (nice-to-have)
Link to ADRs - Reference architecture decisions

Task Documentation Best Practices¶

One task per document - Keep tasks focused and actionable
Define acceptance criteria - Clear "done" conditions
Track status accurately - Update as work progresses
Assign ownership - Every task should have an assignee
Link to parent docs - Reference PRDs and ADRs

Error Documentation Best Practices¶

Document on first occurrence - Create error doc when first seen
Include error details - Stack traces, logs, reproduction steps
Track occurrences - Update count each time error happens
Document root cause - Don't just fix symptoms
Mark when resolved - Update status after verification

Test Documentation Best Practices¶

Generate automatically - Use document-tests after every run
Include coverage - Pass coverage JSON for complete reports
Analyze failures - Document root cause and fix
Track trends - Compare with previous runs
Link to issues - Reference task docs for failures

Git Integration¶

Let hooks run - Don't bypass pre-commit validation
Fix action items - Resolve or move to issue tracker
Update index - Post-merge hook keeps index current
Review changes - Check generated docs before committing
Version everything - All docs in git, no hidden state

Troubleshooting¶

See troubleshooting.md for detailed problem resolution.

MBPanel Documentation System User Guide¶

Overview¶

Architecture¶

Prerequisites¶

Required Dependencies¶

Installation¶

Environment Setup¶

Quick Start¶

Create an Architecture Decision Record (ADR)¶

Generate Test Report¶

Build Cross-Reference Index¶

View Build Cache Information¶

CLI Command Reference¶

create-adr¶

create-prd¶

create-task¶

document-tests¶

build-index¶

generate-api-docs¶

cache-clear¶

cache-info¶

context¶

Document Types¶

Architecture Decision Record (ADR)¶

Product Requirements Document (PRD)¶

Architecture Design Document (ADD)¶

Data Model¶

API Design¶

Implementation Note¶

Error Documentation¶

Test Report¶

Using the AI Agent Interface¶

Quick Start¶

Agent Methods¶

create_adr()¶

create_prd()¶

create_task()¶

document_test_run()¶

get_context()¶

Error Handling¶

Best Practices¶

ADR Best Practices¶

PRD Best Practices¶

Task Documentation Best Practices¶

Error Documentation Best Practices¶

Test Documentation Best Practices¶

Git Integration¶

Troubleshooting¶

Sources¶

`create-adr`¶

`create-prd`¶

`create-task`¶

`document-tests`¶

`build-index`¶

`generate-api-docs`¶

`cache-clear`¶

`cache-info`¶

`context`¶

`create_adr()`¶

`create_prd()`¶

`create_task()`¶

`document_test_run()`¶

`get_context()`¶