00 - Directory Structure
Architectural Boundaries
tradeboard/
|-- 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 contentRequest 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/<key>/ | 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.
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/<key>/plugin.json. Common optional subtrees are:
broker/<key>/
|-- 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 Tradeboard request to broker request
| |-- order_data.py Broker response to Tradeboard shape
| |-- margin_data.py
| `-- gtt_data.py
|-- database/
| `-- master_contract_db.py Symbol master download and `symtoken` load
`-- streaming/
|-- <key>_adapter.py Market-data WebSocket adapter
|-- <key>_order_adapter.py Order-update ingestion
`-- <key>_mapping.pyModules 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.<key>.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 helpersPersistence Shape
The deployment uses six primary configured stores: main tradeboard.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.
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 |