# openbb-finance/backends-for-openbb architecture

> Architecture diagram of the GitHub repository openbb-finance/backends-for-openbb, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openbb-finance/backends-for-openbb
- Repository: https://github.com/openbb-finance/backends-for-openbb

## Overview

##### Project Type and Purpose
- This is a monorepo of Python-based FastAPI microservices and example backends whose sole purpose is to serve JSON-formatted data and widget definitions to the OpenBB Workspace front-end.
- It provides:
- “demo-apps” (e.g., demo-risk, dtcc_trade_repository) – standalone FastAPI apps with their own data files and endpoints
- “getting-started” guides – minimal hello-world and reference backends for learning
- “widget-examples” – catalogues of connector patterns (database connectors, widget types, parameter handling)

##### File Structure Analysis
- Top level:
- demo-apps/ – each folder is an independent service (pyproject.toml, Dockerfile / fly.toml, FastAPI app)
- getting-started/ – tutorial services (hello-world, reference-backend)
- widget-examples/ – sample services grouped by widget type or data connector
- widget_examples/ – additional prompt_widget example
- Each service:
- main.py or app.py – FastAPI entry point
- widgets.json – widget metadata served at a defined endpoint
- requirements.txt or pyproject.toml – Python deps
- Dockerfile / fly.toml – containerization & deployment config
- Data files (.xz, .json, PDFs) or connectors (store.py, utils.py)

##### Insights from README
- Core contract: every integration must expose:
a) A `/widgets.json` endpoint describing widget metadata
b) One or more data endpoints returning JSON arrays or objects
c) CORS enabled for in-browser consumption
d) Optional authentication via headers or query params
- Emphasizes plug-and-play pattern: Workspace UI discovers widgets via widgets.json, then fetches data payloads

