Design Documentation

This directory describes the implemented architecture of OpenAlgo 2.0.1.7. 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 plugin inventory contains 35 broker directories with 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.

• 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	Current repository boundaries and ownership
01 Frontend	React 19, Vite 8, routing, state, data access
02 Backend	Flask factory, route layers, services, background work
04 Cache Architecture	In-process caches and invalidation behavior
17 Connection Pooling	HTTP and market-data connection reuse
18 Database Structure	SQLite and DuckDB stores, NullPool, teardown
20 Design Principles	Local conventions and architectural constraints
27 Service Layer	Route-to-service-to-broker boundaries
31 Utilities	Shared auth, config, logging, networking helpers
34 App Startup	Validation, registration, initialization, server startup
53 Event Bus	Per-process async side-effect dispatch

Authentication And Security

Module	Description
03 Login And Broker Flow	App auth, TOTP, broker selection, session resume
05 Security Architecture	Keys, encryption, CSRF, CORS, CSP, middleware
23 IP Security	IP extraction, bans, proxy trust
24 Browser Security	Cookies, CSRF, CSP, hardening headers
40 Logout And Session Lifecycle	Daily expiry, heartbeat, reconnect, multi-session behavior
47 SMTP Configuration	Mail configuration and diagnostics
48 Password Reset	Reset flow and password change revocation
50 TOTP Configuration	Per-purpose two-factor policy

Trading, Data, And Automation

Module	Description
06 WebSockets	Proxy protocol, ZMQ fan-in, adapters, subscriptions
07 Sandbox	Analyzer execution engine and isolated state
08 Historify	DuckDB historical-data subsystem
09 REST API	Registered v1 architecture; Swagger intentionally disabled
10 Flow	Visual workflow storage and execution
13 Chartink	Scanner automation
14 TradingView And GoCharting	JSON integration surfaces
19 PlaceOrder Flow	Validation, mode routing, Action Center, broker calls
32 Master Contract	Broker instrument downloads and cache policy
33 Broker Folder	Plugin module convention
38 Python Strategies	Hosted-process model and logs
39 Strategy Module	Webhook strategy management
42 Action Center	Semi-auto order approval
54 Scalping Terminal	Keyboard trading, charts, persisted stops, risk monitor
55 Portfolio Analytics	Read-only backtesting and current-holdings scenario analysis

UI, Tools, And Integrations

Module	Description
15 Basic UI And Analytics	Current React pages and analytics tools
37 API Key And Playground	API key management and WebSocket tester
41 MCP Architecture	Local stdio and opt-in remote OAuth transport
43 Telegram Bot	Bot lifecycle, commands, automatic and explicit alerts
43 Toast Notifications	Browser notification categories
44 PnL Tracker	Live P&L charting
46 Search	Contract and underlying search
49 Themes	Theme and accent persistence
51 Broker And System Config	Environment and broker configuration boundaries
52 Broker Factory	WebSocket adapter construction

Operations And Deployment

Module	Description
11 Docker	Container build and compose runtime
12 Ubuntu Server	Host deployment
16 Centralized Logging	Python logs and file retention
21 Admin Section	Runtime and Remote MCP administration
22 Log Section	Order and analyzer log views
25 Latency Monitor	API timing data
26 Traffic Logs	Request telemetry and ban support
28 Environment Configuration	.env contract
29 Ngrok Configuration	Tunnel management
30 Upgrade Procedure	Upgrade and backup flow
35 Development And Testing	Local checks and CI coverage
36 Rate Limiting	Limiter configuration and endpoint classes