# zhudotexe/redel architecture

> Architecture diagram of the GitHub repository zhudotexe/redel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zhudotexe/redel
- Repository: https://github.com/zhudotexe/redel

## Overview

##### Project type and purpose
- ReDel is a full-stack research toolkit: a Python backend library for recursive multi-agent LLM systems plus a bundled web visualization frontend. It exposes both a programmatic API and a web server (VizServer) for interactive sessions and replay of logged experiments.

##### Main components
a. Frontend (viz/)
- Vue.js SPA (TypeScript)
- Components: Chat, Tree, Load/Save, Notifications
- Communicates with the backend via REST/WebSocket (HTTP API & streaming)
- Bundled in viz/index.html, built with Vite
b. Backend server (redel/server/)
- VizServer: HTTP/WebSocket endpoints, session management
- SessionManager: tracks interactive sessions, state
- Indexer & Models: stores/queries logs, session metadata
- Server entrypoint: redel/server/server.py and __main__.py
c. Core library (redel/)
- ReDel class (app.py): orchestrates root vs. delegate engines
- Delegation modules: delegate_and_wait, delegate_one, base interfaces
- Event system: central events.py and EventLogger for granular logs
- Tools plugin system: redel/tools/* (browsing, email, travelplanner, etc.)
- Configuration & state: config.py, state.py, tool_config.py
- Utilities: embeddings.py, namer.py, utils.py
- Kani integration: base_kani.py—drives LLM calls (OpenAIEngine, function calling)
d. External services
- LLM API provider (OpenAI, via kani.engines.openai)
- Optional tool backends: web browsing, email SMTP, travel planner DB, WebArena process
e. Persistence
- File-based logs of all events (JSONL) in working directory or experiments/
- (No external database by default; can be extended in models.py)
f. CLI & Sandbox
- CLI entrypoints: server.py, terminal.py
- Sandbox scripts for ad-hoc experiments (sandbox/)

##### Architectural patterns & design principles
- Event-driven core: all components communicate through events; EventLogger captures every signal
- Modular plugin architecture: Tools and delegation strategies implement a common interface
- Clear separation:
- Presentation (Vue.js)
- Application server (VizServer + REST/WebSocket)
- Domain logic (ReDel orchestration, delegation, tools)
- Infrastructure (logging, persistence)

##### Relationships & data flow
1. User interacts via SPA or CLI → HTTP/WebSocket request to VizServer
2. VizServer → SessionManager loads/creates a ReDel instance
3. ReDel.query() → emits events → Delegation modules schedule sub-queries
4. Kani engine invokes LLM Calls → returns responses
5. EventLogger writes each event to disk; SessionManager broadcasts events to frontend in real time
6. Frontend renders new messages, tree updates, notifications
7. On “replay” mode: frontend loads stored log file, replays events locally

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User and Clients
    User["User"]:::external
    CLI["CLI (server.py, terminal.py)"]:::cli
    Sandbox["Sandbox Scripts"]:::sandbox

    %% Frontend Layer
    subgraph "Frontend (viz/)" 
        direction TB
        SPA["Vue.js SPA"]:::frontend
        EntryHTML["Entry Point (index.html)"]:::frontend
        ViteConfig["Vite Config (vite.config.ts)"]:::frontend
        MainTS["Main Script (main.ts)"]:::frontend

        subgraph "Components"
            Chat["Chat"]:::frontendComp
            Tree["Tree"]:::frontendComp
            LoadSave["Load/Save"]:::frontendComp
            Notifications["Notifications"]:::frontendComp
        end

        subgraph "API & State"
            APIClient["API Client"]:::frontendUtil
            Interactive["Interactive Client"]:::frontendUtil
            ModelsState["Models & State"]:::frontendUtil
            UtilsNotifs["Utils & Notifications"]:::frontendUtil
        end
    end

    %% Backend Server Layer
    subgraph "Backend Server (redel/server/)"
        direction TB
        VizServer["VizServer"]:::backend
        EntrypointServer["Server Entrypoint"]:::backend
        SessionMgr["SessionManager"]:::backend
        Indexer["Indexer"]:::backend
        ServerModels["Models & Metadata"]:::backend
    end

    %% Core Library Layer
    subgraph "Core Library (redel/)"
        direction TB
        ReDel["ReDel Orchestrator"]:::core
        subgraph "Delegation Strategies"
            direction TB
            DelegBase["Base Interface"]:::core
            DelegateWait["delegate_and_wait"]:::core
            DelegateOne["delegate_one"]:::core
        end
        subgraph "Tool Plugins"
            direction TB
            ToolsBase["Tools Base"]:::core
            Browsing["Web Browsing"]:::core
            EmailTool["Email"]:::core
            TravelPlanner["Travel Planner"]:::core
            WebArena["WebArena"]:::core
        end
        EventDefs["Event Definitions"]:::core
        EventLogger["EventLogger"]:::infra
        subgraph "Kani Integration"
            direction TB
            KaniBase["base_kani"]:::core
            KaniUtils["kani & engines"]:::core
        end
        Config["Config & State"]:::core
        Utils["Utilities"]:::core
    end

    %% Persistence
    Logs["JSONL Logs"]:::storage

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAI["OpenAI API"]:::external
        WebBrowseSvc["Web Browsing Service"]:::external
        EmailSvc["Email SMTP"]:::external
        TravelDB["Travel Planner DB"]:::external
        WebArenaSvc["WebArena Process"]:::external
    end

    %% Relationships
    User -->|"interacts"| SPA
    CLI -->|"CLI usage"| VizServer
    Sandbox -->|"runs scripts"| ReDel

    SPA -->|REST/WebSocket| VizServer
    VizServer -->|manages sessions| SessionMgr
    SessionMgr -->|loads/creates| ReDel
    ReDel -->|emits events| EventDefs
    ReDel -->|uses| DelegBase
    DelegateWait -->|implements| DelegBase
    DelegateOne -->|implements| DelegBase
    ReDel -->|uses| ToolsBase
    Browsing -->|implements| ToolsBase
    EmailTool -->|implements| ToolsBase
    TravelPlanner -->|implements| ToolsBase
    WebArena -->|implements| ToolsBase

    ReDel -->|calls| KaniBase
    KaniBase -->|calls| OpenAI
    KaniUtils -->|supports| KaniBase

    ReDel -->|logs events| EventLogger
    EventLogger -->|writes| Logs
    SessionMgr -->|broadcasts events| SPA
    EventLogger -.->|replay| SPA

    ToolsBase -->|connects| WebBrowseSvc
    ToolsBase -->|connects| EmailSvc
    ToolsBase -->|connects| TravelDB
    ToolsBase -->|connects| WebArenaSvc

    %% CLI & Sandbox to Core
    CLI -->|invokes| ReDel
    Sandbox -->|invokes| ReDel

    %% Click Events
    click SPA "https://github.com/zhudotexe/redel/tree/main/viz/"
    click EntryHTML "https://github.com/zhudotexe/redel/blob/main/viz/index.html"
    click ViteConfig "https://github.com/zhudotexe/redel/blob/main/viz/vite.config.ts"
    click MainTS "https://github.com/zhudotexe/redel/blob/main/viz/src/main.ts"
    click Chat "https://github.com/zhudotexe/redel/blob/main/viz/src/components/Chat.vue"
    click Tree "https://github.com/zhudotexe/redel/blob/main/viz/src/components/Tree.vue"
    click LoadSave "https://github.com/zhudotexe/redel/blob/main/viz/src/components/LoadSaveModal.vue"
    click Notifications "https://github.com/zhudotexe/redel/blob/main/viz/src/components/NotificationsOverlay.vue"
    click APIClient "https://github.com/zhudotexe/redel/blob/main/viz/src/redel/api.ts"
    click Interactive "https://github.com/zhudotexe/redel/blob/main/viz/src/redel/interactive.ts"
    click ModelsState "https://github.com/zhudotexe/redel/blob/main/viz/src/redel/models.ts"
    click ModelsState "https://github.com/zhudotexe/redel/blob/main/viz/src/redel/state.ts"
    click UtilsNotifs "https://github.com/zhudotexe/redel/blob/main/viz/src/redel/utils.ts"
    click UtilsNotifs "https://github.com/zhudotexe/redel/blob/main/viz/src/redel/notifications.ts"
    click VizServer "https://github.com/zhudotexe/redel/blob/main/redel/server/server.py"
    click EntrypointServer "https://github.com/zhudotexe/redel/blob/main/redel/server/__main__.py"
    click SessionMgr "https://github.com/zhudotexe/redel/blob/main/redel/server/session_manager.py"
    click Indexer "https://github.com/zhudotexe/redel/blob/main/redel/server/indexer.py"
    click ServerModels "https://github.com/zhudotexe/redel/blob/main/redel/server/models.py"
    click ReDel "https://github.com/zhudotexe/redel/blob/main/redel/app.py"
    click DelegBase "https://github.com/zhudotexe/redel/blob/main/redel/delegation/_base.py"
    click DelegateWait "https://github.com/zhudotexe/redel/blob/main/redel/delegation/delegate_and_wait.py"
    click DelegateOne "https://github.com/zhudotexe/redel/blob/main/redel/delegation/delegate_one.py"
    click EventDefs "https://github.com/zhudotexe/redel/blob/main/redel/events.py"
    click EventLogger "https://github.com/zhudotexe/redel/blob/main/redel/eventlogger.py"
    click KaniBase "https://github.com/zhudotexe/redel/blob/main/redel/base_kani.py"
    click KaniUtils "https://github.com/zhudotexe/redel/blob/main/redel/kanis.py"
    click Config "https://github.com/zhudotexe/redel/blob/main/redel/config.py"
    click Utils "https://github.com/zhudotexe/redel/blob/main/redel/utils.py"
    click ToolsBase "https://github.com/zhudotexe/redel/blob/main/redel/tools/_base.py"
    click Browsing "https://github.com/zhudotexe/redel/blob/main/redel/tools/browsing/impl.py"
    click Browsing "https://github.com/zhudotexe/redel/blob/main/redel/tools/browsing/webutils.py"
    click EmailTool "https://github.com/zhudotexe/redel/blob/main/redel/tools/email.py"
    click Logs "https://github.com/zhudotexe/redel/tree/main/experiments/"
    click CLI "https://github.com/zhudotexe/redel/blob/main/server.py"
    click CLI "https://github.com/zhudotexe/redel/blob/main/terminal.py"
    click Sandbox "https://github.com/zhudotexe/redel/tree/main/sandbox/"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#4C8BF5,color:#000;
    classDef frontendComp fill:#BDDFFF,stroke:#4C8BF5,color:#000;
    classDef frontendUtil fill:#B3D4FF,stroke:#4C8BF5,color:#000;
    classDef backend fill:#DFF5E1,stroke:#3FA34D,color:#000;
    classDef core fill:#FFF6D0,stroke:#E5C23C,color:#000;
    classDef infra fill:#FFF2CC,stroke:#E0B541,color:#000;
    classDef storage fill:#FFE0B2,stroke:#F4971A,color:#000;
    classDef external fill:#E2E2E2,stroke:#888,color:#000,stroke-dasharray: 5 5;
    classDef cli fill:#E8D7FF,stroke:#8F3ADB,color:#000;
    classDef sandbox fill:#F2D7FF,stroke:#9A42C2,color:#000;
```
