How openbb-finance/backends-for-openbb works
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