Skip to content

Architecture

AgentBI is a business-analytics platform for AI agents. It ingests operational and commercial events, aggregates ROI metrics, and presents CEO/CFO dashboards. This document describes the major components and data flows.

System Components

flowchart LR
    subgraph Presentation
        FE[Executive UI<br/>nginx :3000]
        DOCS[MkDocs<br/>optional]
    end

    subgraph Edge
        TR[Traefik<br/>:8088]
    end

    subgraph API["FastAPI Application :8000"]
        GW[API Gateway<br/>/api/v1]
        ING[Ingest / Webhook<br/>/ingest]
        AUTH[Auth<br/>JWT + API keys]
    end

    subgraph Services
        AGG[Event Aggregator]
        MC[Metric Calculator]
        ROI[ROI Engine]
        AD[Anomaly Detector]
        RG[Report Generator]
        EX[Export Service<br/>PDF / Excel]
        IS[Ingest Service]
    end

    subgraph Storage
        PG[(PostgreSQL 15)]
        TS[(TimescaleDB<br/>optional)]
        RD[(Redis 7)]
    end

    subgraph External
        SDK[Agent SDK]
        AEG[AegisAI]
        OPS[AgentOps]
    end

    FE --> TR
    TR --> GW
    DOCS -.-> FE

    SDK --> ING
    AEG --> ING
    OPS --> ING
    ING --> IS
    GW --> AUTH
    GW --> AGG & MC & ROI & AD & RG & EX
    IS --> PG
    AGG & MC & ROI & AD & RG --> PG
    MC --> RD
    GW --> RD
    PG --- TS

Component Reference

Component Location Responsibility
API Gateway app/main.py, app/api/v1/ REST API, routing, CORS, auth dependencies
Ingest / Webhook app/api/v1/ingest.py Accept agent events, batch ingest, upstream webhooks
Ingest Service app/services/ingest_service.py Persist events, auto-register unknown agents
Event Aggregator app/services/data_aggregator.py Group events by agent / period, time series buckets
Metric Calculator app/services/metric_calculator.py Portfolio and per-agent metrics, cache snapshots
ROI Engine app/services/roi_engine.py ROI with labor savings, compare, portfolio
Anomaly Detector app/services/anomaly_detector.py Efficiency drop, cost spike, ROI decline signals
Report Generator app/services/report_generator.py Executive / agent reports and summaries
Export Service app/services/export_service.py PDF and Excel exports
Auth app/core/security.py, app/api/v1/auth.py JWT login, API keys, RBAC roles
Frontend frontend/ Executive, Agents, ROI, Compare, Reports
Traefik docker-compose.yml Reverse proxy edge

Data Flow

Business event → metrics

sequenceDiagram
    participant Agent
    participant API as FastAPI
    participant IS as Ingest Service
    participant PG as PostgreSQL
    participant MC as Metric Calculator
    participant RD as Redis
    participant UI as Executive UI

    Agent->>API: POST /api/v1/ingest/events
    API->>IS: process_event()
    IS->>PG: INSERT agent_events
    IS-->>API: accepted
    API-->>Agent: 200

    UI->>API: GET /api/v1/dashboard/executive
    API->>RD: cache lookup
    alt Cache miss
        API->>MC: get_aggregated(period)
        MC->>PG: SUM cost / value / time_saved
        MC->>RD: cache set (TTL ~30s)
    end
    API-->>UI: KPIs + charts payload

ROI calculation

sequenceDiagram
    participant User
    participant API as FastAPI
    participant ROI as ROI Engine
    participant PG as PostgreSQL

    User->>API: GET /api/v1/roi/agent/{id}?period=month
    API->>ROI: calculate(agent_id, period)
    ROI->>PG: aggregate events + agent labor rate
    ROI->>ROI: effective_value = business_value + labor_savings
    ROI->>ROI: net_roi = (value - cost) / cost × 100
    ROI->>PG: persist roi_reports snapshot
    ROI-->>API: ROIResult + interpretation
    API-->>User: JSON response

Layer Overview

flowchart TB
    subgraph Ingestion
        A1[API Gateway]
        A2[Webhook Receiver]
        A3[AegisAI / AgentOps]
        A4[SDK]
    end

    subgraph Processing
        B1[Event Aggregator]
        B2[Metric Calculator]
        B3[ROI Engine]
        B4[Anomaly Detector]
        B5[Report Generator]
    end

    subgraph Store
        C1[(PostgreSQL)]
        C2[(Redis)]
        C3[(TimescaleDB)]
    end

    subgraph Present
        D1[Executive Dashboard]
        D2[Agent Performance]
        D3[ROI Calculator]
        D4[Compare]
        D5[PDF / Excel Reports]
    end

    Ingestion --> Processing --> Store --> Present