# genai-works-org/genai-agentos architecture

> Architecture diagram of the GitHub repository genai-works-org/genai-agentos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/genai-works-org/genai-agentos
- Repository: https://github.com/genai-works-org/genai-agentos

## Overview

##### Project type and purpose
- This is a full-stack, microservices-style monorepo that provisions a GenAI Agents Infrastructure.
- Key goals:
- Provide a React-based frontend UI for user/agent management, chat, flows, settings.
- Expose a FastAPI backend (REST + WebSocket) to handle authentication, agent registration, chats, flows, file storage.
- Use Celery + Redis for asynchronous LLM/agent calls and background jobs.
- Offer a dedicated Router microservice for WebSocket routing.
- Offer a Master-Agent microservice for advanced agent orchestration.
- Provide a CLI for scripting user/agent registration.
- Persist state in PostgreSQL and coordinate containerized deployment via Docker Compose.

##### File structure analysis
- Top-level dirs:
- backend/ → FastAPI app, Alembic migrations, Celery tasks, database models, HTTP & WS routes.
- frontend/ → React + Vite + TypeScript UI, REST & WebSocket clients, pages, components, services.
- cli/ → Python CLI tool for signup/login/register_agent, uses backend API.
- router/ → Python microservice set up as a standalone WebSocket gateway.
- master-agent/ → Python microservice implementing “master” orchestration logic, LLM connectors.
- genai_agents_example/ → sample agent implementations.
- tests/ → HTTP client tests for backend API and agent integration tests.
- Root contains docker-compose.yml (orchestrates containers), Makefile, .env-example, GitHub workflows.

##### README insights
- Confirms architecture: Backend, Router, Master-Agents, PostgreSQL, Frontend, CLI, Redis, Celery.
- Describes how to `make up` the full stack.
- Lists environment variables for inter-container hostnames/ports.
- Mentions supported provider types (OpenAI, MCP, A2A).

##### Components
a. User’s Browser (Frontend UI)
b. Backend API
– REST endpoints (HTTP 8000)
– WebSocket endpoint (over HTTP 8080 or via Router)
c. Router service
– WebSocket gateway at ws://…/ws
d. Celery system
– Redis broker
– Celery workers (tasks.py)
e. PostgreSQL database
f. Master-Agent microservice
g. CLI tool (external client)
h. External Agent Protocol endpoints
– GenAI Agents (genai-protocol)
– MCP servers
– A2A servers

##### Interactions & data flows
1. Browser ←→ REST API (user login, CRUD on agents, flows, files)
2. Browser ←→ Router (WebSocket) ←→ Backend WebSocket route (real-time chat, flow updates)
3. Backend → Celery (enqueue long-running tasks: LLM calls, file I/O, agent-to-agent)
4. Celery workers → External LLM/agent endpoints via HTTP/streamable-HTTP
5. Celery workers → write results back to Backend (DB or publish to WebSocket)
6. Master-Agent microservice ←→ Router or Backend (specialized orchestration calls, tracing)
7. CLI → REST API (signup, login, register_agent)

##### Architectural patterns & principles
- Microservices: Backend, Router, Master-Agent, CLI are separate deployables.
- Asynchronous/event-driven: Celery tasks + Redis broker handle heavy LLM calls.
- REST + WebSocket Hybrid: Synchronous resource ops vs. real-time streaming.
- Containerization: Each component runs in its own Docker container, networked via Docker Compose.
- Separation of concerns: UI vs. API vs. background processing vs. orchestration.

##### Detail checklist
- Environment variable links (e.g., ROUTER_WS_URL in frontend).
- Alembic migrations → PostgreSQL path for schema evolution.
- Celery broker (Redis) as central message bus.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation" 
        style Presentation fill:none,stroke:none
        Browser["User Browser\n(React UI)"]:::frontend
        CLI["CLI Tool"]:::frontend
    end

    %% API & Gateway Layer
    subgraph "API & Gateway"
        style API fill:none,stroke:none
        Backend["FastAPI Backend\n(HTTP 8000, WS)"]:::api
        Router["WebSocket Router\n(WS 8080)"]:::api
    end

    %% Worker Layer
    subgraph "Worker & Orchestration"
        style Worker fill:none,stroke:none
        Celery["Celery Worker"]:::worker
        Redis["Redis Broker"]:::worker
        MasterAgent["Master-Agent Service"]:::worker
    end

    %% Data Store Layer
    subgraph "Data Stores"
        style DataStore fill:none,stroke:none
        Postgres[(PostgreSQL DB)]:::datastore
    end

    %% External Services
    subgraph "External Services"
        style External fill:none,stroke:none
        GenAI["GenAI Agents Protocol"]:::external
        MCP["MCP Server"]:::external
        A2A["A2A Server"]:::external
    end

    %% Connections - synchronous
    Browser -->|"GET/POST /api (HTTP 8000)"| Backend
    CLI -->|"signup/login (HTTP 8000)"| Backend
    Browser -->|"ws://router/ws (WS 8080)"| Router
    Router -->|"Forward WS"| Backend
    Backend -->|"CRUD /agents,flows,files"| Postgres

    %% Connections - asynchronous
    Backend -->|".-> enqueue task (AMQP)"| Redis
    Redis -->|".-> fetch task"| Celery
    Celery -->|".-> write results"| Postgres
    Celery -->|".-> publish updates (WS)"| Router

    %% Worker calls external
    Celery -->|"HTTP/streaming"| GenAI
    Celery -->|"HTTP"| MCP
    Celery -->|"HTTP"| A2A

    %% Master-Agent interactions
    MasterAgent -->|"REST API"| Backend
    MasterAgent -->|"WS"| Router

    %% Docker Compose network
    Browser -.->|"Container: frontend"| Browser
    Backend -.->|"Container: backend"| Backend
    Router -.->|"Container: router"| Router
    Redis -.->|"Container: redis"| Redis
    Celery -.->|"Container: celery_worker"| Celery
    MasterAgent -.->|"Container: master_agent"| MasterAgent
    Postgres -.->|"Container: postgres_db"| Postgres

    %% Legend omitted for clarity

    %% Click events
    click Browser "https://github.com/genai-works-org/genai-agentos/blob/main/frontend/src/index.tsx"
    click CLI "https://github.com/genai-works-org/genai-agentos/blob/main/cli/cli.py"
    click Backend "https://github.com/genai-works-org/genai-agentos/blob/main/backend/main.py"
    click Celery "https://github.com/genai-works-org/genai-agentos/blob/main/backend/src/celery/celery_app.py"
    click Redis "https://github.com/genai-works-org/genai-agentos/blob/main/backend/src/celery/tasks.py"
    click Router "https://github.com/genai-works-org/genai-agentos/blob/main/router/main.py"
    click MasterAgent "https://github.com/genai-works-org/genai-agentos/blob/main/master-agent/main.py"
    click Postgres "https://github.com/genai-works-org/genai-agentos/blob/main/backend/scripts/init_pg_cron.sh"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#006064,color:#006064
    classDef api fill:#E8F5E9,stroke:#1B5E20,color:#1B5E20
    classDef worker fill:#FFF3E0,stroke:#E65100,color:#E65100
    classDef datastore fill:#F3E5F5,stroke:#4A148C,color:#4A148C
    classDef external fill:#ECEFF1,stroke:#37474F,color:#37474F
```
