Homelab Integration Architecture

Homelab Integration Architecture

This document maps the full integration architecture of the homelab project, detailing how components like Codex, Clawdbot, Pulse, and Noosphere connect to form an autonomous development and communication ecosystem.

Overview

The homelab is structured into three primary layers:
1. Orchestration & Dispatch (Codex): Manages tasks, queues, and agent routing.
2. Communication & Gateway (Clawdbot): Bridges human interfaces (Discord, Telegram) with system actions.
3. Execution & Intelligence (Pulse, Claude Code, Noosphere): Performs the actual development work and maintains project context.

Integration Graph

graph TD
    subgraph "External"
        GH[GitHub]
        Discord[Discord]
        Telegram[Telegram]
        OrbitCloud[Orbit Cloud Run]
    end

    subgraph "Data Layer (Supabase)"
        DB_Tasks[(Task Queue)]
        DB_Orbit[(Project Intelligence)]
    end

    subgraph "Orchestration (Codex)"
        Codex[Codex Service]
        WebhookHandler[GitHub Webhook Handler]
        Dispatcher[Task Dispatcher]
    end

    subgraph "Communication (Clawdbot)"
        C_Gateway[Clawdbot Gateway]
        C_CLI[Clawdbot CLI]
        C_Skills[Specialized Skills]
        MessageLogger[Message Logger Hook]
    end

    subgraph "Execution Agents"
        Pulse[Pulse Autonomous Dev]
        ClaudeCode[Claude Code Max]
        Noosphere[Noosphere / Mycelium]
        DW[Dream Weaver / Garden]
    end

    %% Connections
    GH -->|Webhooks| WebhookHandler
    WebhookHandler --> DB_Tasks
    Codex -->|Polls| DB_Tasks
    Codex -->|Queries| DB_Orbit
    OrbitCloud -->|Populates| DB_Orbit

    Codex -->|Dispatch| Dispatcher
    Dispatcher -->|Spawn Session| C_CLI
    Dispatcher -->|Notify| C_CLI

    C_CLI -->|Bridges| Discord
    C_CLI -->|Bridges| Telegram
    Discord -->|Commands| C_Gateway

    C_Gateway -->|Spawns| Pulse
    C_Gateway -->|Interacts| DW

    ClaudeCode -->|Hook: Prompt Logger| Noosphere
    Noosphere -->|Syncs| DB_Orbit

    Pulse -->|Commits/PRs| GH

    C_Gateway -->|Logs| KimiDB[(Kimi Memory DB)]
    MessageLogger --> KimiDB

Key Components

### 1. Codex (Orchestrator)
- Role: Global task queue and agent dispatcher.
- Tech: Node.js, Express, Supabase.
- Integration:
- Receives GitHub webhooks (pushes, PRs).
- Manages a task queue in Supabase.
- Dispatches tasks to agents (`dual-max`, `pulse`, `clawdbot-session`) via the `Dispatcher`.
- Enriches prompts with project context from the Orbit intelligence layer.

### 2. Clawdbot (Gateway)
- Role: The central communication hub and command router.
- Tech: Node.js, CLI-first architecture.
- Integration:
- Bridges multiple chat platforms (Discord, Telegram, iMessage).
- Provides a CLI (`clawdbot message send`) used by other services for notifications.
- Manages "Skills" (specialized agents) and spawns autonomous sessions.
- Maintains a local message log and SQLite memory database (`kimi_memory.db`).

### 3. Pulse (Autonomous Development)
- Role: Autonomous agent focused on git-based development tasks.
- Tech: Node.js, MCP (Model Context Protocol).
- Integration:
- Exposed as an MCP server for Claude Desktop.
- Handles the full dev lifecycle: branching, coding, committing, and creating PRs.
- Triggered by Codex for automated task fulfillment.

### 4. Noosphere & Mycelium (Intelligence)
- Role: Pattern recognition and cross-conversation memory.
- Tech: Python, local JSON/SQLite storage.
- Integration:
- Hooks into Claude Code via `prompt-logger`.
- Detects recurring themes across all sessions (Mycelium sensing).
- Syncs activity and decisions with the Orbit layer.

### 5. Dream Weaver (Garden)
- Role: Idea incubation and conceptual "gardening".
- Tech: Python MCP server.
- Integration:
- Accessed via the `#garden` Discord channel in Clawdbot.
- Uses a `schema.sql` for local persistence of "dreams" and "blooms".

### 6. Orbit (Project Intelligence)
- Role: Centralized project metadata and activity tracking.
- Tech: Cloud Run (External), Supabase (Local Cache).
- Integration:
- Tracks tech stacks, project status, and activity.
- Used by Codex and Prompt Logger to maintain consistent context.

Single Points of Failure (SPOFs)

1. Clawdbot Gateway: If the Clawdbot gateway or its Discord connection fails, all human-agent interaction is severed, and Codex loses its ability to send notifications or spawn sessions.
2. Supabase Availability: Codex relies entirely on Supabase for its task queue and Orbit project data. If Supabase is offline, the orchestration layer stops functioning.
3. Local Host (Mac): Most components (Codex, Clawdbot, Pulse, Noosphere, Dream Weaver) run locally on the host machine (`darwin`). A system failure or loss of internet connectivity on this machine halts the entire ecosystem.
4. GitHub Connectivity: The "closed-loop" automation (Webhook -> Codex -> Pulse -> PR) depends on GitHub's API and webhook delivery.
5. Disk Capacity: The aggressive logging (JSONL messages, SQLite databases, Effect Trees, Transcript logs) could eventually lead to disk exhaustion if not rotated/compacted.

## Communication Patterns
- Async/Push: GitHub -> Codex (Webhooks), Codex -> Discord (via Clawdbot CLI).
- Polling: Codex -> Supabase (Task Queue).
- Synchronous/RPC: Claude Desktop -> MCP Servers (Pulse, Dream Weaver).
- Hooks: Claude Code -> Prompt Logger (Pre-prompt execution).