Архитектура¶

AgentBI — платформа бизнес-аналитики для AI-агентов. Она принимает операционные и коммерческие события, агрегирует метрики ROI и предоставляет дашборды для CEO/CFO. В этом документе описаны основные компоненты и потоки данных.

Компоненты системы¶

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

Справочник компонентов¶

Компонент	Расположение	Назначение
API Gateway	`app/main.py`, `app/api/v1/`	REST API, маршрутизация, CORS, зависимости аутентификации
Ingest / Webhook	`app/api/v1/ingest.py`	Приём событий агентов, пакетный ingest, upstream webhooks
Ingest Service	`app/services/ingest_service.py`	Сохранение событий, автоматическая регистрация неизвестных агентов
Event Aggregator	`app/services/data_aggregator.py`	Группировка событий по агенту / периоду, временные бакеты
Metric Calculator	`app/services/metric_calculator.py`	Метрики портфеля и по агентам, снимки кэша
ROI Engine	`app/services/roi_engine.py`	ROI с учётом экономии труда, сравнение, портфель
Anomaly Detector	`app/services/anomaly_detector.py`	Сигналы падения эффективности, скачка стоимости, снижения ROI
Report Generator	`app/services/report_generator.py`	Исполнительные / агентские отчёты и сводки
Export Service	`app/services/export_service.py`	Экспорт в PDF и Excel
Auth	`app/core/security.py`, `app/api/v1/auth.py`	JWT-логин, API-ключи, роли RBAC
Frontend	`frontend/`	Executive, Agents, ROI, Compare, Reports
Traefik	`docker-compose.yml`	Reverse proxy на периметре

Потоки данных¶

Бизнес-событие → метрики¶

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¶

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

Обзор слоёв¶

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