##### Diagramming the Architecture
a. Main Components
- OpenBB Workspace Front-End (UI)
- Integration Services (each demo-app or example service)
- Data Sources
· Flat files (portfolios.xz, swaps_data.xz, PDFs, mock_data.json)
· External Databases (ClickHouse, Supabase, Snowflake, Elasticsearch, MindsDB, ArcticDB)
- Deployment Infrastructure
· Docker / Fly.io (fly.toml)
· CI/CD (implied)
b. Relationships & Data Flow
1. UI issues GET /widgets.json → Integration Service
2. UI parses widget definitions (endpoint URLs, params, dataKey)
3. UI issues GET /data-endpoint → Integration Service
4. Integration Service reads from its data source (file or DB via connector code)
5. Integration Service returns JSON payload → UI renders widget
6. (Optional) Auth middleware intercepts and validates headers / query params
c. Architectural Patterns & Principles
- Microservice / Plugin architecture: each integration is self-contained
- Contract-first design: widgets.json defines the API contract
- RESTful JSON APIs with CORS
- Separation of concerns: UI, API surface, data access layer
- Reuse via consistent directory layout and code patterns
d. Key Technologies
- Python 3.x, FastAPI, Pydantic (models)
- Docker, Fly.io for containerized deployment
- Database client libraries (clickhouse-driver, snowflake-connector, elasticsearch-py, supabase-py, mindsdb, arcticdb-python)
- Plotly for chart widget demos

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend
    UI["OpenBB Workspace UI"]:::frontend

    %% Integration Services
    subgraph "Integration Services"
        direction TB
        demo_risk["demo-risk"]:::service
        dtcc_trade_repository["dtcc_trade_repository"]:::service
        hello_world["hello-world"]:::service
        reference_backend["reference-backend"]:::service

        subgraph "Database Connectors"
            direction TB
            arcticdb["ArcticDB Connector"]:::service
            clickhouse["ClickHouse Connector"]:::service
            elasticsearch["Elasticsearch Connector"]:::service
            mindsdb["MindsDB Connector"]:::service
            snowflake["Snowflake Connector"]:::service
            supabase["Supabase Connector"]:::service
        end

        subgraph "Parameter Types"
            direction TB
            column_and_cell["Column & Cell Rendering"]:::service
            form_parameter["Form Parameter"]:::service
            grouping_widgets["Grouping Widgets"]:::service
            parameters_example["Parameters Example"]:::service
        end

        subgraph "Widget Types"
            direction TB
            advanced_charting["Advanced Charting"]:::service
            chart_widget["Chart Widget"]:::service
            live_grid_widget["Live Grid Widget"]:::service
            markdown_widget["Markdown Widget"]:::service
            metric_widget["Metric Widget"]:::service
            multi_file_viewer["Multi File Viewer"]:::service
            news_widget["News Widget"]:::service
            pdf_widget["PDF Widget"]:::service
            table_widget["Table Widget"]:::service
        end

        prompt_widget["Prompt Widget"]:::service
    end

    %% Data Sources
    subgraph "Data Sources"
        direction TB
        flat_files["Flat Files"]:::files
        external_dbs["External Databases"]:::db
    end

    %% Flows
    UI -->|"GET /widgets.json"| demo_risk
    UI -->|"GET /widgets.json"| dtcc_trade_repository
    UI -->|"GET /widgets.json"| hello_world
    UI -->|"GET /widgets.json"| reference_backend
    UI -->|"GET /widgets.json"| arcticdb
    UI -->|"GET /widgets.json"| clickhouse
    UI -->|"GET /widgets.json"| elasticsearch
    UI -->|"GET /widgets.json"| mindsdb
    UI -->|"GET /widgets.json"| snowflake
    UI -->|"GET /widgets.json"| supabase
    UI -->|"GET /widgets.json"| column_and_cell
    UI -->|"GET /widgets.json"| form_parameter
    UI -->|"GET /widgets.json"| grouping_widgets
    UI -->|"GET /widgets.json"| parameters_example
    UI -->|"GET /widgets.json"| advanced_charting
    UI -->|"GET /widgets.json"| chart_widget
    UI -->|"GET /widgets.json"| live_grid_widget
    UI -->|"GET /widgets.json"| markdown_widget
    UI -->|"GET /widgets.json"| metric_widget
    UI -->|"GET /widgets.json"| multi_file_viewer
    UI -->|"GET /widgets.json"| news_widget
    UI -->|"GET /widgets.json"| pdf_widget
    UI -->|"GET /widgets.json"| table_widget
    UI -->|"GET /widgets.json"| prompt_widget

    demo_risk -->|reads portfolios.xz| flat_files
    dtcc_trade_repository -->|reads swaps_data.xz| flat_files
    dtcc_trade_repository -->|uses store.py| flat_files
    hello_world -->|no data source| flat_files
    reference_backend -->|uses sample.pdf| flat_files

    snowflake -->|connects via connector| external_dbs
    clickhouse -->|connects via clickhouse-driver| external_dbs
    elasticsearch -->|connects via elasticsearch-py| external_dbs
    supabase -->|connects via supabase-py| external_dbs
    mindsdb -->|connects via mindsdb| external_dbs
    arcticdb -->|connects via arcticdb-python| external_dbs

    %% Click Events
    click demo_risk "https://github.com/openbb-finance/backends-for-openbb/blob/main/demo-apps/demo-risk/demo_risk/app.py"
    click dtcc_trade_repository "https://github.com/openbb-finance/backends-for-openbb/blob/main/demo-apps/dtcc_trade_repository/openbb_swaps/main.py"
    click hello_world "https://github.com/openbb-finance/backends-for-openbb/blob/main/getting-started/hello-world/main.py"
    click reference_backend "https://github.com/openbb-finance/backends-for-openbb/blob/main/getting-started/reference-backend/main.py"
    click arcticdb "https://github.com/openbb-finance/backends-for-openbb/blob/main/widget-examples/database-connectors/arcticdb_python/main.py"
    click clickhouse "https://github.com/openbb-finance/backends-for-openbb/blob/main/widget-examples/database-connectors/clickhouse_python/main.py"
    click elasticsearch "https://github.com/openbb-finance/backends-for-openbb/blob/main/widget-examples/database-connectors/elasticsearch_python/main.py"
    click mindsdb "https://github.com/openbb-finance/backends-for-openbb/blob/main/widget-examples/database-connectors/mindsdb_python/main.py"
    click snowflake "https://github.com/openbb-finance/backends-for-openbb/blob/main/widget-examples/database-connectors/snowflake_connector_python/main.py"
    click supabase "https://github.com/openbb-finance/backends-for-openbb/blob/main/widget-examples/database-connectors/supabase_python/main.py"
    click column_and_cell "https://github.com/openbb-finance/backends-for-openbb/blob/main/widget-examples/parameters-types/column_and_cell_rendering/main.py"
    click form_parameter "https://github.com/openbb-finance/backends-for-openbb/blob/main/widget-examples/parameters-types/form_parameter/main.py"
    click grouping_widgets "https://github.com/openbb-finance/backends-for-openbb/blob/main/widget-examples/parameters-types/grouping_widgets/main.py"
    click parameters_example "https://github.com/openbb-finance/backends-for-openbb/blob/main/widget-examples/parameters-types/parameters_example/main.py"
    click advanced_charting "https://github.com/openbb-finance/backends-for-openbb/blob/main/widget-examples/widget-types/advanced_charting/main.py"
    click chart_widget "https://github.com/openbb-finance/backends-for-openbb/blob/main/widget-examples/widget-types/chart_widget/main.py"
    click live_grid_widget "https://github.com/openbb-finance/backends-for-openbb/blob/main/widget-examples/widget-types/live_grid_widget/main.py"
    click markdown_widget "https://github.com/openbb-finance/backends-for-openbb/blob/main/widget-examples/widget-types/markdown_widget/main.py"
    click metric_widget "https://github.com/openbb-finance/backends-for-openbb/blob/main/widget-examples/widget-types/metric_widget/main.py"
    click multi_file_viewer "https://github.com/openbb-finance/backends-for-openbb/blob/main/widget-examples/widget-types/multi_file_viewer/main.py"
    click news_widget "https://github.com/openbb-finance/backends-for-openbb/blob/main/widget-examples/widget-types/news_widget/main.py"
    click pdf_widget "https://github.com/openbb-finance/backends-for-openbb/blob/main/widget-examples/widget-types/pdf_widget/main.py"
    click table_widget "https://github.com/openbb-finance/backends-for-openbb/blob/main/widget-examples/widget-types/table_widget/main.py"
    click prompt_widget "https://github.com/openbb-finance/backends-for-openbb/blob/main/widget_examples/prompt_widget/main.py"

    %% Styles
    classDef frontend fill:#8FBFE0,stroke:#333,stroke-width:1px
    classDef service fill:#A2D39C,stroke:#333,stroke-width:1px
    classDef files fill:#F7DC6F,stroke:#333,stroke-width:1px
    classDef db fill:#D7BDE2,stroke:#333,stroke-width:1px
```
