-
Notifications
You must be signed in to change notification settings - Fork 1
Architecture
Ömer Tarık Yılmaz edited this page Apr 5, 2026
·
1 revision
This page describes the system architecture of White-Ops, including component responsibilities, data flows, and technology choices.
- System Overview
- Component Details
- Data Flow: Task Execution
- Agent Communication Flow
- Technology Choices
+---------------------+
| Admin Panel |
| (React + Vite) |
| :3000 |
+----------+----------+
|
| REST + WebSocket
|
+------------------+ +---------v---------+ +------------------+
| | | | | |
| PostgreSQL <-------+ API Server +-------> Redis |
| :5432 | | (FastAPI) | | :6379 |
| | | :8000 | | |
+------------------+ +---------+---------+ +------------------+
|
+----------+----------+
| |
+-------v-------+ +-------v-------+
| Worker 01 | | Worker N |
| (Python) | | (Python) |
| | | |
| +---+ +---+ | | +---+ +---+ |
| |Agt| |Agt| | | |Agt| |Agt| |
| +---+ +---+ | | +---+ +---+ |
+-------+-------+ +-------+-------+
| |
+-------v---------------------v-------+
| Shared Services |
| |
| +----------+ +----------------+ |
| | MinIO | | Internal Mail | |
| | :9000 | | :8025 | |
| +----------+ +----------------+ |
+--------------------------------------+
Optional: Prometheus (:9090) + Grafana (:3001)
The central control plane. Built with FastAPI (Python 3.12+).
| Responsibility | Details |
|---|---|
| REST API | 16 endpoint modules covering agents, tasks, workflows, files, workers, admin, analytics, and more |
| WebSocket Hub | Real-time event broadcasting (task updates, agent status, worker heartbeats) |
| Authentication | JWT-based auth with bcrypt password hashing |
| Authorization | Role-based access control (admin, operator, viewer) |
| Database | PostgreSQL via SQLAlchemy + Alembic migrations |
| Task Queue | Coordinates task assignment to workers via Redis |
| File Storage | Proxies uploads/downloads to MinIO (S3-compatible) |
| Middleware | Rate limiting, request logging, security headers, error handling |
Key files:
-
server/app/main.py-- application entry point -
server/app/api/v1/-- all API route modules -
server/app/api/websocket.py-- WebSocket connection manager -
server/app/models/-- SQLAlchemy ORM models -
server/app/core/-- auth, security, middleware, permissions
The execution engine. Each worker is a standalone Python process that connects to the master server, receives tasks, and runs agents.
| Responsibility | Details |
|---|---|
| Registration | Announces itself to the server with hardware specs |
| Heartbeat | Sends CPU/RAM/disk metrics every 30 seconds |
| Task Polling | Polls the server for assigned tasks every 5 seconds |
| Agent Loop | Runs an iterative LLM agent loop (plan, tool call, observe, repeat) |
| Tool Execution | Hosts the 55-tool registry across 10 categories |
| LLM Integration | Unified interface via LiteLLM (Anthropic, OpenAI, Google, Ollama) |
| Sandboxing | Isolates code execution in restricted environments |
Key files:
-
worker/agent/main.py-- worker lifecycle (register, heartbeat, poll) -
worker/agent/executor.py-- task executor with LLM agent loop -
worker/agent/llm/provider.py-- multi-provider LLM interface -
worker/agent/tools/registry.py-- auto-discovery tool registry
A single-page application providing the operator interface. Built with React 18, TypeScript, Vite, and Tailwind CSS.
| Responsibility | Details |
|---|---|
| Dashboard | KPI cards, charts, system health overview |
| Agent Management | CRUD, start/stop, preset profiles |
| Task Management | Create, filter, monitor, inspect results |
| Workflow Builder | Visual DAG editor for multi-step workflows |
| Real-time Updates | WebSocket connection for live event feeds |
| 21 Pages | Full management across Main, Intelligence, Operations, and System sections |
Key files:
-
web/src/pages/-- 21 page components -
web/src/api/-- API client layer -
web/src/stores/-- state management -
web/src/components/-- reusable UI components
See Admin-Panel-Guide for a full tour of every page.
A lightweight SMTP server for agent-to-agent and agent-to-external email communication.
| Responsibility | Details |
|---|---|
| Internal Routing | Routes mail between agents at @whiteops.local
|
| External Relay | Optional SMTP relay for outbound email |
| Redis Integration | Uses Redis for message queuing |
| Domain | Configurable via MAIL_DOMAIN
|
| Store | Purpose | Port |
|---|---|---|
| PostgreSQL 16 | Persistent storage for agents, tasks, workflows, users, audit logs, settings | 5432 |
| Redis 7 | Cache, pub/sub message queue, task queue, session store | 6379 |
| MinIO | S3-compatible object storage for files, attachments, exports | 9000 (API), 9001 (console) |
| Component | Purpose | Port |
|---|---|---|
| Prometheus | Metrics collection and alerting | 9090 |
| Grafana | Dashboards and visualization | 3001 |
Enabled via make monitoring or docker compose --profile monitoring up -d.
1. User creates task via Admin Panel (or API)
|
v
2. Server stores task in PostgreSQL (status: pending)
Server publishes task.created event via WebSocket
|
v
3. Worker polls GET /api/v1/workers/{id}/tasks
Server assigns task to worker based on availability
|
v
4. Worker receives task, updates status to in_progress
(PATCH /api/v1/tasks/{id})
|
v
5. TaskExecutor builds system prompt + user prompt
Fetches available tool definitions from ToolRegistry
|
v
6. Agent Loop begins (max 20 iterations):
a. LLM receives prompt + conversation history + tool definitions
b. LLM responds with text and/or tool_calls
c. Worker executes each tool call via ToolRegistry
d. Tool results appended to conversation history
e. Loop continues until LLM signals completion or max iterations
|
v
7. Worker reports result to server
(PATCH /api/v1/tasks/{id} with status: completed/failed)
|
v
8. Server broadcasts task.completed/task.failed via WebSocket
Admin Panel updates in real time
Agents can communicate with each other through the internal messaging system:
Agent A (on Worker 1) Agent B (on Worker 2)
| |
| 1. Send message via |
| internal mail or |
| Messages API |
| |
+------> Server (messages table) ------->+
| + WebSocket broadcast |
| |
| 2. Agent B picks up |
| message during |
| task execution |
| |
+<------ Response via same channel <-----+
Messages are persisted in PostgreSQL and delivered via:
- The Messages API (
/api/v1/messages) - The internal mail server (
agent@whiteops.local) - WebSocket events for real-time notification
Collaboration sessions (multi-agent) are managed through the Collaboration module, where agents share a workspace and coordinate on complex tasks.
| Component | Technology | Why |
|---|---|---|
| API Framework | FastAPI | Async-native, automatic OpenAPI docs, high performance, type-safe |
| ORM | SQLAlchemy 2.0 + asyncpg | Async database access, mature migration tooling (Alembic) |
| LLM Integration | LiteLLM | Unified interface across Anthropic, OpenAI, Google, Ollama with zero code changes |
| Task Queue | Redis | Lightweight pub/sub, no additional broker dependency, doubles as cache |
| File Storage | MinIO | S3-compatible, self-hosted, no cloud vendor lock-in |
| Frontend | React + TypeScript + Vite | Type safety, fast HMR, large ecosystem |
| Styling | Tailwind CSS | Utility-first, consistent design, small bundle |
| Containerization | Docker Compose | Single-command deployment, reproducible environments |
| Monitoring | Prometheus + Grafana | Industry standard, rich alerting, pre-built dashboards |
| Auth | JWT + bcrypt | Stateless authentication, secure password hashing |
| Logging | structlog | Structured JSON logs, context-aware, production-ready |
| Password Hashing | passlib (bcrypt) | Battle-tested, resistant to timing attacks |
| Config | pydantic-settings | Type-safe config from environment variables |