Architecture

System Architecture

The Octopus Trading Platform is built on a modern, scalable microservices architecture designed for high-performance financial data processing.

Architecture Overview

graph TB
    subgraph CLIENT["CLIENT LAYER"]
        WA["Web App<br/>(Next.js)"]
        MA["Mobile App<br/>(React Native)"]
        AC["API Client<br/>(Python/JS/Go)"]
        WS["WebSocket<br/>Client"]
    end
    
    subgraph GATEWAY["API GATEWAY LAYER"]
        NGINX["NGINX / Kong API Gateway<br/>• Load Balancing<br/>• Rate Limiting<br/>• SSL Termination<br/>• Auth"]
    end
    
    subgraph APP["APPLICATION LAYER"]
        subgraph FASTAPI["FastAPI Backend"]
            MD["Market Data API"]
            PA["Portfolio API"]
            RA["Risk API"]
            AI["AI Models"]
            TA["Trading API"]
            WM["WebSocket Manager"]
            AS["Auth Service"]
            AN["Analytics Service"]
        end
    end
    
    subgraph INTEL["INTELLIGENCE LAYER"]
        subgraph ORCH["Intelligence Orchestrator (11 AI Agents)"]
            M1["M1<br/>Data Coll."]
            M2["M2<br/>Data Ware."]
            M3["M3<br/>Real-time"]
            M4["M4<br/>Strategy"]
            M5["M5<br/>ML Model"]
            M6["M6<br/>Risk Mgr"]
            M7["M7<br/>Exec. Mgr"]
            M8["M8<br/>Port. Opt."]
            M9["M9<br/>Compliance"]
            M10["M10<br/>Backtest"]
            M11["M11<br/>Alt. Data"]
        end
    end
    
    subgraph DATA["DATA LAYER"]
        PG["PostgreSQL<br/>TimescaleDB<br/>• Market Data<br/>• Users<br/>• Portfolios"]
        RD["Redis<br/>Cache<br/>• Sessions<br/>• Cache<br/>• Pub/Sub"]
        KF["Kafka<br/>Streaming<br/>• Events<br/>• Messages<br/>• Real-time"]
    end
    
    WA --> NGINX
    MA --> NGINX
    AC --> NGINX
    WS --> NGINX
    
    NGINX --> FASTAPI
    
    FASTAPI --> INTEL
    
    INTEL --> DATA
    
    style CLIENT fill:#e1f5ff
    style GATEWAY fill:#fff4e1
    style APP fill:#e8f5e9
    style INTEL fill:#f3e5f5
    style DATA fill:#fce4ec

Loading

---

Component Details

1. Client Layer

Component	Technology	Purpose
Web App	Next.js 14	Primary trading interface
Mobile App	React Native	Mobile trading (planned)
API Clients	Python/JS/Go SDKs	Programmatic access
WebSocket	Native WS	Real-time data streaming

2. API Gateway Layer

• Rate Limiting: Request throttling per user/IP
• Authentication: JWT token validation
• Kong/APISIX: API management and rate limiting
• NGINX: Load balancing and SSL termination

3. Application Layer (FastAPI)

src/
├── api/
│   ├── endpoints/
│   │   ├── agents.py          # AI agent monitoring
│   │   ├── auth.py            # Authentication
│   │   ├── backtesting.py    # Strategy backtesting
│   │   ├── market_data.py     # Market data endpoints
│   │   ├── portfolio_api.py  # Portfolio management
│   │   ├── risk.py            # Risk analysis
│   │   ├── trading.py         # Trading operations
│   │   └── websocket.py       # WebSocket endpoints
│   └── routes/
│       └── ...                # Route definitions
├── core/
│   ├── config.py              # Configuration management
│   ├── cache.py               # Redis cache manager
│   ├── celery_app.py          # Celery configuration
│   └── security.py            # Security utilities
└── main_refactored.py         # FastAPI application

4. Intelligence Layer

See AI Agents for detailed documentation on the 11 AI agents.

5. Data Layer

Database	Purpose	Features
PostgreSQL	Primary storage	ACID compliance, relations
TimescaleDB	Time-series	Hypertables, compression
Redis	Caching	Sub-millisecond latency
Kafka	Streaming	Event-driven architecture

---

Data Flow Patterns

Market Data Pipeline

graph LR
    EXT["External APIs"] --> M1["Data Collector<br/>(M1)"]
    M1 --> M2["Data Warehouse<br/>(M2)"]
    M2 --> M3["Real-time Processor<br/>(M3)"]
    
    M1 --> CACHE["Cache/Storage"]
    M2 --> HIST["Historical Analysis"]
    M3 --> STREAM["Live Streaming"]
    
    HIST --> M5["ML Models<br/>(M5)"]
    STREAM --> M4["Strategy Agent<br/>(M4)"]
    STREAM --> WS["WebSocket Clients"]
    
    style EXT fill:#e1f5ff
    style M1 fill:#fff4e1
    style M2 fill:#fff4e1
    style M3 fill:#fff4e1
    style M4 fill:#e8f5e9
    style M5 fill:#e8f5e9

