Domain

Per-subsystem specs, split out of spec_v3.md. Each page here is the working reference for that subsystem; the canonical spec is always the ultimate source of truth.

Architecture at a Glance

flowchart TB
    subgraph Input["Input Channels"]
        Discord["Discord Bot"]
        SMS["Twilio SMS"]
        Chat["Quick Chat"]
    end

    subgraph Core["Core Engine"]
        Orch["Orchestrator"]
        Router["Model Router"]
        Skills["Skill Executor"]
        Agents["Agent Dispatcher"]
    end

    subgraph Data["Data & State"]
        DB[("SQLite\n(tasks, skills, runs)")]
        Vault["Memory Vault\n(git-backed)"]
        Config["YAML Config\n(models, skills, tasks)"]
    end

    subgraph Services["Services"]
        Sched["Scheduler"]
        Auto["Automations"]
        Notif["Notifications"]
        Cost["Cost Guard"]
    end

    subgraph External["External"]
        Claude["Claude API"]
        Ollama["Ollama\n(local LLM)"]
        GCal["Google Calendar"]
        Gmail["Gmail API"]
    end

    subgraph Observe["Observability"]
        Logs["Loki + Grafana"]
        Inspector["Claude Inspector"]
        Payloads["Payload Writer"]
    end

    Discord & SMS & Chat --> Orch
    Orch --> Router
    Router --> Claude & Ollama
    Orch --> Skills & Agents
    Skills --> Router
    Agents --> Router
    Orch --> DB
    Skills --> DB
    Orch --> Vault
    Sched --> Orch
    Auto --> Skills
    Orch --> Notif
    Cost --> Router
    Sched --> GCal
    Router --> Logs
    Router --> Payloads
    Payloads --> Inspector

    classDef input fill:#e1f5fe,stroke:#0288d1
    classDef core fill:#fff3e0,stroke:#f57c00
    classDef data fill:#e8f5e9,stroke:#388e3c
    classDef service fill:#f3e5f5,stroke:#7b1fa2
    classDef external fill:#fce4ec,stroke:#c62828
    classDef observe fill:#fffde7,stroke:#f9a825

    class Discord,SMS,Chat input
    class Orch,Router,Skills,Agents core
    class DB,Vault,Config data
    class Sched,Auto,Notif,Cost service
    class Claude,Ollama,GCal,Gmail external
    class Logs,Inspector,Payloads observe

Start Here

New to the codebase? Read these in order for a complete mental model:

1. Architecture Overview — Docker topology, component map, storage layout. Start here for the physical picture.
2. Data Flow — How a Discord message becomes a persisted, scheduled, routed task. The happy path end-to-end.
3. Task System — Task lifecycle, state machine, deduplication. The central data model everything else revolves around.
4. Model Layer — How LLM calls are routed, structured, and logged. Every AI interaction flows through here.
5. Skill System — YAML-defined skills, execution pipeline, lifecycle, evolution. The capability layer on top of the model layer.
6. Scheduling — Time windows, conflict resolution, calendar sync. How tasks get placed on the calendar.
7. Cost — Budget enforcement, escalation gates, manual fallbacks. Critical for understanding Donna's safety posture.

After these seven, branch into whichever subsystem is relevant to your work.

Subsystems

Subsystem	Spec section
Task System	spec_v3.md §5
Orchestrator	Central dispatch and intent routing
Model Layer	spec_v3.md §4
LLM Gateway	Priority queue, rate limiting, GPU tracking
Skill System	YAML-defined skills, execution pipeline, lifecycle, evolution
Agents	Agent hierarchy, safety, tool progression
Chat	Conversational engine, action handlers, sessions
Replies	Universal reply classification and routing
Scheduling	spec_v3.md §6
Integrations	spec_v3.md §3.2 (hybrid MCP/API)
Memory Vault	Git-backed knowledge store with embeddings
Notifications	Channels, escalation, conversation context
Preferences	Correction logging, rule extraction
Cost	Budget enforcement, escalation gate, tool gap surfacing
Collection	LLM payload capture for forensics
Insights	SQL-based analytics for Claude Inspector
Observability	Logging, dashboards, alerting
Resilience	spec_v3.md §3.6 retries, circuit breaker, backup
API & Auth	REST API, authentication, authorization
Setup	Interactive bootstrapping wizard
Management GUI	Admin and inspection surfaces