> For the complete documentation index, see [llms.txt](https://docs.openalgo.in/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openalgo.in/developers/design-documentation/00-directory-structure.md). # 00 - Directory Structure ## Architectural Boundaries ``` openalgo/ |-- app.py Flask factory, blueprint registration, startup |-- extensions.py Shared Flask-SocketIO instance |-- limiter.py Shared Flask-Limiter instance |-- cors.py CORS configuration and init |-- csp.py CSP and security-header after_request middleware |-- restx_api/ External `/api/v1` resources and schemas |-- blueprints/ Session UI APIs, webhooks, React route serving |-- services/ Business logic and mode routing |-- broker/ 36 metadata-driven broker plugins |-- websocket_proxy/ Standalone asyncio WebSocket server and adapters |-- database/ SQLAlchemy/DuckDB models and persistence helpers |-- sandbox/ Analyzer execution, positions, funds, settlement |-- portfolio/ Portfolio analytics, attribution, crisis studies |-- sip/ SIP scheduling, XIRR and backtest analytics |-- events/ Typed EventBus payloads |-- subscribers/ Logging, Socket.IO, Telegram, WhatsApp consumers |-- utils/ Cross-cutting helpers, middleware, monitors |-- mcp/ Local stdio MCP server |-- frontend/ React 19 + TypeScript + Vite application |-- upgrade/ Database bootstrap and migration scripts |-- install/ Bare-metal, Docker and multi-instance installers |-- scripts/ Maintenance, benchmark and generator scripts |-- download/ Historify bulk downloaders and symbol seeds |-- docs/ API, BDD, design, PRD, guides, audits, releases |-- okf/ Open Knowledge Format bundle for agents |-- test/ Python tests, including sandbox tests |-- examples/ Python, Go, and Node.js integration examples |-- collections/ Bruno and Postman request collections |-- audit/ Point-in-time compatibility and leak audits |-- data/ Static seed data such as `qtyfreeze.csv` |-- db/ Runtime SQLite and DuckDB files (not source) |-- log/ Optional runtime log files (not source) |-- keys/ Remote MCP OAuth signing keys (runtime, not source) |-- workspace/ Gitignored personal scratch area `-- strategies/ User strategy scripts and runtime content ``` ## Request Layers | Layer | Owns | Must not own | | --------------- | ------------------------------------------------------------------ | ------------------------------- | | `restx_api/` | JSON/query parsing, Marshmallow validation, HTTP response | Broker-specific business rules | | `blueprints/` | Session-authenticated app APIs, webhooks, feature routes | Reusable broker execution logic | | `services/` | API-key verification, mode routing, normalized orchestration | Flask page rendering | | `broker//` | Broker authentication, request mapping, data transforms, streaming | Cross-broker product policy | | `database/` | Persistence models, migrations, queries, cache invalidation | HTTP contracts | | `sandbox/` | Simulated execution and account state | Live broker calls | ## Backend Inventory `restx_api/__init__.py` mounts one Flask-RESTX `Api` on the `api_v1` blueprint at `/api/v1` and registers 47 namespaces, which expose 63 method/path pairs in total. `blueprints/` contains 52 route modules covering the larger session and feature surface for auth, admin, Flow, Historify, strategies, tools, messaging, monitoring, and the React application. `services/` currently holds 79 modules. Public REST documentation is maintained in the [API reference](/api-documentation/v1.md). The service directory currently includes order, account, market-data, option, calendar, Flow, Historify, messaging, charting, analytics, arbitrage, custom straddle, and scalping risk services. Use `rg --files services` for the live inventory instead of copying a long file list into architecture documents. ## Broker Plugin Shape Every configured broker has `broker//plugin.json`. Common optional subtrees are: ``` broker// |-- plugin.json Name, type, supported exchanges, leverage flag |-- api/ | |-- auth_api.py `authenticate_broker(...)` | |-- order_api.py `place_order_api(...)` and order lifecycle calls | |-- data.py Quotes, depth, history, intervals | |-- funds.py Margin and funds | |-- margin_api.py Order margin preview | `-- gtt_api.py GTT lifecycle (Dhan and Zerodha only) |-- mapping/ | |-- transform_data.py OpenAlgo request to broker request | |-- order_data.py Broker response to OpenAlgo shape | |-- margin_data.py | `-- gtt_data.py |-- database/ | `-- master_contract_db.py Symbol master download and `symtoken` load `-- streaming/ |-- _adapter.py Market-data WebSocket adapter |-- _order_adapter.py Order-update ingestion `-- _mapping.py ``` Modules are imported lazily by name, not by a registry: `services/place_order_service.py` calls `importlib.import_module(f"broker.{broker_name}.api.order_api")` on each request, and `utils/plugin_loader.py` returns a `_LazyBrokerAuthDict` that imports `broker..api.auth_api` only on first access. Not every broker implements every optional file. Live GTT modules currently exist for Dhan and Zerodha only. ## Frontend Shape ``` frontend/src/ |-- main.tsx Vite entry point |-- App.tsx Lazy routes and auth gates |-- app/providers.tsx Query, theme, tooltip, Socket.IO providers |-- api/ Typed HTTP clients by feature |-- pages/ Top-level and grouped route pages |-- components/ Layout, trading, tools, Flow, scalping, UI |-- hooks/ Market data, Socket.IO, visibility, risk helpers |-- stores/ Zustand auth, broker, session, theme, Flow state |-- contexts/ React contexts shared across feature trees |-- lib/ MarketDataManager, plotting, math, helpers |-- utils/ Formatting and small pure helpers |-- config/ Build-time and runtime front-end configuration |-- types/ Feature contracts |-- assets/ Static assets bundled by Vite `-- test/ Vitest setup and accessibility helpers ``` ## Persistence Shape The deployment uses six primary configured stores: main `openalgo.db`, traffic `logs.db`, latency `latency.db`, health `health.db`, sandbox `sandbox.db`, and Historify `historify.duckdb`. Scalping tables use the main database URL. See [18 Database Structure](/developers/design-documentation/18-database-structure.md). ## Documentation Shape | Directory | Purpose | | ------------------------------ | ------------------------------------------ | | `docs/api` | External REST and WebSocket contracts | | `docs/bdd` | Gherkin specifications and inventories | | `docs/design` | Implemented architecture | | `docs/prd` | Current and subsystem product requirements | | `docs/audit` | Point-in-time reviews | | `docs/releases` | Release notes | | `docs/userguide` | End-user guides, including Remote MCP | | `docs/installation-guidelines` | Platform-specific install notes | | `docs/migration` | Upgrade and data-migration notes | | `docs/benchmarks` | Recorded benchmark runs |