How to Read These Docs
These docs serve two audiences with different goals. Pick the path that matches what you need right now.
Two Paths
Section titled “Two Paths”“I want to understand how this works.” Start with Architecture Overview, then read through the Concepts section. These pages explain the design philosophy, architectural patterns, and key decisions. They answer “why” and “how” questions. Read them in order or jump to whatever interests you.
“I need to operate or modify the system.” Go directly to Systems for per-service documentation, or Operations for deployment and maintenance procedures. These pages assume you already understand the architecture and need specific instructions. They answer “what do I do” questions.
Content Types
Section titled “Content Types”Every page on this site falls into one of four categories:
| Type | Purpose | You will find… |
|---|---|---|
| Overview | Broad orientation for a topic or subsystem | Architecture diagrams, key concepts, “what and why” explanations |
| System | Per-service deep dive | Configuration, dependencies, ports, health checks, gotchas |
| Runbook | Step-by-step operational procedure | Numbered steps, copy-paste commands, verification checks |
| Decision | Rationale behind an architectural choice | Context, decision, consequences, tradeoffs |
Section Map
Section titled “Section Map”Start Here
Section titled “Start Here”Where you are now. Orientation material: what chris-os is, how the pieces fit together, and how to navigate these docs.
Concepts
Section titled “Concepts”The design philosophy behind chris-os. Why everything runs locally. How privacy tiers work. Why one PostgreSQL database instead of many. How AI agents interact with the infrastructure. Read these to build a mental model before diving into specifics.
Systems
Section titled “Systems”Per-service documentation for every major subsystem: database, n8n, MCP, Caddy, dashboard, monitoring, Home Assistant, voice pipeline. Each page covers what the service does, how it is configured, what depends on it, and what can go wrong.
Operations
Section titled “Operations”Procedures for running the system: deployment, database migrations, backup and restore, container management, monitoring, and incident response. These are the runbooks.
Decisions
Section titled “Decisions”Architecture Decision Records (ADRs) capturing the context and reasoning behind major choices. Why Pi 5 as the production host. Why four PostgreSQL roles. Why MCP proxy chains instead of direct access. These are the historical record of “why did we do it this way?”
Reading Tips
Section titled “Reading Tips”Bold terms mark key concepts on their first appearance. If you see a bolded term you do not recognize, the Concepts section probably has a page for it.
Code blocks contain real commands and real output. They are tested against the live system, not written from memory.
Callout boxes like the tip above highlight prerequisites, warnings, and shortcuts. Pay attention to caution and danger callouts; they flag things that can break the system.
Numbers are specific. When a page says “37 containers” or “210 tables,” those are verified counts, not estimates. If a number looks wrong, the system changed after the page was last updated (check the “last updated” date at the bottom of each page).