Skip to content

ADR 003: Documentation Site Architecture

Status

Accepted

Context

The arbiter-bot project has accumulated significant documentation: - Spec: docs/spec/requirements.md - Comprehensive FRS with 50+ functional requirements - ADRs: docs/adrs/001-connectivity-check.md, 002-dry-run-safety.md - Architecture: docs/architecture/index.md - Main system architecture - Plans: Implementation phase plans in docs/development/plans/ - Reviews: docs/reviews/design_review_01.md, design_review_02.md - Traceability: docs/development/ledger.md

This documentation existed as raw markdown files without: 1. Unified navigation and search 2. Public accessibility for contributors/users 3. Blog infrastructure - CLAUDE.md mandates: "Each change requires a developer-centric blog post in docs/blog/ explaining the intent, decision-making process, and implementation examples." 4. Consistent styling matching amiable-dev organization standards

Decision

Implement MkDocs with Material theme, deployed to GitHub Pages via GitHub Actions.

Alternatives Considered

Alternative Pros Cons Verdict
MkDocs Material Org consistency (amiable-templates.dev), blog plugin, Python-based Python dep in Rust project Selected
mdBook Rust-native, used by Rust ecosystem No blog plugin, limited theming Rejected
Docusaurus React-based, rich features Node.js dep, heavier build Rejected
GitHub Wiki Zero config, built-in No blog, limited navigation Rejected

Primary driver: Organization alignment with amiable-templates.dev enables shared patterns and developer familiarity.

Site Structure

docs/
├── index.md                    # Landing page
├── getting-started/            # Installation, config, first run
├── architecture/               # Actor model, saga pattern, exchange clients
├── spec/                       # Requirements (existing requirements.md)
├── adrs/                       # ADRs (existing + new)
├── development/                # TDD, council review, ledger, contributing
├── reference/                  # CLI, environment variables
├── blog/                       # Engineering blog posts
└── reviews/                    # Council reviews (existing)

Security Considerations

Content Review Checklist (required before publishing): - [ ] No API keys, private keys, or credentials in examples - [ ] No internal IP addresses or hostnames - [ ] No specific wallet addresses used in production - [ ] Architecture diagrams reviewed for security-sensitive details - [ ] CLI examples use placeholder values (e.g., YOUR_API_KEY) - [ ] No internal tooling paths exposed

Dependency Security: - Pin all MkDocs plugin versions in requirements-docs.txt - Run pip-audit in CI before deployment

Consequences

Positive

  • Discoverability via full-text search
  • Workflow compliance (blog infrastructure for CLAUDE.md requirement)
  • Organization consistency (matches amiable-templates.dev)
  • Public accessibility for contributors

Negative

  • Python dependency (~30-60s CI build time)
  • Navigation duplication (mkdocs.yml nav: vs file structure)
  • Learning curve for MkDocs structure

Neutral

  • Requires GitHub Pages enablement on repository
  • Blog posts add ongoing documentation effort (already required by CLAUDE.md)

Verification

  • Site builds with mkdocs build --strict
  • Local preview with mkdocs serve
  • Deployed to https://amiable-dev.github.io/arbiter-bot/
  • Reviewed and approved by LLM Council (Reasoning Tier)