flowchart TD
    subgraph Clients ["MCP Clients (Local / Remote)"]
        Ollama["Local LLMs (Ollama, Qwen, Llama)"]
        Claude["Claude Code / Desktop"]
        Codex["Codex / Antigravity"]
    end

    subgraph Transport ["Transport Layer"]
        Stdio["stdio (Python MCP SDK)"]
    end

    subgraph Core ["ellmos-homebase-mcp Core Engine"]
        Server["homebase.server"]
        Config["homebase.config"]
    end

    subgraph ToolGroups ["51 MCP Tools across 14 Functional Modules"]
        Mem["hb_mem_* (SQLite Memory)"]
        KB["hb_kb_* (Knowledge Digest)"]
        State["hb_state_* (State & Tasks)"]
        Route["hb_route_* (Model Router)"]
        Swarm["hb_swarm_* (Swarm Patterns)"]
        Api["hb_api_* (API Probing)"]
        Conn["hb_conn_* (Connectors Queue)"]
        Auto["hb_auto_* (Automation Chains)"]
        Plug["hb_plug_* (Plugin Discovery)"]
        Garden["hb_garden_* (Garden Store)"]
        Test["hb_test_* (Self Tests)"]
        Policy["hb_policy_* (Policy Registry, read-only)"]
        Ticket["hb_ticket_* (Ticket Master, read-only)"]
        Lock["hb_lock_* (Lock Master, read-only)"]
    end

    subgraph Storage ["Local Storage (Offline-First)"]
        DB[(SQLite Storage ~/.homebase/)]
    end

    Clients --> Stdio
    Stdio --> Server
    Server --> Config
    Server --> ToolGroups
    ToolGroups --> DB

sequenceDiagram
    autonumber
    participant Client as MCP Client (Local LLM / Claude / Codex)
    participant Stdio as Transport Layer (stdio)
    participant Server as Server & Registry (homebase)
    participant Module as Functional Module (hb_mem / hb_state / hb_route)
    participant Engine as Engine Seam (Bundled vs Canonical)
    participant DB as SQLite Storage (~/.homebase/)

    Client->>Stdio: JSON-RPC 2.0 Request (tools/call: hb_mem_store, agent_id="agent-01")
    Stdio->>Server: Decode & dispatch tool call
    Server->>Module: Validate arguments & inject agent provenance
    alt Bundled Engine Mode (Default)
        Module->>DB: Execute SQLite query (WAL mode, busy timeout)
        DB-->>Module: Return structured records / mutation status
    else Canonical Engine Mode ([engines].mode = "canonical")
        Module->>Engine: Seam check (Gardener / TASKPLAN / USMC)
        alt Engine Available
            Engine-->>Module: Delegate to canonical subsystem
        else Engine Unreachable
            Engine-->>Module: Raise CanonicalEngineUnavailable (Fail-Closed)
        end
    end
    Module-->>Server: Format response in requested language (i18n: en/de/es/zh/ja/ru)
    Server-->>Stdio: Encode JSON-RPC 2.0 Response
    Stdio-->>Client: Result payload (Zero cloud egress, 100% local)