boki/stock-bot
1
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions
stock-bot/CONTEXT.md

8.2 KiB
Raw Blame History

📋 Stock Bot Trading System - Architecture Context

🏗️ System Overview

A comprehensive, microservice-based trading bot system built with Bun, TypeScript, and Turborepo. The system features a service-oriented architecture designed for real-time market data processing, strategy execution, and risk management.

🎯 Current System Status

✅ Operational Services

  • Market Data Gateway (apps/core-services/market-data-gateway) - Port 3004

    • UNIFIED IMPLEMENTATION - Merged from duplicate services
    • Real-time market data ingestion and processing
    • WebSocket server for live data streaming (Port 3005)
    • REST API for market data queries and configuration
    • Mock data implementation for testing
    • Full TypeScript implementation with resolved compilation errors

  • Trading Dashboard (apps/interface-services/trading-dashboard) - Port 5173

    • React + TypeScript frontend with Tremor UI
    • Real-time data visualization
    • WebSocket client for live updates
    • Professional financial dashboard components

🚧 Ready for Implementation

  • Strategy Orchestrator (apps/intelligence-services/strategy-orchestrator) - Port 4001

    • Package structure created, implementation needed
    • Strategy execution and management
    • Signal generation coordination

  • Risk Guardian (apps/core-services/risk-guardian) - Port 3002

    • Package structure created, implementation needed
    • Real-time risk monitoring and alerts
    • Position and exposure limits

🏗️ Service Architecture

Service Categories

apps/
├── core-services/          # Essential trading infrastructure
│   ├── market-data-gateway/     ✅ Operational (UNIFIED)
│   └── risk-guardian/           📋 Ready to implement
├── intelligence-services/  # Strategy and signal generation
│   └── strategy-orchestrator/   📋 Ready to implement
├── interface-services/     # User interfaces and APIs
│   ├── trading-dashboard/       ✅ Operational
│   └── trading-dashboard-react/ 📋 Alternative implementation
├── data-services/          # Data processing and analytics
├── execution-services/     # Order management and execution
├── integration-services/   # External system integrations
└── platform-services/     # Infrastructure and monitoring

Shared Packages

packages/
├── shared-types/          # TypeScript type definitions
├── config/               # Configuration management
├── database/             # Database utilities (planned)
└── trading-core/         # Core trading logic (planned)

🔄 Communication Architecture

Event-Driven Core (Dragonfly)

  • Primary Event Bus: Dragonfly Redis-compatible streams
  • Event Types: Market data, trading signals, risk alerts, portfolio updates
  • Communication Pattern: Publish/Subscribe for loose coupling
  • Real-time Processing: Sub-millisecond event propagation

Data Flow Patterns

  1. Market Data Flow

    External APIs → Market Data Gateway → Dragonfly Events → Dashboard/Services

  2. Trading Signal Flow

    Market Data → Strategy Orchestrator → Signals → Risk Guardian → Execution

  3. Real-time Updates

    Services → WebSocket Server → Dashboard (Live UI Updates)

API Communication

  • REST APIs: Service-to-service and client-to-service communication
  • WebSocket: Real-time bidirectional communication
  • HTTP Health Checks: Service monitoring and discovery

🗄️ Data Infrastructure

Storage Systems

  • 🐉 Dragonfly (Port 6379): Redis-compatible event streaming and caching
  • 🐘 PostgreSQL (Port 5432): Operational data with trading schemas
  • 📊 QuestDB (Ports 9000/8812): Time-series market data and analytics
  • 🍃 MongoDB (Port 27017): Document storage for sentiment analysis and raw documents

Database Schemas

  • trading.* - Orders, positions, executions, accounts
  • strategy.* - Strategies, signals, performance metrics
  • risk.* - Risk limits, events, monitoring
  • audit.* - System events, health checks, configuration

MongoDB Collections

  • sentiment_analysis - Market sentiment scores and analysis
  • raw_documents - News articles, social media posts, research reports
  • market_events - Significant market events and their impact

Admin Interfaces

  • Redis Insight (Port 8001): Dragonfly management
  • PgAdmin (Port 8080): PostgreSQL administration
  • QuestDB Console (Port 9000): Time-series data management
  • Mongo Express (Port 8081): MongoDB document browser and editor

🛡️ Infrastructure & DevOps

Container Management

  • Docker Compose: Multi-service orchestration
  • Development Environment: npm run dev:full
  • Infrastructure Management: PowerShell scripts in scripts/docker.ps1

Monitoring Stack

  • Prometheus (Port 9090): Metrics collection
  • Grafana (Port 3000): Dashboards and alerting
  • Health Checks: Each service exposes /health endpoints

Development Workflow

# Start infrastructure
npm run infra:up

# Start admin tools  
npm run docker:admin

# Start development services
npm run dev:full

🌐 Port Allocation

Service Category Port Range Current Services
Core Services 3001-3099 Market Data Gateway (3001), Risk Guardian (3002)
Intelligence 4001-4099 Strategy Orchestrator (4001)
Data Services 5001-5099 (Future expansion)
Interface 5173, 8001+ Trading Dashboard (5173)
Infrastructure 6379, 5432, 9000+, 27017 Dragonfly, PostgreSQL, QuestDB, MongoDB

🎯 Implementation Roadmap

Phase 1 - Foundation ✅ Complete

  • Monorepo setup with Turborepo
  • Market Data Gateway with real-time streaming
  • Professional React dashboard with Tremor UI
  • Docker infrastructure with Dragonfly/PostgreSQL/QuestDB
  • WebSocket real-time communication

Phase 2 - Trading Logic 📋 Next Priority

  • Strategy Orchestrator implementation
  • Risk Guardian implementation
  • Event-driven strategy execution
  • Portfolio position tracking

Phase 3 - Advanced Features ⏳ Future

  • Execution Engine with broker integration
  • Advanced analytics and backtesting
  • Machine learning signal generation
  • Multi-broker support

🔧 Technology Stack

Backend Services

  • Runtime: Bun (fast JavaScript runtime)
  • Framework: Hono (lightweight web framework)
  • Language: TypeScript (type safety)
  • Events: Dragonfly Redis Streams
  • WebSocket: Native WebSocket implementation

Frontend

  • Framework: React with TypeScript
  • Build Tool: Vite (fast development)
  • UI Library: Tremor UI (financial components)
  • Styling: Modern CSS with responsive design

Infrastructure

  • Monorepo: Turborepo for build orchestration
  • Containers: Docker & Docker Compose
  • Databases: PostgreSQL, QuestDB, Dragonfly
  • Monitoring: Prometheus + Grafana

🔒 Security & Configuration

Environment Management

  • Environment-specific configurations
  • Secure credential management
  • Development vs production separation

Service Security

  • Inter-service authentication
  • API rate limiting
  • Database connection security
  • External API key management

🚀 Getting Started

  1. Prerequisites: Docker Desktop, Bun runtime
  2. Infrastructure: npm run infra:up
  3. Admin Tools: npm run docker:admin
  4. Development: npm run dev:full
  5. Access: Dashboard at http://localhost:5173

📁 Key Configuration Files

  • turbo.json - Monorepo build configuration
  • docker-compose.yml - Infrastructure orchestration
  • packages/config/ - Shared configuration management
  • database/postgres/init/ - Database schema definitions

Architecture Design Principles:

  • Microservices: Independent, scalable services
  • Event-Driven: Loose coupling via Dragonfly events
  • Type Safety: TypeScript across all services
  • Real-time: WebSocket and event streaming
  • Observability: Comprehensive monitoring and logging
  • Developer Experience: Fast development with hot reload