# aditri-07/fo-analytics architecture

> Architecture diagram of the GitHub repository aditri-07/fo-analytics, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aditri-07/fo-analytics
- Repository: https://github.com/aditri-07/fo-analytics
- Video tour (about a minute): https://gitdiagram.com/aditri-07/fo-analytics/video

## Overview

This is a simulated-data front-office trade analytics platform. Its main workflow generates lifecycle-event feeds, loads and validates them, promotes accepted events into trade state and an audit trail, then derives daily positions and analytics for desk users. Separate product branches provide sales/client insights, natural-language queries, a dashboard, and a C++ position/P&L engine. The graph uses documented workflow links where source wiring was not sampled; those limits are noted with evidence references or unverified dashed edges.

Main entry points: [`fo/db/schema.sql`](https://github.com/aditri-07/fo-analytics/blob/main/fo/db/schema.sql) (Analytics database), [`dashboard.py`](https://github.com/aditri-07/fo-analytics/blob/main/dashboard.py) (Desk dashboard), [`fo/ai/agent.py`](https://github.com/aditri-07/fo-analytics/blob/main/fo/ai/agent.py) (Query agent), [`fo/etl/pipeline.py`](https://github.com/aditri-07/fo-analytics/blob/main/fo/etl/pipeline.py) (ETL promotion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Feed and ETL"]
  node_feedgen["Feed generator<br/>[feed_generator.py]"]
  node_feedfiles["Simulated feeds"]
  node_dbbootstrap["DB bootstrap<br/>[database.py]"]
  node_loader["Feed loader<br/>[loader.py]"]
  node_validator["DQ validator<br/>[validator.py]"]
  node_pipeline["ETL promotion<br/>[pipeline.py]"]
end

subgraph group_domain["Trade domain"]
  node_database[("Analytics database<br/>[schema.sql]")]
  node_trade["Trade lifecycle<br/>[trade.py]"]
  node_portfolio["Portfolio positions<br/>[portfolio.py]"]
end

subgraph group_analytics["Analytics"]
  node_marks["Position marks<br/>[marks.py]"]
  node_snapshots["EOD snapshots<br/>[snapshots.py]"]
  node_portfolioanalytics["Portfolio analytics<br/>[portfolio.py]"]
  node_salesanalytics["Sales analytics<br/>[sales.py]"]
end

subgraph group_query["Query and dashboard"]
  node_agent["Query agent<br/>[agent.py]"]
  node_tools["Analytics tools<br/>[tools.py]"]
  node_gemini{{"Gemini service"}}
  node_dashboard["Desk dashboard<br/>[dashboard.py]"]
end

subgraph group_engine["Position engine"]
  node_pyengine["Python engine<br/>[positions.py]"]
  node_cppengine["C++ engine<br/>[engine.cpp]"]
end

node_desk(("Desk user"))

node_desk -->|"requests simulation"| node_feedgen
node_feedgen -->|"writes feeds"| node_feedfiles
node_feedfiles -->|"loads files"| node_loader
node_dbbootstrap -->|"initializes schema"| node_database
node_loader -.->|"stages feed rows"| node_database
node_pipeline -->|"validates rows"| node_validator
node_pipeline -->|"promotes events"| node_database
node_pipeline -->|"updates trade state"| node_trade
node_database -.->|"supplies trades"| node_marks
node_marks -.->|"writes marks"| node_database
node_snapshots -.->|"writes snapshots"| node_database
node_database -->|"queries positions"| node_portfolioanalytics
node_database -->|"queries trades"| node_salesanalytics
node_desk -->|"asks questions"| node_agent
node_agent -->|"routes query"| node_gemini
node_agent -->|"dispatches calls"| node_tools
node_tools -->|"calls functions"| node_portfolioanalytics
node_tools -->|"calls functions"| node_salesanalytics
node_desk -->|"views analytics"| node_dashboard
node_dashboard -->|"uses analytics"| node_portfolioanalytics
node_dashboard -->|"uses analytics"| node_salesanalytics
node_dashboard -->|"offers query tab"| node_agent
node_portfolio -.->|"keeps positions"| node_pyengine
node_pyengine -->|"delegates computation"| node_cppengine

click node_feedgen "https://github.com/aditri-07/fo-analytics/blob/main/fo/simulator/feed_generator.py"
click node_dbbootstrap "https://github.com/aditri-07/fo-analytics/blob/main/fo/db/database.py"
click node_loader "https://github.com/aditri-07/fo-analytics/blob/main/fo/etl/loader.py"
click node_validator "https://github.com/aditri-07/fo-analytics/blob/main/fo/etl/validator.py"
click node_pipeline "https://github.com/aditri-07/fo-analytics/blob/main/fo/etl/pipeline.py"
click node_database "https://github.com/aditri-07/fo-analytics/blob/main/fo/db/schema.sql"
click node_trade "https://github.com/aditri-07/fo-analytics/blob/main/fo/models/trade.py"
click node_portfolio "https://github.com/aditri-07/fo-analytics/blob/main/fo/models/portfolio.py"
click node_marks "https://github.com/aditri-07/fo-analytics/blob/main/fo/analytics/marks.py"
click node_snapshots "https://github.com/aditri-07/fo-analytics/blob/main/fo/analytics/snapshots.py"
click node_portfolioanalytics "https://github.com/aditri-07/fo-analytics/blob/main/fo/analytics/portfolio.py"
click node_salesanalytics "https://github.com/aditri-07/fo-analytics/blob/main/fo/analytics/sales.py"
click node_agent "https://github.com/aditri-07/fo-analytics/blob/main/fo/ai/agent.py"
click node_tools "https://github.com/aditri-07/fo-analytics/blob/main/fo/ai/tools.py"
click node_dashboard "https://github.com/aditri-07/fo-analytics/blob/main/dashboard.py"
click node_pyengine "https://github.com/aditri-07/fo-analytics/blob/main/fo/engine/positions.py"
click node_cppengine "https://github.com/aditri-07/fo-analytics/blob/main/cpp/engine.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_feedgen,node_feedfiles,node_dbbootstrap,node_loader,node_validator,node_pipeline,node_desk toneBlue
class node_database,node_trade,node_portfolio toneAmber
class node_marks,node_snapshots,node_portfolioanalytics,node_salesanalytics toneMint
class node_agent,node_tools,node_gemini,node_dashboard toneRose
class node_pyengine,node_cppengine toneIndigo
```

## Components

### Feed and ETL

- [Feed generator](https://github.com/aditri-07/fo-analytics/blob/main/fo/simulator/feed_generator.py): `fo/simulator/feed_generator.py`
- **Simulated feeds**
- [DB bootstrap](https://github.com/aditri-07/fo-analytics/blob/main/fo/db/database.py): `fo/db/database.py`
- [Feed loader](https://github.com/aditri-07/fo-analytics/blob/main/fo/etl/loader.py): `fo/etl/loader.py`
- [DQ validator](https://github.com/aditri-07/fo-analytics/blob/main/fo/etl/validator.py): `fo/etl/validator.py`
- [ETL promotion](https://github.com/aditri-07/fo-analytics/blob/main/fo/etl/pipeline.py): `fo/etl/pipeline.py`

### Trade domain

- [Analytics database](https://github.com/aditri-07/fo-analytics/blob/main/fo/db/schema.sql): `fo/db/schema.sql`
- [Trade lifecycle](https://github.com/aditri-07/fo-analytics/blob/main/fo/models/trade.py): `fo/models/trade.py`
- [Portfolio positions](https://github.com/aditri-07/fo-analytics/blob/main/fo/models/portfolio.py): `fo/models/portfolio.py`

### Analytics

- [Position marks](https://github.com/aditri-07/fo-analytics/blob/main/fo/analytics/marks.py): `fo/analytics/marks.py`
- [EOD snapshots](https://github.com/aditri-07/fo-analytics/blob/main/fo/analytics/snapshots.py): `fo/analytics/snapshots.py`
- [Portfolio analytics](https://github.com/aditri-07/fo-analytics/blob/main/fo/analytics/portfolio.py): `fo/analytics/portfolio.py`
- [Sales analytics](https://github.com/aditri-07/fo-analytics/blob/main/fo/analytics/sales.py): `fo/analytics/sales.py`

### Query and dashboard

- [Query agent](https://github.com/aditri-07/fo-analytics/blob/main/fo/ai/agent.py): `fo/ai/agent.py`
- [Analytics tools](https://github.com/aditri-07/fo-analytics/blob/main/fo/ai/tools.py): `fo/ai/tools.py`
- **Gemini service**
- [Desk dashboard](https://github.com/aditri-07/fo-analytics/blob/main/dashboard.py): `dashboard.py`

### Position engine

- [Python engine](https://github.com/aditri-07/fo-analytics/blob/main/fo/engine/positions.py): `fo/engine/positions.py`
- [C++ engine](https://github.com/aditri-07/fo-analytics/blob/main/cpp/engine.cpp): `cpp/engine.cpp`

### Other components

- **Desk user**

## Connections

- Desk user → Feed generator: requests simulation (evidence: `README.md`)
- Feed generator → Simulated feeds: writes feeds (evidence: `README.md`)
- Simulated feeds → Feed loader: loads files (evidence: `README.md`)
- DB bootstrap → Analytics database: initializes schema (evidence: `fo/db/database.py`)
- Feed loader → Analytics database: stages feed rows
- ETL promotion → DQ validator: validates rows (evidence: `fo/etl/pipeline.py`)
- ETL promotion → Analytics database: promotes events (evidence: `fo/etl/pipeline.py`)
- ETL promotion → Trade lifecycle: updates trade state (evidence: `README.md`)
- Analytics database → Position marks: supplies trades
- Position marks → Analytics database: writes marks
- EOD snapshots → Analytics database: writes snapshots
- Analytics database → Portfolio analytics: queries positions (evidence: `fo/analytics/portfolio.py`)
- Analytics database → Sales analytics: queries trades (evidence: `fo/analytics/sales.py`)
- Desk user → Query agent: asks questions (evidence: `README.md`)
- Query agent → Gemini service: routes query (evidence: `fo/ai/agent.py`)
- Query agent → Analytics tools: dispatches calls (evidence: `fo/ai/agent.py`)
- Analytics tools → Portfolio analytics: calls functions (evidence: `fo/ai/tools.py`)
- Analytics tools → Sales analytics: calls functions (evidence: `fo/ai/tools.py`)
- Desk user → Desk dashboard: views analytics (evidence: `README.md`)
- Desk dashboard → Portfolio analytics: uses analytics (evidence: `dashboard.py`)
- Desk dashboard → Sales analytics: uses analytics (evidence: `dashboard.py`)
- Desk dashboard → Query agent: offers query tab (evidence: `dashboard.py`)
- Portfolio positions → Python engine: keeps positions
- Python engine → C++ engine: delegates computation (evidence: `README.md`)