Architecture Overview

godotz.ai is organized into seven discrete layers. Each layer has a single responsibility, a stable API surface to the layer above, and no knowledge of layers above it. This separation lets any layer be replaced independently without cascading refactors.

The L0–L6 Stack

┌─────────────────────────────────────────────────────────┐
│  L6  Economy          x402 payment protocol             │
├─────────────────────────────────────────────────────────┤
│  L5  Fleet Mesh       Tailscale WireGuard mesh          │
├─────────────────────────────────────────────────────────┤
│  L4  Observability    Langfuse traces + cost ledger     │
├─────────────────────────────────────────────────────────┤
│  L3  Memory           Mnemopi + Knowledge Gardener      │
├─────────────────────────────────────────────────────────┤
│  L2  Task Graph       beads CLI (bd) + Dolt backend     │
├─────────────────────────────────────────────────────────┤
│  L1  Model Gateway    LiteLLM proxy + Redis cache       │
├─────────────────────────────────────────────────────────┤
│  L0  Agent Runtime    Claude Code + OMC harness         │
└─────────────────────────────────────────────────────────┘

Data flows upward: the runtime calls the gateway, which logs through observability, which is accessible across the mesh.

L0 — Agent Runtime

Components: Claude Code, OMC (oh-my-claudecode), skills registry
Role: The execution substrate. Agents live here. OMC injects hooks, routes skills, and enforces session contracts.

The runtime exposes a uniform tool interface regardless of which underlying model is active. Agents never call provider APIs directly — all requests pass through L1.

Agent → OMC hook → tool call → L1 gateway
              ↑
         skill/rule injection

Key properties:

• 60+ bundled skills auto-discovered on startup
• Fail-closed: unresolvable tool calls return an error, never a silent no-op
• Session contracts enforce budget ceilings before the first token

L1 — Model Gateway

Components: LiteLLM proxy, Redis, Postgres
Role: Single OpenAI-compatible API surface for all model providers.

All L0 model calls hit http://gateway:4000. LiteLLM routes them to the correct provider, enforces virtual-key budgets, and checks the Redis cache before touching the network.

L0 call → LiteLLM proxy → [cache hit?] → return cached
                        ↘ [cache miss] → provider API → store → return

See Model Gateway for the full 8-model config.

L2 — Task Graph

Components: beads CLI (bd), Dolt versioned backend
Role: Persistent DAG task scheduler with hooks and human checkpoints.

bd decomposes epics into tasks and tasks into steps. Dependencies are explicit edges in the DAG; the scheduler never starts a node until all its predecessors have completed or been skipped.

epic: ship-feature
  ├── task: implement   [deps: none]
  ├── task: test        [deps: implement]
  └── task: deploy      [deps: test]

Dolt provides a git-like version history for the task graph — every state change is a diff-able commit.

L3 — Memory

Components: Mnemopi (session + long-term), Knowledge Gardener v0.21.0 (vault)
Role: Three-tier durable memory across agent sessions.

┌─────────────────┐   ┌─────────────────┐
│    Working       │   │   Episodic       │
│  (session TTL)   │   │ (7-day default)  │
└────────┬────────┘   └────────┬────────┘
         └──────────┬──────────┘
              ┌─────▼──────┐
              │  Semantic   │
              │ (permanent) │
              │  KG + vault │
              └────────────┘

See Memory for vault structure and YAML frontmatter requirements.

L4 — Observability

Components: Langfuse (self-hosted), structured trace logs
Role: Every token, tool call, cost, and latency recorded with full provenance.

Langfuse runs in the Docker control plane alongside Postgres and Redis. It receives traces via the LiteLLM callback integration — no agent-side instrumentation required.

L5 — Fleet Mesh

Components: Tailscale, WireGuard, MagicDNS
Role: Zero-trust encrypted mesh connecting all fleet nodes.

Every node receives a stable 100.x.x.x address and a node.tail.omp DNS name on join. ACL policies control which nodes can reach which services — the gateway is not exposed to the public internet.

node-a (100.64.0.1)  ←──WireGuard──→  node-b (100.64.0.2)
        ↑                                       ↑
   gateway:4000                         worker processes

See Fleet Topology for multi-node deployment patterns.

L6 — Economy

Components: x402 payment protocol, virtual key ledger
Role: Per-call economic metering for agent work, enabling paid access to fleet capabilities.

x402 is an HTTP 402-based micropayment protocol. An agent requesting a paid capability receives a 402 Payment Required response with a X-Payment-Request header; it attaches a signed payment proof and retries.

agent → capability request
      ← 402 + payment terms
agent → request + X-Payment-Proof header
      ← 200 + result

This layer is optional for internal fleets but required for public-facing agent APIs.

Layer Interface Contract

Each layer consumes the layer below through a versioned interface and never skips layers:

The interfaces are stable across minor versions. Breaking changes follow a two-release deprecation window.

Related

• Model Gateway — LiteLLM config and 8-model routing
• Task Graph — beads DAG scheduler
• Memory — Mnemopi and Knowledge Gardener
• Orchestration — Swarm YAML and agent isolation
• Self-Evolution — pheromone trails and cascade optimization