# narender-rk10/openbi architecture

> Architecture diagram of the GitHub repository narender-rk10/openbi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/narender-rk10/openbi
- Repository: https://github.com/narender-rk10/openbi

## Overview

#### Purpose and Entry Points
OpenBI is a self-hosted AI business-intelligence platform: connect live data sources, define MindsDB-backed agents, query via chat, build dashboards, and distribute reports. The FastAPI process starts at `backend/main.py`; domain routers are assembled from `backend/api/`. The React SPA starts at `frontend/src/main.tsx` and routes from `frontend/src/App.tsx`. Docker topology is defined in `docker-compose.yml`.

#### Application Boundary, Identity, and Persistence
The backend owns tenancy, application state, and authorization; MongoDB is the system of record, accessed asynchronously through `backend/core/database.py`. JWT authentication, bcrypt password verification, and Fernet encryption for stored connection/LLM credentials are centralized in `backend/core/security.py`; API dependency enforcement is in `backend/api/deps.py`. Domain APIs persist projects, connections, agents, chats, dashboards, schedules, exports, and settings in MongoDB, while MindsDB holds executable agent/KB constructs.

#### Data Connectivity and AI Agent Layer
Connection management translates UI-provided source settings into encrypted MongoDB records and MindsDB database handlers through `backend/api/connections.py` and `backend/services/mindsdb_client.py`. Agent creation binds selected tables/connections and optional knowledge bases into MindsDB multi-skill agents via `backend/api/agents.py`. MindsDB is therefore the boundary to 90+ source handlers, text-to-SQL execution, and RAG retrieval; the OpenBI backend does not directly query customer databases.

#### Chat Execution Pipeline
`frontend/src/hooks/useChat.ts` consumes the primary SSE interaction exposed by `backend/api/chat.py`. Requests can target mentioned agents, use an active agent, or invoke LLM-based routing. The backend restores bounded conversation history from MongoDB, handles greetings locally, streams MindsDB agent output, extracts generated SQL, re-executes it for structured rows, and emits status/SQL/data/answer events. `backend/services/llm_client.py` abstracts Gemini, OpenAI, and Anthropic for routing and synthesis; optional tracing flows through `backend/services/langfuse_client.py`.

#### Dashboard Authoring and Real-Time State
Dashboards store widget SQL, display configuration, cached result data, filters, and versions as application documents behind `backend/api/dashboards.py` and `backend/services/version_service.py`. Widgets execute through MindsDB; AI-generated visual/table configurations are produced by `backend/services/chart_agent.py` and `backend/services/table_agent.py`. The primary interactive surface is `frontend/src/pages/DashboardViewPage.tsx`, rendering chart/table/KPI/narrative widgets from `frontend/src/components/dashboard/`. WebSocket coordination is handled by `backend/api/ws.py` and `backend/services/websocket_manager.py`, with Redis pub/sub as the multi-viewer broadcast boundary.

#### Knowledge Bases and Exports
Knowledge-base APIs in `backend/api/knowledge_bases.py` ingest uploads or crawled content, prepare supported files, and delegate chunking, embeddings, and vector storage to MindsDB. PDF history/export behavior is represented by `backend/services/pdf_service.py`; PPTX generation delegates asynchronously to the separate Presenton service through `backend/services/pptx_service.py`. PDF capture is client-side from dashboard UI, while persisted export/version metadata remains in MongoDB.

#### Automation and Deployment Services
Schedules are persisted and registered in the in-process APScheduler flow in `backend/services/scheduler_service.py`; execution refreshes dashboard data and dispatches email, Telegram, or webhook deliveries through `backend/services/report_runner.py` and `backend/services/delivery_service.py`. The optional bot is an independent process at `telegram_bot/bot.py`. Material runtime services are FastAPI/Python 3.11, React/TypeScript, MindsDB, Redis, external MongoDB, optional Presenton, SMTP, Telegram, and Langfuse, containerized by `docker-compose.yml`.

