This document describes the high-level architecture of the OpenBB Platform, explaining how commands flow from user interfaces through the core platform layer and back as structured results. It covers the extension system, command execution engine, provider abstraction, and static code generation mechanisms that enable the platform's "connect once, consume everywhere" philosophy.
For details on specific user interfaces (Python SDK, CLI, API, Workspace), see User Interfaces. For information on individual data extensions and providers, see Data Extensions and Data Providers. For the command execution implementation details, see Command Execution Engine.
The OpenBB Platform uses a layered architecture that separates user interfaces from data providers through a unified core platform layer. Commands are defined dynamically through routers, statically generated into Python modules for IDE support, and executed through a standardized pipeline that abstracts away provider-specific details.
Sources: openbb_platform/core/openbb_core/app/router.py1-100 openbb_platform/core/openbb_core/app/command_runner.py1-100 openbb_platform/core/openbb_core/app/extension_loader.py1-50 openbb_platform/core/openbb_core/app/static/package_builder.py134-169
The platform consists of four major layers:
| Layer | Components | Purpose |
|---|---|---|
| Interface Layer | CLI, Python SDK, FastAPI Server | User-facing entry points |
| Core Platform Layer | Router, CommandRunner, ExtensionLoader, ProviderInterface | Command routing and execution |
| Extension System | Core, Provider, OBBject extensions | Modular functionality |
| Build System | PackageBuilder, Static Package | IDE autocomplete support |
The platform uses Python entry points defined in pyproject.toml files to discover and load extensions at runtime. Extensions are categorized into three types, each serving a distinct purpose.
Sources: openbb_platform/core/openbb_core/app/extension_loader.py1-150 openbb_platform/pyproject.toml1-118
The ExtensionLoader class discovers extensions through three entry point groups:
| Entry Point Group | Extension Type | Example Extensions |
|---|---|---|
openbb_core_extension | Router modules organizing commands | openbb-equity, openbb-economy, openbb-etf |
openbb_provider_extension | Data provider implementations | openbb-fmp, openbb-fred, openbb-intrinio |
openbb_obbject_extension | OBBject output processors | openbb-charting, openbb-technical, openbb-quantitative |
Sources: openbb_platform/core/openbb_core/app/extension_loader.py40-120
The ExtensionLoader class implements the Singleton pattern and loads extensions lazily using @lru_cache decorators on its properties. Entry points are discovered via importlib_metadata.entry_points() and loaded into dictionaries indexed by extension name.
Commands flow through a multi-stage pipeline that validates parameters, resolves providers, executes fetchers, and wraps results in OBBject containers.
Sources: openbb_platform/core/openbb_core/app/router.py79-250 openbb_platform/core/openbb_core/app/static/package_builder.py145-146
The Router.command() decorator registers functions as API routes. Each command:
standard_params - common parameters across all providersextra_params - provider-specific parametersproviders through the ProviderInterfaceOBBject containing results and metadataSources: openbb_platform/core/openbb_core/app/command_runner.py34-237 openbb_platform/core/openbb_core/app/provider_interface.py70-350
The execution pipeline consists of:
| Stage | Component | Responsibility |
|---|---|---|
| Context Creation | ExecutionContext | Holds route, system settings, user settings |
| Parameter Building | ParametersBuilder | Merges args/kwargs, validates types, injects CommandContext |
| Command Execution | CommandRunner | Orchestrates execution, handles errors, triggers extensions |
| Provider Resolution | ProviderInterface | Maps route to fetcher, resolves provider choice |
| Data Fetching | Fetcher | Transforms query, calls external API, transforms data |
| Result Wrapping | OBBject | Contains results, provider, warnings, chart, metadata |
The ExecutionContext class provides access to system and user settings during command execution:
Sources: openbb_platform/core/openbb_core/app/command_runner.py34-57
The CommandContext is injected into functions that have a cc parameter:
Sources: openbb_platform/core/openbb_core/app/command_runner.py126-144
The ParametersBuilder.validate_kwargs() method creates a dynamic Pydantic model to validate and coerce parameters:
Sources: openbb_platform/core/openbb_core/app/command_runner.py180-206
The ProviderInterface enables multiple data providers to implement the same data types with consistent output. It dynamically generates parameter models and routes queries to the appropriate fetcher.
Sources: openbb_platform/core/openbb_core/provider/registry_map.py1-150
The RegistryMap maintains a mapping of routes to available providers and their fetchers:
Sources: openbb_platform/core/openbb_core/app/provider_interface.py150-450
Each fetcher implements two key methods:
| Method | Purpose | Responsibilities |
|---|---|---|
transform_query(params, credentials) | Prepare API request | Convert standard params to provider-specific format, add authentication |
transform_data(query, data, **kwargs) | Process API response | Parse JSON, convert to standard models, handle errors |
Standard models define the common schema across providers:
Provider-specific models extend the standard:
Sources: openbb_platform/core/openbb_core/app/provider_interface.py200-350
The PackageBuilder generates static Python modules from dynamic route definitions, enabling IDE autocomplete while maintaining runtime flexibility.
Sources: openbb_platform/core/openbb_core/app/static/package_builder.py134-305
The PackageBuilder.auto_build() method automatically triggers a build when extensions change:
Sources: openbb_platform/core/openbb_core/app/static/package_builder.py149-168
A file lock prevents concurrent builds:
Sources: openbb_platform/core/openbb_core/app/static/package_builder.py174-205
The ModuleBuilder generates a complete Python module for each router:
Sources: openbb_platform/core/openbb_core/app/static/package_builder.py363-374
ImportDefinition.build() extracts type hints from route functions and generates appropriate imports:
Sources: openbb_platform/core/openbb_core/app/static/package_builder.py529-664
ClassDefinition.build() creates a class with properties for sub-routers and methods for commands:
Sources: openbb_platform/core/openbb_core/app/static/package_builder.py667-759
MethodDefinition.build_command_method() generates command methods with full signatures:
Sources: openbb_platform/core/openbb_core/app/static/package_builder.py1000-1400
The reference.json file tracks installed extensions and available routes:
Sources: openbb_platform/core/openbb/assets/reference.json1-15 openbb_platform/core/openbb_core/app/static/package_builder.py268-285
The OBBject class provides a standardized container for command results with conversion methods and extension accessors.
Sources: openbb_platform/core/openbb_core/app/model/obbject.py36-150
The OBBject class uses PrivateAttr for internal metadata:
Sources: openbb_platform/core/openbb_core/app/model/obbject.py36-72
The OBBject provides methods to convert results to various formats:
| Method | Return Type | Description |
|---|---|---|
to_dataframe() / to_df() | pandas.DataFrame | Convert to pandas DataFrame with optional sorting |
to_dict() | dict | Convert to dictionary (orient="list" by default) |
to_numpy() | numpy.ndarray | Convert to NumPy array |
to_polars() | polars.DataFrame | Convert to Polars DataFrame |
Sources: openbb_platform/core/openbb_core/app/model/obbject.py81-300
The complete data flow from user request to result illustrates how all architectural components interact.
Sources: openbb_platform/core/openbb_core/app/static/container.py1-100 openbb_platform/core/openbb_core/app/command_runner.py240-400 openbb_platform/core/openbb_core/app/provider_interface.py200-450
| Stage | Input | Output | Component |
|---|---|---|---|
| User Call | Function call with parameters | Validated parameter dict | ParametersBuilder |
| Provider Resolution | Route + provider name | Fetcher class instance | ProviderInterface |
| Query Transform | Standard parameters | Provider-specific API params | Fetcher.transform_query() |
| Data Transform | Raw API response | List of standard models | Fetcher.transform_data() |
| Result Wrapping | Data + metadata | OBBject instance | CommandRunner |
| User Conversion | OBBject | DataFrame/dict/array | OBBject.to_*() methods |
Sources: openbb_platform/core/openbb_core/app/command_runner.py1-400 openbb_platform/core/openbb_core/app/provider_interface.py1-600
Refresh this wiki