# 00 - Directory Structure ### Overview OpenAlgo follows a modular architecture with clear separation of concerns. This document provides a comprehensive map of the project structure to help developers navigate the codebase effectively. ### Root Directory ``` openalgo/ ├── app.py # Flask application entry point ├── extensions.py # Flask extensions (SocketIO, CORS) ├── cors.py # CORS configuration ├── csp.py # Content Security Policy ├── limiter.py # Rate limiting setup ├── utils.py # Legacy utilities │ ├── .env # Environment configuration (not in git) ├── .sample.env # Environment template ├── pyproject.toml # Python dependencies (uv) ├── requirements.txt # Pip fallback dependencies ├── uv.lock # Locked dependency versions │ ├── CLAUDE.md # AI assistant instructions ├── README.md # Project overview ├── CONTRIBUTING.md # Contribution guidelines ├── SECURITY.md # Security policy ├── License.md # AGPL-3.0 license │ ├── Dockerfile # Container build ├── docker-compose.yaml # Multi-container setup ├── start.sh # Production startup script │ ├── blueprints/ # Flask route handlers ├── restx_api/ # REST API endpoints ├── services/ # Business logic layer ├── database/ # Database models & utilities ├── broker/ # Broker integrations (29 brokers) ├── utils/ # Shared utilities ├── websocket_proxy/ # Real-time data server ├── sandbox/ # Sandbox trading engine ├── frontend/ # React 19 SPA ├── docs/ # Documentation ├── test/ # Test suites └── db/ # SQLite database files ``` ### Core Backend Modules #### `/blueprints/` - Flask Route Handlers UI routes and webhook handlers organized by feature. ``` blueprints/ ├── __init__.py ├── core.py # Base routes, health checks ├── auth.py # Login, logout, session management ├── brlogin.py # Broker OAuth callbacks ├── dashboard.py # Main dashboard UI ├── orders.py # Order management UI ├── admin.py # Admin panel ├── settings.py # User settings ├── apikey.py # API key management ├── playground.py # API testing playground ├── flow.py # Visual workflow builder ├── historify.py # Historical data UI ├── analyzer.py # Sandbox mode UI ├── sandbox.py # Sandbox API routes ├── pnltracker.py # P&L tracking ├── chartink.py # Chartink webhook ├── tv_json.py # TradingView webhook ├── gc_json.py # GoCharting webhook ├── telegram.py # Telegram bot integration ├── search.py # Symbol search UI ├── strategy.py # Strategy management ├── python_strategy.py # Python strategy execution ├── gex.py # GEX Dashboard analytics ├── ivchart.py # IV Chart analytics ├── ivsmile.py # IV Smile analytics ├── oiprofile.py # OI Profile analytics ├── oitracker.py # OI Tracker analytics ├── straddle_chart.py # Straddle Chart analytics ├── vol_surface.py # Volatility Surface analytics ├── health.py # Health monitoring ├── log.py # Log viewer ├── traffic.py # Traffic logs ├── latency.py # Latency monitor ├── security.py # Security settings ├── broker_credentials.py # Broker API credentials ├── master_contract_status.py # Contract download status ├── system_permissions.py # Permissions management ├── logging.py # Logging configuration ├── websocket_example.py # WebSocket demo page ├── platforms.py # Platform integrations └── react_app.py # React SPA serving ``` #### `/restx_api/` - REST API Endpoints Flask-RESTX namespaces for `/api/v1/` routes with Swagger documentation. ``` restx_api/ ├── __init__.py # API namespace registry ├── schemas.py # Common response schemas ├── data_schemas.py # Data model schemas ├── account_schema.py # Account schemas │ ├── place_order.py # POST /placeorder ├── place_smart_order.py # POST /placesmartorder ├── options_order.py # POST /optionsorder ├── options_multiorder.py # POST /optionsmultiorder ├── modify_order.py # POST /modifyorder ├── cancel_order.py # POST /cancelorder ├── cancel_all_order.py # POST /cancelallorder ├── close_position.py # POST /closeposition ├── basket_order.py # POST /basketorder ├── split_order.py # POST /splitorder │ ├── orderbook.py # GET /orderbook ├── orderstatus.py # GET /orderstatus ├── tradebook.py # GET /tradebook ├── positionbook.py # GET /positionbook ├── holdings.py # GET /holdings ├── openposition.py # GET /openposition ├── funds.py # GET /funds ├── margin.py # GET /margin │ ├── quotes.py # GET /quotes ├── multiquotes.py # GET /multiquotes ├── depth.py # GET /depth ├── history.py # GET /history ├── ticker.py # WebSocket ticker info │ ├── symbol.py # Symbol lookup ├── search.py # Symbol search ├── instruments.py # Instrument list ├── intervals.py # Timeframe intervals ├── expiry.py # Option expiry dates │ ├── option_chain.py # Option chain data ├── option_greeks.py # Option Greeks ├── multi_option_greeks.py # Batch Greeks ├── option_symbol.py # Option symbol builder ├── synthetic_future.py # Synthetic future price │ ├── market_holidays.py # Market holiday calendar ├── market_timings.py # Exchange timings ├── pnl_symbols.py # P&L by symbol ├── chart_api.py # Chart data │ ├── analyzer.py # Sandbox mode API ├── telegram_bot.py # Telegram integration └── ping.py # Health check endpoint ``` #### `/services/` - Business Logic Layer Core business logic separated from routes. ``` services/ ├── place_order_service.py # Order placement logic ├── place_smart_order_service.py # Smart order with position awareness ├── place_options_order_service.py # Options order handling ├── options_multiorder_service.py # Multi-leg options ├── modify_order_service.py # Order modification ├── cancel_order_service.py # Order cancellation ├── cancel_all_order_service.py # Bulk cancellation ├── close_position_service.py # Position closing ├── basket_order_service.py # Basket orders ├── split_order_service.py # Order splitting for large qty ├── order_router_service.py # Order routing logic ├── pending_order_execution_service.py # Pending order execution ├── action_center_service.py # Manual approval workflow │ ├── orderbook_service.py # Order book retrieval ├── orderstatus_service.py # Order status lookup ├── tradebook_service.py # Trade history ├── positionbook_service.py # Position data ├── holdings_service.py # Holdings data ├── openposition_service.py # Open positions ├── funds_service.py # Account funds ├── margin_service.py # Margin calculation │ ├── quotes_service.py # Real-time quotes ├── depth_service.py # Market depth ├── history_service.py # Historical OHLCV ├── market_data_service.py # Market data aggregation ├── chart_service.py # Charting data │ ├── symbol_service.py # Symbol resolution ├── search_service.py # Symbol search ├── instruments_service.py # Instrument data ├── intervals_service.py # Timeframe info ├── expiry_service.py # Expiry dates │ ├── option_chain_service.py # Option chain ├── option_greeks_service.py # Greeks calculation ├── option_symbol_service.py # Option symbol builder ├── synthetic_future_service.py # Synthetic futures ├── options_multiorder_service.py # Multi-leg options │ ├── gex_service.py # Gamma Exposure (GEX) analytics ├── iv_chart_service.py # IV Chart analytics ├── iv_smile_service.py # IV Smile analytics ├── oi_profile_service.py # OI Profile analytics ├── oi_tracker_service.py # OI Tracker analytics ├── straddle_chart_service.py # ATM Straddle Chart analytics ├── vol_surface_service.py # 3D Volatility Surface analytics │ ├── market_calendar_service.py # Trading calendar ├── historify_service.py # Historical data storage ├── historify_scheduler_service.py # Historify background jobs ├── analyzer_service.py # Sandbox mode ├── sandbox_service.py # Sandbox operations │ ├── telegram_alert_service.py # Telegram alerts ├── telegram_bot_service.py # Telegram bot commands │ ├── flow_executor_service.py # Flow execution engine ├── flow_scheduler_service.py # Scheduled flows ├── flow_price_monitor_service.py # Price-triggered flows ├── flow_openalgo_client.py # Flow API client │ ├── ping_service.py # Health check ├── websocket_service.py # WebSocket management └── websocket_client.py # WebSocket client ``` #### `/database/` - Database Models & Utilities SQLAlchemy models and database operations. ``` database/ ├── __init__.py ├── db_init_helper.py # Database initialization │ ├── auth_db.py # User, ApiKey, Token models ├── user_db.py # User CRUD operations ├── token_db.py # Token management ├── settings_db.py # User settings │ ├── sandbox_db.py # Sandbox mode models ├── analyzer_db.py # Analyzer database ├── action_center_db.py # Order approval workflow │ ├── strategy_db.py # Strategy storage ├── flow_db.py # Flow workflows ├── chartink_db.py # Chartink configurations ├── telegram_db.py # Telegram settings │ ├── symbol.py # Symbol helpers ├── tv_search.py # TradingView search ├── qty_freeze_db.py # Quantity freeze limits ├── market_calendar_db.py # Market calendar data ├── master_contract_status_db.py # Contract download status ├── master_contract_cache_hook.py # Contract caching ├── chart_prefs_db.py # Chart preferences │ ├── health_db.py # Health monitoring data ├── historify_db.py # Historical data (DuckDB) ├── apilog_db.py # API logs ├── latency_db.py # Latency metrics ├── traffic_db.py # Traffic logs ├── cache_restoration.py # Cache recovery ├── cache_invalidation.py # Cache invalidation ├── token_db_enhanced.py # Enhanced token features └── token_db_backup.py # Token backup utilities ``` #### `/utils/` - Shared Utilities Common utilities used across the application. ``` utils/ ├── __init__.py ├── config.py # Configuration loading ├── constants.py # Application constants ├── logging.py # Logging setup ├── session.py # Session management │ ├── auth_utils.py # Authentication helpers ├── security_middleware.py # Security middleware ├── ip_helper.py # IP address utilities │ ├── plugin_loader.py # Broker plugin discovery ├── api_analyzer.py # API analysis tools ├── httpx_client.py # HTTP client pooling │ ├── email_utils.py # Email sending ├── email_debug.py # Email debugging │ ├── latency_monitor.py # Latency tracking ├── traffic_logger.py # Traffic logging ├── number_formatter.py # Number formatting ├── mpp_slab.py # Margin slab calculations │ ├── health_monitor.py # System health monitoring ├── ngrok_manager.py # Ngrok tunnel management ├── env_check.py # Environment validation ├── version.py # Version information └── socketio_error_handler.py # SocketIO error handling ``` ### Broker Integration #### `/broker/` - Broker Plugins Each broker follows a standardized structure. ``` broker/ ├── __init__.py ├── zerodha/ # Reference implementation ├── dhan/ ├── angel/ ├── fyers/ ├── upstox/ ├── kotak/ ├── iifl/ ├── flattrade/ ├── shoonya/ ├── aliceblue/ ├── fivepaisa/ ├── fivepaisaxts/ ├── firstock/ ├── groww/ ├── samco/ ├── motilal/ ├── mstock/ ├── tradejini/ ├── wisdom/ ├── zebu/ ├── ibulls/ ├── compositedge/ ├── definedge/ ├── indmoney/ ├── jainamxts/ ├── nubra/ ├── paytm/ ├── pocketful/ └── dhan_sandbox/ # Dhan sandbox mode ``` #### Broker Module Structure Each broker implements the same interface: ``` broker/zerodha/ ├── plugin.json # Broker metadata ├── api/ │ ├── auth_api.py # OAuth/API authentication │ ├── order_api.py # Order operations │ ├── data.py # Market data │ └── funds.py # Account funds ├── mapping/ │ ├── order_data.py # Order format mapping │ ├── transform_data.py # Data transformation │ └── *.py # Additional mappings ├── database/ │ └── master_contract_db.py # Symbol master download └── streaming/ ├── adapter.py # WebSocket adapter └── *.py # Streaming utilities ``` ### Real-Time Infrastructure #### `/websocket_proxy/` - WebSocket Server Unified market data streaming server. ``` websocket_proxy/ ├── __init__.py ├── server.py # Main WebSocket server (port 8765) ├── connection_manager.py # Client connection handling ├── broker_factory.py # Broker adapter factory ├── base_adapter.py # Base WebSocket adapter ├── mapping.py # Symbol mapping utilities ├── port_check.py # Port availability check └── app_integration.py # Flask integration ``` #### `/sandbox/` - Sandbox Trading Engine Virtual trading environment for testing. ``` sandbox/ ├── __init__.py ├── execution_engine.py # Order execution simulator ├── websocket_execution_engine.py # WebSocket-based execution ├── execution_thread.py # Background execution thread ├── catch_up_processor.py # Catch-up order processing ├── order_manager.py # Order management ├── position_manager.py # Position tracking ├── fund_manager.py # Virtual fund management ├── holdings_manager.py # Holdings tracking ├── squareoff_manager.py # Square-off logic └── squareoff_thread.py # Background square-off thread ``` ### Frontend #### `/frontend/` - React 19 SPA Modern single-page application. ``` frontend/ ├── package.json # Dependencies ├── vite.config.ts # Vite build config ├── tsconfig.json # TypeScript config ├── biome.json # Linting/formatting ├── index.html # Entry HTML │ ├── src/ │ ├── main.tsx # Application entry │ ├── App.tsx # Router configuration │ ├── index.css # Global styles │ │ │ ├── api/ # API client modules │ │ ├── client.ts # Axios instance │ │ ├── auth.ts # Authentication API │ │ ├── admin.ts # Admin API │ │ ├── trading.ts # Trading API (orders, positions) │ │ ├── option-chain.ts # Option chain API │ │ ├── gex.ts # GEX analytics API │ │ ├── iv-chart.ts # IV Chart API │ │ ├── iv-smile.ts # IV Smile API │ │ ├── oi-profile.ts # OI Profile API │ │ ├── oi-tracker.ts # OI Tracker API │ │ ├── straddle-chart.ts # Straddle Chart API │ │ ├── vol-surface.ts # Volatility Surface API │ │ ├── health.ts # Health monitoring API │ │ ├── flow.ts # Flow editor API │ │ ├── strategy.ts # Strategy API │ │ ├── chartink.ts # Chartink API │ │ ├── python-strategy.ts # Python strategy API │ │ └── telegram.ts # Telegram API │ │ │ ├── components/ # Reusable components │ │ ├── ui/ # shadcn/ui components │ │ ├── layout/ # Layout components │ │ ├── auth/ # Auth components (AuthSync) │ │ ├── flow/ # Flow editor components │ │ ├── socket/ # Socket.IO components │ │ ├── trading/ # Trading components │ │ ├── option-chain/ # Option chain components │ │ └── playground/ # Playground components │ │ │ ├── pages/ # Route pages (60+) │ │ ├── Dashboard.tsx # Main dashboard │ │ ├── OrderBook.tsx # Order book │ │ ├── Positions.tsx # Positions │ │ ├── Tools.tsx # Analytics tools hub │ │ ├── GEXDashboard.tsx # Gamma Exposure dashboard │ │ ├── IVSmile.tsx # IV Smile chart │ │ ├── IVChart.tsx # IV Chart │ │ ├── OIProfile.tsx # OI Profile │ │ ├── OITracker.tsx # OI Tracker │ │ ├── MaxPain.tsx # Max Pain analysis │ │ ├── StraddleChart.tsx # ATM Straddle chart │ │ ├── VolSurface.tsx # 3D Volatility Surface │ │ ├── admin/ # Admin pages │ │ ├── chartink/ # Chartink pages │ │ ├── flow/ # Flow editor pages │ │ ├── monitoring/ # Monitoring dashboards │ │ ├── python-strategy/ # Python strategy pages │ │ ├── strategy/ # Strategy pages │ │ └── telegram/ # Telegram pages │ │ │ ├── hooks/ # Custom React hooks │ │ ├── useSocket.ts # Socket.IO hook │ │ ├── useLivePrice.ts # Live price feed │ │ ├── useLiveQuote.ts # Live quote feed │ │ ├── useMarketData.ts # Market data hook │ │ ├── useMarketStatus.ts # Market status │ │ ├── useOptionChainLive.ts # Live option chain │ │ └── useOrderEventRefresh.ts # Order event refresh │ │ │ ├── stores/ # Zustand stores │ │ ├── authStore.ts # Auth state │ │ ├── themeStore.ts # Theme state │ │ ├── alertStore.ts # Alert/toast state │ │ └── flowWorkflowStore.ts # Flow editor state │ │ │ ├── lib/ # Utility libraries │ │ ├── utils.ts │ │ ├── rateLimiter.ts # Client-side rate limiter │ │ ├── MarketDataManager.ts # Market data management │ │ └── flow/ # Flow editor utilities │ │ │ ├── types/ # TypeScript types │ │ ├── trading.ts # Trading types │ │ ├── option-chain.ts # Option chain types │ │ ├── plotly.d.ts # Plotly type declarations │ │ └── *.ts # Other type definitions │ │ │ ├── config/ # Configuration │ │ └── navigation.ts # Navigation config │ │ │ ├── app/ # App-level providers │ │ └── providers.tsx # React context providers │ │ │ └── test/ # Test utilities │ ├── dist/ # Production build output ├── e2e/ # Playwright E2E tests └── node_modules/ # Dependencies ``` ### Data & Storage #### `/db/` - Database Files ``` db/ ├── openalgo.db # Main database (users, orders, settings) ├── logs.db # API and traffic logs ├── latency.db # Latency metrics ├── sandbox.db # Sandbox trading data └── historify.duckdb # Historical market data (DuckDB) ``` ### Documentation #### `/docs/` - Documentation ``` docs/ ├── design/ # Developer design docs (this folder) │ ├── 00-directory-structure/ │ ├── 01-frontend/ │ ├── 02-backend/ │ └── ... (52 modules) │ ├── api/ # API documentation ├── audit/ # Broker API audit reports ├── prd/ # Product requirements docs ├── plans/ # Implementation plans ├── docker/ # Docker documentation ├── userguide/ # User guide ├── test/ # Test documentation ├── CHANGELOG.md # Version history └── *.md # Other docs ``` ### Testing #### `/test/` - Test Suites ``` test/ ├── conftest.py # Pytest fixtures ├── test_*.py # Backend tests └── *.py # Test utilities ``` ### Additional Directories | Directory | Purpose | | --------------- | -------------------------------- | | `/collections/` | Postman/Bruno API collections | | `/examples/` | Example integrations and scripts | | `/strategies/` | Strategy templates | | `/playground/` | API playground resources | | `/mcp/` | Model Context Protocol configs | | `/upgrade/` | Database migration scripts | | `/install/` | Installation helpers | | `/scripts/` | Utility scripts | | `/download/` | Downloaded resources | | `/data/` | Data files | | `/keys/` | SSL certificates (not in git) | | `/logs/` | Application logs (not in git) | | `/tmp/` | Temporary files (not in git) | ### Key File Reference | File | Purpose | | --------------------------------- | ------------------------------------------------ | | `app.py` | Main Flask entry point, registers all blueprints | | `extensions.py` | SocketIO, CORS initialization | | `frontend/src/App.tsx` | React router configuration | | `restx_api/__init__.py` | REST API namespace registry | | `broker/*/plugin.json` | Broker plugin metadata | | `websocket_proxy/server.py` | WebSocket server entry | | `sandbox/execution_engine.py` | Sandbox order execution | | `database/auth_db.py` | Core authentication models | | `services/place_order_service.py` | Order placement logic | ### Navigation Tips 1. **Finding a feature**: Start in `/blueprints/` for UI routes or `/restx_api/` for API endpoints 2. **Business logic**: Look in `/services/` for the corresponding service 3. **Database operations**: Check `/database/` for models and queries 4. **Broker-specific code**: Navigate to `/broker/{broker_name}/` 5. **Frontend components**: Explore `/frontend/src/components/` and `/frontend/src/pages/` 6. **Real-time features**: See `/websocket_proxy/` for market data streaming 7. **Sandbox mode**: Check `/sandbox/` for virtual trading logic --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.openalgo.in/developers/design-documentation/00-directory-structure.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.