Architecture

How Leif fits together — the major components and how they interact.

A high-level map of Leif and its surroundings. The system is intentionally simple: one server doing the work, one tunnel exposing it, one client (Claude) driving it.

Components

                    ┌──────────────────────────────────────┐
                    │           Claude.ai                  │
                    │   (Anthropic-hosted, web/desktop)    │
                    └──────────────┬───────────────────────┘
                                   │ MCP over HTTPS
                                   ▼
                    ┌──────────────────────────────────────┐
                    │      Cloudflare Tunnel               │
                    │   leif.super-ht.com / mcp.super-ht.com │
                    └──────────────┬───────────────────────┘
                                   │
                                   ▼
   ┌───────────────────────────────────────────────────────────────┐
   │  Leif host (10.10.0.25) — FastMCP server                      │
   │                                                               │
   │  ┌──────────────────────────────────────────────────────────┐ │
   │  │ Tool surface (273+ tools across 11+ namespaces)          │ │
   │  │                                                          │ │
   │  │  cwa_*    quickbooks_*    repairshopr_*    hudu_*        │ │
   │  │  growably_*  pricing_app_*  sheets_*  drive_*  gmail_*   │ │
   │  │  shtops_*  unifi_*  pve_*  github_*  social_*  ...       │ │
   │  └──────────────────────────────────────────────────────────┘ │
   │                                                               │
   │  ┌──────────────────────────────────────────────────────────┐ │
   │  │ Persistent state                                         │ │
   │  │   - Self-document (read_self)                            │ │
   │  │   - Project context, commitments, tasks, notes           │ │
   │  │   - Bootstrap context (per-scope living docs)            │ │
   │  └──────────────────────────────────────────────────────────┘ │
   └───┬───────────────────┬───────────────────┬────────────────┬──┘
       │                   │                   │                │
       ▼                   ▼                   ▼                ▼
  ┌─────────┐        ┌──────────┐        ┌──────────┐     ┌──────────┐
  │nvrbackup│        │  SHTops  │        │ External │     │ Customer │
  │ pricing │        │   ops    │        │   APIs   │     │  sites   │
  │  app    │        │          │        │          │     │ (SSH/VPN)│
  └─────────┘        └──────────┘        └──────────┘     └──────────┘

How a request flows

A typical Claude → Leif → real-world action looks like:

  1. Wayne asks Claude to do something (in chat or via Claude Code)
  2. Claude picks the right Leif tool from the catalog and calls it via MCP
  3. The MCP request flows through Cloudflare Tunnel to the FastMCP server on 10.10.0.25
  4. The tool runs against whichever backend it targets — local shell, remote SSH, an external API (RepairShopr, QuickBooks, Hudu, Growably, etc.), or Google Workspace
  5. The tool returns structured data; Claude synthesizes a response

Most of the value comes from this last step: rather than Claude having to guess or scrape, it gets clean JSON from the system of record.

Why this shape

The architecture is deliberately one brain, one body:

  • Claude is the brain. Conversation, planning, synthesis, judgment.
  • Leif is the body. Tool execution, persistent state, side effects.

Anything stateful (RS data, QB data, customer files, scheduled jobs) lives on the Leif side. Anything reasoning-heavy (deciding what to do, how to phrase something, whether to ask first) stays in Claude.

The Leif web ops console (/review/* URLs at leif.super-ht.com) was an earlier-generation surface for human review/approval. It still runs but is effectively unused now — most workflows happen through Claude conversations directly. Flagged for possible deprecation in a future cleanup pass.