Main entry points: [`backend/main.py`](https://github.com/narender-rk10/openbi/blob/master/backend/main.py) (API application), [`backend/core/database.py`](https://github.com/narender-rk10/openbi/blob/master/backend/core/database.py) (Application persistence), [`backend/api/chat.py`](https://github.com/narender-rk10/openbi/blob/master/backend/api/chat.py) (Chat pipeline), [`backend/api/dashboards.py`](https://github.com/narender-rk10/openbi/blob/master/backend/api/dashboards.py) (Dashboards API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React SPA"]
  node_spa_entry["SPA entry<br/>React bootstrap<br/>[main.tsx]"]
  node_app_routes["App routes<br/>React routing<br/>[App.tsx]"]
  node_chat_hook["Chat client<br/>SSE hook<br/>[useChat.ts]"]
  node_dashboard_view["Dashboard view<br/>interactive UI"]
end

subgraph group_backend["FastAPI backend"]
  node_api_app["API application<br/>FastAPI<br/>[main.py]"]
  node_auth_boundary["Identity and access<br/>JWT auth<br/>[deps.py]"]
  node_security["Security services<br/>crypto<br/>[security.py]"]
  node_mongo_access["Application persistence<br/>async Mongo access<br/>[database.py]"]
  node_connection_api["Connections API<br/>domain router<br/>[connections.py]"]
  node_agent_api["Agents API<br/>domain router<br/>[agents.py]"]
  node_chat_api["Chat pipeline<br/>SSE router<br/>[chat.py]"]
  node_dashboard_api["Dashboards API<br/>domain router<br/>[dashboards.py]"]
  node_realtime["Realtime coordination<br/>WebSocket manager<br/>[ws.py]"]
  node_scheduler["Report scheduler<br/>APScheduler service"]
  node_delivery["Report delivery<br/>delivery service"]
end

subgraph group_ai["AI and data boundary"]
  node_mindsdb_client["MindsDB client<br/>integration client<br/>[mindsdb_client.py]"]
  node_llm_client["LLM abstraction<br/>AI client<br/>[llm_client.py]"]
  node_mindsdb{{"MindsDB<br/>agent and data runtime"}}
end

subgraph group_runtime["Runtime services"]
  node_mongodb[("MongoDB<br/>system of record")]
  node_redis["Redis pub/sub<br/>broadcast broker"]
  node_delivery_targets["Delivery channels"]
  node_compose["Container topology<br/>Docker Compose<br/>[docker-compose.yml]"]
end

node_spa_entry -->|"mounts"| node_app_routes
node_app_routes -->|"chat UI"| node_chat_hook
node_app_routes -->|"dashboard UI"| node_dashboard_view
node_chat_hook -->|"SSE chat"| node_chat_api
node_dashboard_view -->|"author and load"| node_dashboard_api
node_dashboard_view -->|"WebSocket updates"| node_realtime
node_api_app -->|"applies dependencies"| node_auth_boundary
node_auth_boundary -->|"validates tokens"| node_security
node_api_app -->|"routes"| node_connection_api
node_api_app -->|"routes"| node_agent_api
node_api_app -->|"routes"| node_chat_api
node_api_app -->|"routes"| node_dashboard_api
node_connection_api -->|"stores settings"| node_mongo_access
node_agent_api -->|"stores metadata"| node_mongo_access
node_chat_api -->|"loads history"| node_mongo_access
node_dashboard_api -->|"stores dashboards"| node_mongo_access
node_mongo_access -->|"async persistence"| node_mongodb
node_connection_api -->|"provisions handlers"| node_mindsdb_client
node_agent_api -->|"creates agents"| node_mindsdb_client
node_chat_api -->|"routing and synthesis"| node_llm_client
node_chat_api -->|"streams agent and SQL results"| node_mindsdb_client
node_dashboard_api -->|"executes widgets"| node_mindsdb_client
node_mindsdb_client -->|"API boundary"| node_mindsdb
node_realtime -->|"publishes updates"| node_redis
node_scheduler -->|"loads schedules"| node_mongo_access
node_scheduler -->|"refreshes dashboard data"| node_dashboard_api
node_scheduler -->|"runs reports"| node_delivery
node_delivery -->|"dispatches"| node_delivery_targets
node_compose -.->|"runs"| node_api_app
node_compose -.->|"runs"| node_mindsdb
node_compose -.->|"runs"| node_redis

click node_spa_entry "https://github.com/narender-rk10/openbi/blob/master/frontend/src/main.tsx"
click node_app_routes "https://github.com/narender-rk10/openbi/blob/master/frontend/src/App.tsx"
click node_chat_hook "https://github.com/narender-rk10/openbi/blob/master/frontend/src/hooks/useChat.ts"
click node_dashboard_view "https://github.com/narender-rk10/openbi/blob/master/frontend/src/pages/DashboardViewPage.tsx"
click node_api_app "https://github.com/narender-rk10/openbi/blob/master/backend/main.py"
click node_auth_boundary "https://github.com/narender-rk10/openbi/blob/master/backend/api/deps.py"
click node_security "https://github.com/narender-rk10/openbi/blob/master/backend/core/security.py"
click node_mongo_access "https://github.com/narender-rk10/openbi/blob/master/backend/core/database.py"
click node_connection_api "https://github.com/narender-rk10/openbi/blob/master/backend/api/connections.py"
click node_agent_api "https://github.com/narender-rk10/openbi/blob/master/backend/api/agents.py"
click node_chat_api "https://github.com/narender-rk10/openbi/blob/master/backend/api/chat.py"
click node_dashboard_api "https://github.com/narender-rk10/openbi/blob/master/backend/api/dashboards.py"
click node_realtime "https://github.com/narender-rk10/openbi/blob/master/backend/api/ws.py"
click node_scheduler "https://github.com/narender-rk10/openbi/blob/master/backend/services/scheduler_service.py"
click node_delivery "https://github.com/narender-rk10/openbi/blob/master/backend/services/delivery_service.py"
click node_mindsdb_client "https://github.com/narender-rk10/openbi/blob/master/backend/services/mindsdb_client.py"
click node_llm_client "https://github.com/narender-rk10/openbi/blob/master/backend/services/llm_client.py"
click node_compose "https://github.com/narender-rk10/openbi/blob/master/docker-compose.yml"

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_spa_entry,node_app_routes,node_chat_hook,node_dashboard_view toneBlue
class node_api_app,node_auth_boundary,node_security,node_mongo_access,node_connection_api,node_agent_api,node_chat_api,node_dashboard_api,node_realtime,node_scheduler,node_delivery toneAmber
class node_mindsdb_client,node_llm_client,node_mindsdb toneMint
class node_mongodb,node_redis,node_delivery_targets,node_compose toneRose
```

## Components

### React SPA

- [SPA entry](https://github.com/narender-rk10/openbi/blob/master/frontend/src/main.tsx): React bootstrap · `frontend/src/main.tsx`
- [App routes](https://github.com/narender-rk10/openbi/blob/master/frontend/src/App.tsx): React routing · `frontend/src/App.tsx`
- [Chat client](https://github.com/narender-rk10/openbi/blob/master/frontend/src/hooks/useChat.ts): SSE hook · Consumes streamed chat events. · `frontend/src/hooks/useChat.ts`
- [Dashboard view](https://github.com/narender-rk10/openbi/blob/master/frontend/src/pages/DashboardViewPage.tsx): interactive UI · Renders dashboard widgets and captures PDFs client-side. · `frontend/src/pages/DashboardViewPage.tsx`

### FastAPI backend

- [API application](https://github.com/narender-rk10/openbi/blob/master/backend/main.py): FastAPI · Assembles domain routers. · `backend/main.py`
- [Identity and access](https://github.com/narender-rk10/openbi/blob/master/backend/api/deps.py): JWT auth · Dependencies enforce authorization; credentials are encrypted. · `backend/api/deps.py`
- [Security services](https://github.com/narender-rk10/openbi/blob/master/backend/core/security.py): crypto · JWT, bcrypt, and Fernet credential encryption. · `backend/core/security.py`
- [Application persistence](https://github.com/narender-rk10/openbi/blob/master/backend/core/database.py): async Mongo access · Stores tenancy, state, metadata, and histories. · `backend/core/database.py`
- [Connections API](https://github.com/narender-rk10/openbi/blob/master/backend/api/connections.py): domain router · Persists encrypted source settings and provisions handlers. · `backend/api/connections.py`
- [Agents API](https://github.com/narender-rk10/openbi/blob/master/backend/api/agents.py): domain router · Creates multi-skill agents from connections, tables, and KBs. · `backend/api/agents.py`
- [Chat pipeline](https://github.com/narender-rk10/openbi/blob/master/backend/api/chat.py): SSE router · Restores history, routes requests, streams answers, and re-executes generated SQL. · `backend/api/chat.py`
- [Dashboards API](https://github.com/narender-rk10/openbi/blob/master/backend/api/dashboards.py): domain router · Stores widget SQL, configurations, cached data, filters, and versions. · `backend/api/dashboards.py`
- [Realtime coordination](https://github.com/narender-rk10/openbi/blob/master/backend/api/ws.py): WebSocket manager · Coordinates multi-viewer dashboard updates. · `backend/api/ws.py`
- [Report scheduler](https://github.com/narender-rk10/openbi/blob/master/backend/services/scheduler_service.py): APScheduler service · Registers persisted schedules and refreshes dashboards. · `backend/services/scheduler_service.py`
- [Report delivery](https://github.com/narender-rk10/openbi/blob/master/backend/services/delivery_service.py): delivery service · Dispatches email, Telegram, and webhook reports. · `backend/services/delivery_service.py`

### AI and data boundary

- [MindsDB client](https://github.com/narender-rk10/openbi/blob/master/backend/services/mindsdb_client.py): integration client · Backend boundary for handlers, agents, SQL execution, and knowledge bases. · `backend/services/mindsdb_client.py`
- [LLM abstraction](https://github.com/narender-rk10/openbi/blob/master/backend/services/llm_client.py): AI client · Uses Gemini, OpenAI, or Anthropic for routing and synthesis. · `backend/services/llm_client.py`
- **MindsDB**: agent and data runtime · Owns source handlers, text-to-SQL, RAG, embeddings, and vectors.

### Runtime services

- **MongoDB**: system of record · External application database.
- **Redis pub/sub**: broadcast broker · Multi-viewer realtime broadcast boundary.
- **Delivery channels**: SMTP / Telegram / webhook
- [Container topology](https://github.com/narender-rk10/openbi/blob/master/docker-compose.yml): Docker Compose · Defines the material runtime services. · `docker-compose.yml`

## Connections

- SPA entry → App routes: mounts
- App routes → Chat client: chat UI
- App routes → Dashboard view: dashboard UI
- Chat client → Chat pipeline: SSE chat
- Dashboard view → Dashboards API: author and load
- Dashboard view → Realtime coordination: WebSocket updates
- API application → Identity and access: applies dependencies
- Identity and access → Security services: validates tokens
- API application → Connections API: routes
- API application → Agents API: routes
- API application → Chat pipeline: routes
- API application → Dashboards API: routes
- Connections API → Application persistence: stores settings
- Agents API → Application persistence: stores metadata
- Chat pipeline → Application persistence: loads history
- Dashboards API → Application persistence: stores dashboards
- Application persistence → MongoDB: async persistence
- Connections API → MindsDB client: provisions handlers
- Agents API → MindsDB client: creates agents
- Chat pipeline → LLM abstraction: routing and synthesis
- Chat pipeline → MindsDB client: streams agent and SQL results
- Dashboards API → MindsDB client: executes widgets
- MindsDB client → MindsDB: API boundary
- Realtime coordination → Redis pub/sub: publishes updates
- Report scheduler → Application persistence: loads schedules
- Report scheduler → Dashboards API: refreshes dashboard data
- Report scheduler → Report delivery: runs reports
- Report delivery → Delivery channels: dispatches
- Container topology → API application: runs
- Container topology → MindsDB: runs
- Container topology → Redis pub/sub: runs