> 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.md).

# Design Documentation

This directory describes the implemented architecture of the current OpenAlgo source tree. OpenAlgo is a self-hosted, single-user trading application with a Flask/Flask-RESTX backend, React 19 frontend, broker plugins, a separate WebSocket proxy, sandbox execution, hosted strategies, Flow automation, portfolio analytics, chart trading, and optional local or remote MCP access.

The current inventory is 39 broker plugins, including Dhan Sandbox and Delta Exchange for crypto derivatives. Each has a `plugin.json`. Broker capabilities are metadata-driven; a plugin's presence does not imply every optional broker operation is supported.

## Documentation Policy

* Code and registered routes are authoritative when a design document conflicts with an example.
* The public REST contract lives in the [API documentation](https://docs.openalgo.in/api-documentation/v1.md).
* Flask-RESTX Swagger/OpenAPI UI is intentionally disabled with `doc=False` in `restx_api/__init__.py`. Do not advertise or re-enable `/api/docs` as part of documentation maintenance.
* These pages describe implemented behavior verified against the application code and registered routes.

## Runtime And Core Architecture

| Module                                                                                                       | Description                                              |
| ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------- |
| [00 Directory Structure](https://docs.openalgo.in/developers/design-documentation/00-directory-structure.md) | Current repository boundaries and ownership              |
| [01 Frontend](https://docs.openalgo.in/developers/design-documentation/architecture.md)                      | React 19, Vite 8, routing, state, data access            |
| [02 Backend](https://docs.openalgo.in/developers/design-documentation/02-backend-architecture.md)            | Flask factory, route layers, services, background work   |
| [04 Cache Architecture](https://docs.openalgo.in/developers/design-documentation/broker-integerations.md)    | In-process caches and invalidation behavior              |
| [17 Connection Pooling](https://docs.openalgo.in/developers/design-documentation/17-connection-pooling.md)   | HTTP and market-data connection reuse                    |
| [18 Database Structure](https://docs.openalgo.in/developers/design-documentation/18-database-structure.md)   | SQLite and DuckDB stores, `NullPool`, teardown           |
| [20 Design Principles](https://docs.openalgo.in/developers/design-documentation/20-design-principles.md)     | Local conventions and architectural constraints          |
| [27 Service Layer](https://docs.openalgo.in/developers/design-documentation/27-service-layer.md)             | Route-to-service-to-broker boundaries                    |
| [31 Utilities](https://docs.openalgo.in/developers/design-documentation/31-utils-functionalities.md)         | Shared auth, config, logging, networking helpers         |
| [34 App Startup](https://docs.openalgo.in/developers/design-documentation/34-app-startup.md)                 | Validation, registration, initialization, server startup |
| [53 Event Bus](https://docs.openalgo.in/developers/design-documentation/53-event-bus.md)                     | Per-process async side-effect dispatch                   |

## Authentication And Security

| Module                                                                                                                      | Description                                                |
| --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| [03 Login And Broker Flow](https://docs.openalgo.in/developers/design-documentation/api-layer.md)                           | App auth, TOTP, broker selection, session resume           |
| [05 Security Architecture](https://docs.openalgo.in/developers/design-documentation/database-layer.md)                      | Keys, encryption, CSRF, CORS, CSP, middleware              |
| [23 IP Security](https://docs.openalgo.in/developers/design-documentation/23-ip-security.md)                                | IP extraction, bans, proxy trust                           |
| [24 Browser Security](https://docs.openalgo.in/developers/design-documentation/24-browser-security.md)                      | Cookies, CSRF, CSP, hardening headers                      |
| [40 Logout And Session Lifecycle](https://docs.openalgo.in/developers/design-documentation/40-logout-and-session-expiry.md) | Daily expiry, heartbeat, reconnect, multi-session behavior |
| [47 SMTP Configuration](https://docs.openalgo.in/developers/design-documentation/47-smtp-configuration.md)                  | Mail configuration and diagnostics                         |
| [48 Password Reset](https://docs.openalgo.in/developers/design-documentation/48-password-reset.md)                          | Reset flow and password change revocation                  |
| [50 TOTP Configuration](https://docs.openalgo.in/developers/design-documentation/50-totp-configuration.md)                  | Per-purpose two-factor policy                              |

## Trading, Data, And Automation

| Module                                                                                                                     | Description                                                                |
| -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| [06 WebSockets](https://docs.openalgo.in/developers/design-documentation/authentication-platforms.md)                      | Proxy protocol, ZMQ fan-in, adapters, subscriptions                        |
| [07 Sandbox](https://docs.openalgo.in/developers/design-documentation/configuration.md)                                    | Analyzer execution engine and isolated state                               |
| [08 Historify](https://docs.openalgo.in/developers/design-documentation/utilities.md)                                      | DuckDB historical-data subsystem                                           |
| [09 REST API](https://docs.openalgo.in/developers/design-documentation/broker-integration-checklist.md)                    | Registered v1 architecture; Swagger intentionally disabled                 |
| [10 Flow](https://docs.openalgo.in/developers/design-documentation/10-flow-architecture.md)                                | Visual workflow storage and execution                                      |
| [13 Chartink](https://docs.openalgo.in/developers/design-documentation/13-chartink-architecture.md)                        | Scanner automation                                                         |
| [14 TradingView And GoCharting](https://docs.openalgo.in/developers/design-documentation/14-tradingview-and-gocharting.md) | JSON integration surfaces                                                  |
| [19 PlaceOrder Flow](https://docs.openalgo.in/developers/design-documentation/19-placeorder-call-flow.md)                  | Validation, mode routing, Action Center, broker calls                      |
| [32 Master Contract](https://docs.openalgo.in/developers/design-documentation/32-master-contract-download.md)              | Broker instrument downloads and cache policy                               |
| [33 Broker Folder](https://docs.openalgo.in/developers/design-documentation/33-broker-folder-explanations.md)              | Plugin module convention                                                   |
| [38 Python Strategies](https://docs.openalgo.in/developers/design-documentation/38-python-strategies-hosting.md)           | Hosted-process model and logs                                              |
| [39 Strategy RMS Engine](https://docs.openalgo.in/developers/design-documentation/39-strategy-module.md)                   | Durable multi-leg and signal lifecycle, RMS, recovery, RESTX, and webhooks |
| [42 Action Center](https://docs.openalgo.in/developers/design-documentation/42-action-center.md)                           | Semi-auto order approval                                                   |
| [54 Scalping Terminal](https://docs.openalgo.in/developers/design-documentation/54-scalping-terminal.md)                   | Keyboard trading, charts, persisted stops, risk monitor                    |
| [55 Portfolio Analytics](https://docs.openalgo.in/developers/design-documentation/55-portfolio-analytics.md)               | Read-only backtesting and current-holdings scenario analysis               |

## UI, Tools, And Integrations

| Module                                                                                                                 | Description                                            |
| ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| [15 Basic UI And Analytics](https://docs.openalgo.in/developers/design-documentation/15-basic-ui-elements.md)          | Current React pages and analytics tools                |
| [37 API Key And Playground](https://docs.openalgo.in/developers/design-documentation/37-api-key-and-playground.md)     | API key management and WebSocket tester                |
| [41 MCP Architecture](https://docs.openalgo.in/developers/design-documentation/41-mcp-architecture.md)                 | Local stdio and opt-in remote OAuth transport          |
| [43 Telegram Bot](https://docs.openalgo.in/developers/design-documentation/43-telegram-bot-configuration.md)           | Bot lifecycle, commands, automatic and explicit alerts |
| [44 Toast Notifications](https://docs.openalgo.in/developers/design-documentation/44-toast-notifications-system.md)    | Browser notification categories                        |
| [44 PnL Tracker](https://docs.openalgo.in/developers/design-documentation/44-pnl-tracker.md)                           | Live P\&L charting                                     |
| [46 Search](https://docs.openalgo.in/developers/design-documentation/46-search.md)                                     | Contract and underlying search                         |
| [49 Themes](https://docs.openalgo.in/developers/design-documentation/49-themes.md)                                     | Theme and accent persistence                           |
| [51 Broker And System Config](https://docs.openalgo.in/developers/design-documentation/51-broker-and-system-config.md) | Environment and broker configuration boundaries        |
| [52 Broker Factory](https://docs.openalgo.in/developers/design-documentation/52-broker-factory-implementation.md)      | WebSocket adapter construction                         |

## Operations And Deployment

| Module                                                                                                                     | Description                                |
| -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| [11 Docker](https://docs.openalgo.in/developers/design-documentation/11-docker-configuration.md)                           | Container build and compose runtime        |
| [12 Ubuntu Server](https://docs.openalgo.in/developers/design-documentation/12-ubuntu-server-installation.md)              | Host deployment                            |
| [16 Centralized Logging](https://docs.openalgo.in/developers/design-documentation/16-centralized-logging.md)               | Python logs and file retention             |
| [21 Admin Section](https://docs.openalgo.in/developers/design-documentation/21-admin-section.md)                           | Runtime and Remote MCP administration      |
| [22 Log Section](https://docs.openalgo.in/developers/design-documentation/22-log-section.md)                               | Order and analyzer log views               |
| [25 Latency Monitor](https://docs.openalgo.in/developers/design-documentation/25-latency-monitor.md)                       | API timing data                            |
| [26 Traffic Logs](https://docs.openalgo.in/developers/design-documentation/26-traffic-logs.md)                             | Request telemetry and ban support          |
| [28 Environment Configuration](https://docs.openalgo.in/developers/design-documentation/28-environment-configuration.md)   | `.env` contract                            |
| [29 Ngrok Configuration](https://docs.openalgo.in/developers/design-documentation/29-ngrok-configuration.md)               | Tunnel management                          |
| [30 Upgrade Procedure](https://docs.openalgo.in/developers/design-documentation/30-upgrade-procedure.md)                   | Upgrade and backup flow                    |
| [35 Development And Testing](https://docs.openalgo.in/developers/design-documentation/35-development-and-testing-guide.md) | Local checks and CI coverage               |
| [36 Rate Limiting](https://docs.openalgo.in/developers/design-documentation/36-rate-limiting-guide.md)                     | Limiter configuration and endpoint classes |
