# reagent-systems/simple-agent-websocket architecture

> Architecture diagram of the GitHub repository reagent-systems/simple-agent-websocket, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/reagent-systems/simple-agent-websocket
- Repository: https://github.com/reagent-systems/simple-agent-websocket

## Overview

##### Project Type and Purpose
- This is an open-source, modular “thin” wrapper around the SimpleAgent Core, exposing its functionality over WebSockets and HTTP.
- It is not a full-stack application (no persistent database), but a server-side component plus a test client UI for real-time AI agent sessions.
- Purpose: DRY-compliant real-time interface, leveraging SimpleAgent Core via a Git submodule.

##### File Structure Analysis
- Top level:
- main.py (entry point)
- websocket_server.py (legacy wrapper)
- requirements.txt, Dockerfile, setup scripts
- SimpleAgent-Core (Git submodule)
- test_client_enhanced.html (client UI)
- websocket_server/ package:
- server.py (initializes Flask‐SocketIO server)
- routes.py (HTTP API endpoints)
- event_handlers.py (maps socket events → handlers)
- run_manager.py (enhances core RunManager with WebSockets)
- agent_wrapper.py (session & state management)
- core_loader.py (loads core library via submodule)

##### README Insights
- Confirms architecture: modular server package + submodule.
- Lists events, endpoints, tech stack (Flask-SocketIO, Python, git submodule).
- Emphasizes DRY, modularity, real-time updates, multi-session, no code duplication.

a. Main Components
1. Client Side:
- test_client_enhanced.html (Browser UI)
- (Any other socket.io clients)
2. WebSocket/HTTP Server:
- main.py → initializes server (Flask + SocketIO)
- websocket_server/server.py
- websocket_server/routes.py (HTTP endpoints: /health, /sessions, /version)
- websocket_server/event_handlers.py (socket event layer)
3. Session & Business Logic:
- websocket_server/agent_wrapper.py (session context, user inputs)
- websocket_server/run_manager.py (orchestrates step execution + emits events)
4. Core Library:
- SimpleAgent-Core (submodule) loaded via websocket_server/core_loader.py
5. External Services:
- AI provider API (OpenAI, LMStudio, Gemini) accessed by the core
6. Deployment/Infra:
- Docker container (Dockerfile, .dockerignore)
- Environment variables (.env in submodule)

b. Relationships & Data Flows
- Client → WebSocket (`/socket.io/`): run_agent, user_input, stop_agent → event_handlers
- event_handlers → run_manager / agent_wrapper → core_loader → SimpleAgent Core
- Core → run_manager emits assistant_message, step_start, tool_call back → event_handlers → Client
- HTTP calls (e.g., GET /health) → routes.py → server status
- main.py wires server, loads configuration, binds host/port

c. Architectural Patterns & Principles
- Layered architecture: Presentation (UI), Transport (WebSocket/HTTP), Application (event handlers & run manager), Core (agent engine)
- Modular package: single-responsibility modules, easy to extend
- DRY via git submodule: no code duplication of core
- Pub/Sub style event propagation: Flask-SocketIO events

d. Key Technologies
- Python 3.x
- Flask + Flask-SocketIO
- git submodule for SimpleAgent Core
- Socket.IO protocol (WebSocket fallback)
- HTML/JavaScript client
- Docker

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client"
        direction TB
        UI["test_client_enhanced.html"]:::client
    end

    %% Entry Point
    Main["main.py"]:::bootstrap

    %% Server Layer
    subgraph "WebSocket Server"
        direction TB
        ServerInit["server.py"]:::server
        Routes["routes.py"]:::server
        EventHandlers["event_handlers.py"]:::server
        AgentWrapper["agent_wrapper.py"]:::logic
        RunManager["run_manager.py"]:::logic
        CoreLoader["core_loader.py"]:::coreloader
    end

    %% Core Library
    Core["SimpleAgent-Core"]:::core

    %% External Services
    AIAPI["AI Provider API"]:::external

    %% Deployment / Infra
    subgraph "Deployment"
        direction TB
        Requirements["requirements.txt"]:::infra
        Docker["Dockerfile/.dockerignore"]:::infra
        SubmoduleSetup["setup_submodule.sh/.bat"]:::infra
    end

    %% Data Flows
    UI -->|"WebSocket run_agent/user_input/stop_agent"| EventHandlers
    EventHandlers -->|"wraps calls"| AgentWrapper
    AgentWrapper -->|"orchestrates"| RunManager
    RunManager -->|"loads via"| CoreLoader
    CoreLoader -->|"integrates submodule"| Core
    Core -->|"calls"| AIAPI
    RunManager -->|"emits events"| EventHandlers
    EventHandlers -->|"socket.io emit"| UI

    UI -->|"HTTP GET /health /sessions /version"| Routes
    Routes -->|"exec status"| UI

    Main -->|"initializes Flask+SocketIO"| ServerInit
    Main --> ServerInit

    Main --> Requirements
    Main --> Docker
    Main --> SubmoduleSetup

    %% Click Events
    click UI "https://github.com/reagent-systems/simple-agent-websocket/blob/main/test_client_enhanced.html"
    click Main "https://github.com/reagent-systems/simple-agent-websocket/blob/main/main.py"
    click ServerInit "https://github.com/reagent-systems/simple-agent-websocket/blob/main/websocket_server/server.py"
    click Routes "https://github.com/reagent-systems/simple-agent-websocket/blob/main/websocket_server/routes.py"
    click EventHandlers "https://github.com/reagent-systems/simple-agent-websocket/blob/main/websocket_server/event_handlers.py"
    click AgentWrapper "https://github.com/reagent-systems/simple-agent-websocket/blob/main/websocket_server/agent_wrapper.py"
    click RunManager "https://github.com/reagent-systems/simple-agent-websocket/blob/main/websocket_server/run_manager.py"
    click CoreLoader "https://github.com/reagent-systems/simple-agent-websocket/blob/main/websocket_server/core_loader.py"
    click Core "https://github.com/reagent-systems/simple-agent-websocket/tree/main/SimpleAgent-Core/"
    click Requirements "https://github.com/reagent-systems/simple-agent-websocket/blob/main/requirements.txt"
    click Docker "https://github.com/reagent-systems/simple-agent-websocket/tree/main/Dockerfile"
    click SubmoduleSetup "https://github.com/reagent-systems/simple-agent-websocket/blob/main/setup_submodule.sh"

    %% Styles
    classDef client fill:#e0f7e9,stroke:#2d8f5a,color:#2d8f5a;
    classDef bootstrap fill:#fff2cc,stroke:#d6a700,color:#d6a700;
    classDef server fill:#d0e7ff,stroke:#1a75ff,color:#1a75ff;
    classDef logic fill:#ffe0b2,stroke:#ff9800,color:#bf5700;
    classDef coreloader fill:#f3e5f5,stroke:#9c27b0,color:#6a0080;
    classDef core fill:#ffecb3,stroke:#ffb300,color:#b27f00;
    classDef external fill:#f3f3f3,stroke:#888888,color:#555555;
    classDef infra fill:#ececec,stroke:#aaaaaa,color:#666666;
```
