# subsy/ralph-tui architecture

> Architecture diagram of the GitHub repository subsy/ralph-tui, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/subsy/ralph-tui
- Repository: https://github.com/subsy/ralph-tui

## Overview

##### Project Type & Purpose
- Ralph TUI is a monorepo containing two main “applications”:
a) A CLI-driven AI Agent Loop Orchestrator (terminal TUI) that selects tasks, builds prompts, executes agents, detects completion, persists state, and supports remote control.
b) A static documentation website (Next.js) for docs and marketing.

##### High-Level File Structure & Patterns
- Top-level directories:
- src/ – core of the CLI tool, subdivided by feature area (cli, commands, config, engine, plugins, remote, session, setup, prd, chat, tui, parallel, sandbox, logs, interruption, templates).
- website/ – Next.js app for docs.
- docs/, assets/ – static docs and theme/sound assets.
- skills/ – bundled AI-agent “skills” (Markdown-based).
- Patterns:
- Plugin architecture under src/plugins (agents & trackers).
- Event-driven engine loop under src/engine.
- Layer separation: CLI entry → command handlers → core engine → persistence & plugins → TUI/rendering or remote API.
- Remote control via WebSocket server/client under src/remote.

##### Key Architectural Components
a. CLI & Command Layer
- Entry point: src/index.ts / src/cli.tsx
- Command modules: src/commands/* parse flags, invoke core services (run, resume, status, setup, create-prd, remote, etc.).
b. Configuration Layer
- src/config: loads & validates user config (Zod schemas), merges defaults/global/project settings.
c. Core Engine Loop
- src/engine: implements the 5-step loop (select→build→execute→detect→next), emits events.
- Parallel execution: src/parallel (task graph, worker, conflict resolution).
- Interruption & signal handling: src/interruption.
d. Plugin Subsystems
- Agents: src/plugins/agents/* – adapters for Claude, Codex, Droid, Gemini, Kiro.
- Trackers: src/plugins/trackers/* – PRD, Beads, JSON trackers with Handlebars templates.
- Registry & dynamic loading.
e. Session & Logging
- Session persistence & locks: src/session.
- Logs & structured logger: src/logs.
f. TUI Layer
- src/tui – React/OpenTUI components render the dashboard, chat view, remote tabs, themes, keyboard handlers.
g. Remote Control
- WebSocket server (src/remote/server.ts) embedded in “run --listen”.
- WebSocket client (src/remote/client.ts) in the local TUI to control remote instances.
- Token management & audit logging.
h. Support Systems
- PRD creation & chat: src/chat, src/prd, src/templates (Handlebars).
- Sandbox wrapper: src/sandbox.
- Utilities: src/utils, testing harness, schema definitions.
i. Docs Website
- website/: Next.js app sourcing markdown .mdx under website/content and using website/lib utilities.

##### Interactions & Data Flow
- CLI entry → Command Handler → Config Loader → Core Engine
- Engine ↔ Plugins: for each iteration, engine calls Tracker (to fetch next task) and Agent (to execute prompt).
- Engine emits events → Session & Logs store progress.
- TUI subscribes to engine events (in‐process) to render real-time dashboard.
- “run --listen” → Engine also instantiates WebSocket server → Remote clients connect → send control commands & receive events.
- PRD generation path: CLI “create-prd” invokes chat + prd modules → outputs JSON/Beads.
- Parallel mode: engine delegates to parallel executor → fork workers (sandboxed) → merge results.
- Website is entirely decoupled: built from markdown, deployed separately.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers
    subgraph "CLI & Command Layer"
        direction TB
        CLI_Index["src/index.ts"]:::core
        CLI_CLI["src/cli.tsx"]:::core
        Commands["Command Modules<br/>(src/commands/)"]:::core
    end

    subgraph "Configuration Layer"
        direction TB
        Config["src/config/"]:::core
    end

    subgraph "Core Engine & Loop"
        direction TB
        Engine["Engine Loop<br/>(src/engine/)"]:::core
        Parallel["Parallel Executor<br/>(src/parallel/)"]:::support
        Interruption["Signal Handling<br/>(src/interruption/)"]:::support
    end

    subgraph "Plugin Layer"
        direction TB
        Agents["Agent Plugins<br/>(src/plugins/agents/)"]:::plugin
        Trackers["Tracker Plugins<br/>(src/plugins/trackers/)"]:::plugin
    end

    subgraph "Persistence"
        direction TB
        Session["Session Persistence<br/>(src/session/)"]:::persist
        Logs["Structured Logs<br/>(src/logs/)"]:::persist
    end

    subgraph "UI & Remote"
        direction TB
        TUI["TUI Layer<br/>(src/tui/)"]:::ui
        RemoteServer["WebSocket Server<br/>(src/remote/server.ts)"]:::ui
        RemoteClient["WebSocket Client<br/>(src/remote/client.ts)"]:::ui
    end

    subgraph "Support Systems"
        direction TB
        PRD["PRD Generator<br/>(src/prd/)"]:::support
        Chat["Chat Interface<br/>(src/chat/)"]:::support
        Templates["Templates<br/>(src/templates/)"]:::support
        Sandbox["Sandbox Wrapper<br/>(src/sandbox/)"]:::support
        Utils["Utilities<br/>(src/utils/)"]:::support
    end

    subgraph "External Dependencies"
        direction TB
        AIAPIs["AI APIs"]:::external
        GitFS["Git & Filesystem"]:::external
    end

    subgraph "Docs Site"
        direction TB
        Website["Next.js Site<br/>(website/)"]:::docs
    end

    %% Connections
    CLI_Index -->|starts| Commands
    CLI_CLI -->|parses flags| Commands
    Commands -->|load config| Config
    Config -->|provides settings| Engine

    Engine -->|calls| Agents
    Engine -->|calls| Trackers
    Agents -->|invoke APIs| AIAPIs
    Trackers -->|write data| GitFS

    Engine -->|emits events| Session
    Engine -->|emits events| Logs
    Session -->|store state| GitFS
    Logs -->|append logs| GitFS

    Engine -->|updates| TUI
    Engine -->|runs server| RemoteServer
    RemoteClient -->|controls| Engine
    RemoteServer -->|sends events| RemoteClient

    Commands -->|create-prd| PRD
    PRD -->|uses| Chat
    PRD -->|renders| Templates
    Engine -->|fork tasks| Parallel
    Parallel -->|spawn workers| Sandbox
    Sandbox -->|isolated tasks| Utils

    %% Style Definitions
    classDef core fill:#D6E9F8,stroke:#3178C6,color:#000
    classDef plugin fill:#E2F7E1,stroke:#28A745,color:#000
    classDef persist fill:#FFE4B5,stroke:#F0A500,color:#000
    classDef ui fill:#E8DBF5,stroke:#6F42C1,color:#000
    classDef support fill:#F5F5F5,stroke:#6C757D,color:#000
    classDef external fill:#F0F0F0,stroke-dasharray: 5 5,color:#666
    classDef docs fill:#FFF5E6,stroke:#FF9900,color:#000

    %% Click Events
    click CLI_Index "https://github.com/subsy/ralph-tui/blob/main/src/index.ts"
    click CLI_CLI "https://github.com/subsy/ralph-tui/blob/main/src/cli.tsx"
    click Commands "https://github.com/subsy/ralph-tui/tree/main/src/commands/"
    click Config "https://github.com/subsy/ralph-tui/tree/main/src/config/"
    click Engine "https://github.com/subsy/ralph-tui/tree/main/src/engine/"
    click Parallel "https://github.com/subsy/ralph-tui/tree/main/src/parallel/"
    click Interruption "https://github.com/subsy/ralph-tui/tree/main/src/interruption/"
    click Agents "https://github.com/subsy/ralph-tui/tree/main/src/plugins/agents/"
    click Trackers "https://github.com/subsy/ralph-tui/tree/main/src/plugins/trackers/"
    click Session "https://github.com/subsy/ralph-tui/tree/main/src/session/"
    click Logs "https://github.com/subsy/ralph-tui/tree/main/src/logs/"
    click TUI "https://github.com/subsy/ralph-tui/tree/main/src/tui/"
    click RemoteServer "https://github.com/subsy/ralph-tui/blob/main/src/remote/server.ts"
    click RemoteClient "https://github.com/subsy/ralph-tui/blob/main/src/remote/client.ts"
    click PRD "https://github.com/subsy/ralph-tui/tree/main/src/prd/"
    click Chat "https://github.com/subsy/ralph-tui/tree/main/src/chat/"
    click Templates "https://github.com/subsy/ralph-tui/tree/main/src/templates/"
    click Sandbox "https://github.com/subsy/ralph-tui/tree/main/src/sandbox/"
    click Utils "https://github.com/subsy/ralph-tui/tree/main/src/utils/"
    click Website "https://github.com/subsy/ralph-tui/tree/main/website/"
```