Loading

Trading Decision Flow

graph TD
    MD["Market Data"] --> SA["Strategy Agent<br/>(M4)"]
    SA --> SF["Signal Fusion"]
    SF --> RM["Risk Manager<br/>(M6)"]
    RM --> EX["Execution<br/>(M7)"]
    
    SA --> TA["Technical<br/>Analysis"]
    SA --> FA["Fundamental<br/>Analysis"]
    SA --> MS["Multi-Strategy<br/>Signals"]
    
    RM --> PS["Position<br/>Sizing"]
    EX --> OR["Order<br/>Routing"]
    
    style MD fill:#e1f5ff
    style SA fill:#fff4e1
    style RM fill:#ffebee
    style EX fill:#e8f5e9

Loading

Real-time Communication

graph TD
    MU["Market Updates"] --> REDIS["Redis Pub/Sub"]
    REDIS --> WM["WebSocket Manager"]
    WM --> CC["Connected Clients"]
    
    REDIS --> CW["Celery Workers"]
    CW --> BP["Background<br/>Processing"]
    
    style MU fill:#e1f5ff
    style REDIS fill:#ffebee
    style WM fill:#fff4e1
    style CC fill:#e8f5e9

Loading

---

Scalability Design

Horizontal Scaling

graph TB
    LB["Load Balancer"] --> API1["API-1"]
    LB --> API2["API-2"]
    LB --> API3["API-3"]
    
    API1 --> DB["Database<br/>(Primary)"]
    API2 --> DB
    API3 --> DB
    
    DB --> REP1["Replica 1"]
    DB --> REP2["Replica 2"]
    DB --> REP3["Replica 3"]
    
    style LB fill:#e1f5ff
    style API1 fill:#fff4e1
    style API2 fill:#fff4e1
    style API3 fill:#fff4e1
    style DB fill:#e8f5e9
    style REP1 fill:#f3e5f5
    style REP2 fill:#f3e5f5
    style REP3 fill:#f3e5f5

Loading

Caching Strategy

graph TD
    REQ["Request"] --> CHECK{"Check Redis<br/>Cache"}
    CHECK -->|Hit| RETURN["Return Cached"]
    CHECK -->|Miss| QUERY["Query Database"]
    QUERY --> UPDATE["Update Cache"]
    UPDATE --> RETURN
    
    style REQ fill:#e1f5ff
    style CHECK fill:#fff4e1
    style RETURN fill:#e8f5e9
    style QUERY fill:#ffebee
    style UPDATE fill:#f3e5f5

Loading

---

Security Architecture

Authentication Flow

graph LR
    CLIENT["Client"] --> GATEWAY["API Gateway"]
    GATEWAY --> JWT["JWT Validation"]
    JWT --> FASTAPI["FastAPI"]
    FASTAPI --> RESOURCE["Protected Resource"]
    
    GATEWAY --> RATE["Rate Limit<br/>Check"]
    GATEWAY --> IP["IP Whitelist<br/>Check"]
    
    style CLIENT fill:#e1f5ff
    style GATEWAY fill:#fff4e1
    style JWT fill:#ffebee
    style FASTAPI fill:#e8f5e9
    style RESOURCE fill:#f3e5f5

Loading

Security Layers

Layer	Protection
Network	Firewall, DDoS protection
Transport	TLS 1.3, HSTS
Application	JWT, OAuth2, rate limiting
Data	Encryption at rest, RLS

---

Monitoring Stack

graph TB
    APP["Applications"] --> PROM["Prometheus<br/>(Metrics)"]
    PROM --> GRAF["Grafana<br/>(Dashboards)"]
    GRAF --> ALERT["Alertmanager<br/>(Alerts)"]
    
    APP --> LOGS["Structured Logs"]
    LOGS --> ELK["ELK Stack"]
    ELK --> KIB["Kibana"]
    
    ALERT --> PAGER["PagerDuty/Slack"]
    
    style APP fill:#e1f5ff
    style PROM fill:#fff4e1
    style GRAF fill:#e8f5e9
    style ALERT fill:#ffebee
    style ELK fill:#f3e5f5

Loading

Key Metrics

• Celery task queue length
• WebSocket connections
• Cache hit/miss ratio
• Database connection pool
• Error rates by endpoint
• Request latency (p50, p95, p99)

---

Next Steps

• Deployment - Production deployment guide
• Database - Database schema details
• API Reference - Complete API documentation
• AI Agents - Deep dive into the 11 AI agents

---

Octopus Trading Platform | GitHub | Report Issue | MIT License