System Architecture

Understand how all the components of Fluxgate AI fit together.

High-Level Overview

Fluxgate AI (ACP) is a microservices platform with five main layers:

Dashboard (Next.js)

The web UI for managing agents, viewing analytics, configuring policies, and monitoring the system. Runs on port 3000.

API Server (FastAPI)

The core REST API that handles all business logic, CRUD operations, and orchestration. Runs on port 8000.

Gateway (Go)

High-performance request router that handles rate limiting, authentication, and load balancing. Runs on port 8080.

Workers (Celery)

Background task processors that handle agent execution, budget checks, and scheduled jobs. Three worker types: runtime, budget, scheduler.

Data Layer

TimescaleDB (PostgreSQL + pgvector) for persistent storage, Redis for caching and sessions, Kafka for event streaming.

AI Providers

Integrations with OpenAI, Anthropic, Google, and other LLM providers via a unified adapter layer.

Architecture Diagram

System Architecturetext


+--------------------------------------------------+
|                   CLIENTS                         |
|  Browser (Dashboard)  |  API Clients  |  Widgets  |
+----------+-----------+---------+------+-----------+
           |                     |
           v                     v
+----------+-----------+ +-------+--------+
|   Next.js Dashboard  | |   Go Gateway   |
|     (Port 3000)      | |  (Port 8080)   |
|  - React UI          | |  - Rate Limit  |
|  - Server Components | |  - Auth Check  |
|  - Tailwind CSS      | |  - Load Balance|
+----------+-----------+ +-------+--------+
           |                     |
           +----------+----------+
                      |
                      v
         +------------+-------------+
         |     FastAPI Server       |
         |      (Port 8000)         |
         |                          |
         |  +--------------------+  |
         |  |   28 API Routers   |  |
         |  | agents, tools,     |  |
         |  | memory, lifecycle, |  |
         |  | budgets, events,   |  |
         |  | governance, etc.   |  |
         |  +--------------------+  |
         |                          |
         |  +--------------------+  |
         |  |  Service Layer     |  |
         |  |  Business Logic    |  |
         |  +--------------------+  |
         +-----+------+------+-----+
               |      |      |
      +--------+  +---+---+  +--------+
      |           |       |           |
      v           v       v           v
+-----+---+ +----+--+ +--+----+ +----+-------+
|TimescaleDB| |Redis  | |Kafka  | |AI Providers|
|PostgreSQL | |Cache  | |Events | |OpenAI      |
|+ pgvector | |Session| |Stream | |Anthropic   |
|Port 5432  | |Port   | |Port   | |Google      |
|           | |6379   | |9092   | |etc.        |
+-----------+ +-------+ +-------+ +------------+
      ^           ^       ^
      |           |       |
+-----+-----------+-------+--------+
|          Celery Workers           |
|                                   |
|  runtime-worker  - Agent runs     |
|  budget-worker   - Cost tracking  |
|  scheduler-worker- Cron/triggers  |
+-----------------------------------+

Request Flow

Here is how a typical agent run flows through the system:

Client sends request — Dashboard or API client sends a POST to /api/v1/agents/:id/run
Gateway validates — Go gateway checks the API key, applies rate limits, and forwards to the API server
API creates run — FastAPI creates a run record in TimescaleDB and dispatches a Celery task
Budget check — Budget worker verifies spending limits before execution proceeds
Runtime executes — Runtime worker loads the agent config, system prompt, tools, and knowledge base
LLM call — Worker calls the configured AI provider (OpenAI, Anthropic, etc.) with the assembled prompt
Tool execution — If the LLM requests tool use, the worker executes tools and loops back
Memory storage — Conversation and results are stored in memory (pgvector for semantic search)
Events emitted — Run events are published to Kafka for analytics, webhooks, and real-time updates
Response returned — Final response is sent back to the client via the API

Core Data Model

Core Tablestext

+------------------+     +------------------+     +------------------+
|     agents       |     |    agent_runs    |     |    run_steps     |
+------------------+     +------------------+     +------------------+
| id               |<-+  | id               |<-+  | id               |
| name             |  |  | agent_id     (FK)|  |  | run_id       (FK)|
| description      |  |  | input            |  |  | step_type        |
| model            |  |  | output           |  |  | input            |
| system_prompt    |  +--| status           |  +--| output           |
| tools[]          |     | tokens_used      |     | tokens_used      |
| tags[]           |     | cost_usd         |     | duration_ms      |
| status           |     | started_at       |     | created_at       |
| created_at       |     | completed_at     |     +------------------+
+------------------+     +------------------+

+------------------+     +------------------+     +------------------+
|    tools         |     | budget_configs   |     | memory_entries   |
+------------------+     +------------------+     +------------------+
| id               |     | id               |     | id               |
| name             |     | agent_id     (FK)|     | agent_id     (FK)|
| description      |     | period           |     | memory_type      |
| type             |     | limit_usd        |     | content          |
| safety_level     |     | action_on_exceed |     | embedding[]      |
| input_schema     |     | current_usage    |     | metadata         |
| config           |     | created_at       |     | created_at       |
+------------------+     +------------------+     +------------------+

Service Ports Reference

Service	Technology	Port	Purpose
Dashboard	Next.js 14	3000	Web UI
API Server	FastAPI (Python)	8000	REST API, business logic
Gateway	Go (Chi router)	8080	Rate limiting, auth, routing
TimescaleDB	PostgreSQL 16 + pgvector	5432	Primary database
Redis	Redis 7	6379	Cache, sessions, Celery broker
Kafka	Apache Kafka	9092	Event streaming
Zookeeper	Apache Zookeeper	2181	Kafka coordination

Technology Stack

Frontend

Next.js 14 (App Router)
React 18
TypeScript
Tailwind CSS
Lucide React icons
Monaco Editor

Backend

FastAPI (Python 3.11)
Go 1.21 (Gateway)
Celery (Task workers)
asyncpg (DB driver)
aiohttp (HTTP client)
Pydantic v2 (Validation)

Infrastructure

Docker & Docker Compose
Kubernetes (optional)
TimescaleDB + pgvector
Redis 7
Apache Kafka
KEDA (autoscaling)

Extensibility

ACP is designed to be extensible. Add new AI providers by implementing the provider adapter interface, create custom tools with REST API or function types, and extend the event bus with custom event types and subscriptions.

Cost Control

Troubleshooting