Documentation Site¶
This document defines the public-facing documentation site for the Chaverim ALPR Platform, providing access to architecture and feature documentation for stakeholders.
Document Status: Proposed Last Updated: 2025-12-30
Table of Contents¶
1. Overview¶
The documentation site provides a public web interface for Chaverim stakeholders to access project documentation without requiring GitHub access.
URL: docs.chvrm.flowcmd.io
Goals: - Provide non-technical stakeholders access to project status and features - Present architecture documentation in a readable, navigable format - Eliminate need for GitHub access to read documentation - Mobile-friendly for field access
2. Target Audience¶
| Audience | Needs | Access |
|---|---|---|
| Chaverim Executive | Project status, features, high-level architecture | Public |
| Chaverim Members | Feature overview, terminology, system capabilities | Public |
| Technical Team | Architecture details, patterns, implementation guides | Public |
| External Partners | System overview, integration points | Public |
Non-goals:
- Internal task tracking (remains in docs/phases/)
- Issue tracking (remains in docs/issues/)
- Testing documentation (developer-only)
3. Content Structure¶
Included Documentation¶
The following documentation is exposed publicly:
| Source File | Site Section | Purpose |
|---|---|---|
docs/PROJECT_TRACKER.md |
Home | Project status and phase progress |
docs/FEATURES.md |
Features | Feature list and descriptions |
docs/GLOSSARY.md |
Glossary | Terminology definitions |
docs/architecture/*.md |
Architecture | System design documents |
docs/prp/*.md |
Patterns | Implementation patterns |
Excluded Documentation¶
The following remains internal (not exposed):
| Source | Reason |
|---|---|
docs/phases/ |
Internal task tracking |
docs/issues/ |
Internal issue tracking |
docs/testing/ |
Developer-only |
CLAUDE.md |
Development workflow |
Site Navigation¶
docs.chvrm.flowcmd.io/
├── Home (PROJECT_TRACKER.md)
├── Features
│ └── Feature List (FEATURES.md)
├── Glossary (GLOSSARY.md)
├── Architecture
│ ├── Overview (ARCHITECTURE.md)
│ ├── Monorepo (monorepo.md)
│ ├── Camera Adapters (camera-adapters.md)
│ ├── Ingest Service (ingest-service.md)
│ ├── Alert Engine (alert-engine.md)
│ ├── ... (all architecture docs)
│ └── Open Decisions (open-decisions.md)
└── Patterns
├── Global Patterns (global.md)
└── ... (component PRPs)
4. Technology Choice¶
Selected: MkDocs Material¶
| Criteria | MkDocs Material | Docusaurus | GitBook |
|---|---|---|---|
| Markdown native | Yes | Yes | Yes |
| Python ecosystem | Yes | No (Node.js) | No (SaaS) |
| Self-hosted | Yes | Yes | Paid |
| Search | Built-in | Built-in | Built-in |
| Mobile-responsive | Yes | Yes | Yes |
| Complexity | Low | Medium | Low |
Decision: MkDocs Material
Rationale: 1. Reads existing Markdown files directly (no conversion needed) 2. Fits Python ecosystem (matches backend stack) 3. Excellent mobile experience (important for field use) 4. Built-in search without external dependencies 5. Simple configuration and maintenance 6. Beautiful default theme with customization options
5. Architecture¶
Container Architecture¶
┌─────────────────────────────────────────────────────────┐
│ docs container │
│ │
│ ┌─────────────────┐ ┌─────────────────────────────┐ │
│ │ MkDocs │ │ docs/ (volume mount) │ │
│ │ serve │◄───│ ├── PROJECT_TRACKER.md │ │
│ │ (port 8080) │ │ ├── FEATURES.md │ │
│ │ │ │ ├── GLOSSARY.md │ │
│ │ │ │ ├── architecture/*.md │ │
│ │ │ │ └── prp/*.md │ │
│ └─────────────────┘ └─────────────────────────────┘ │
│ │ │
│ │ mkdocs.yml (site config) │
│ │ │
└───────────┼─────────────────────────────────────────────┘
│
▼
Traefik (docs.chvrm.flowcmd.io)
Build vs Serve¶
| Mode | Use Case | Performance |
|---|---|---|
mkdocs serve |
Development, live reload | Dynamic |
mkdocs build |
Production, static files | Fast, cacheable |
Recommendation: Use mkdocs build in production with nginx or static file server for best performance and caching.
Configuration¶
Key MkDocs Material features to enable:
| Feature | Purpose |
|---|---|
| Search | Full-text search across all docs |
| Navigation tabs | Top-level section navigation |
| Table of contents | Per-page navigation |
| Dark mode | User preference toggle |
| Mobile navigation | Responsive menu |
Branding¶
| Element | Value |
|---|---|
| Site name | Chaverim ALPR Documentation |
| Logo | Chaverim logo (if available) |
| Primary color | Chaverim brand color |
| Favicon | Chaverim favicon |
6. Deployment¶
Docker Integration¶
The docs site runs as part of the central server Docker Compose stack:
| Service | Image | Purpose |
|---|---|---|
docs |
squidfunk/mkdocs-material |
Documentation site |
Volume Mounts¶
| Host Path | Container Path | Purpose |
|---|---|---|
./docs/ |
/docs/docs/ |
Markdown source files |
./mkdocs.yml |
/docs/mkdocs.yml |
Site configuration |
Note: The /docs/docs/ path is the MkDocs Material convention: /docs/ is the working directory, and docs/ within it is the source directory for markdown files.
Update Process¶
Documentation updates automatically when:
1. Changes are pushed to main branch
2. Container is restarted (picks up new files)
For immediate updates without restart, use mkdocs serve with live reload (development mode).
Caching¶
| Content Type | Cache Duration | Rationale |
|---|---|---|
| HTML pages | 1 hour | Balance freshness with performance |
| CSS/JS assets | 1 year | Versioned filenames allow cache busting |
| Images | 1 week | Rarely change but not versioned |
Traefik adds caching headers via middleware for the docs subdomain.
Availability¶
The documentation site is non-critical infrastructure:
| Concern | Approach |
|---|---|
| Container failure | Docker restart policy (unless-stopped) |
| Monitoring | Health check via Traefik |
| Fallback | GitHub repository (always accessible) |
| High availability | Not required (static content, low traffic) |
Documentation updates can wait for container restart; no real-time requirements.
Related Documentation¶
- Architecture: Reverse Proxy - Traefik subdomain routing
- Project: PROJECT_TRACKER.md - Exposed as docs home page
- Reference: GLOSSARY.md - Terminology definitions
Document Maintainer: Architecture Team Review Cycle: Update when docs site features change