stock-bot/CONTEXT.md

📋 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 3001

  • Real-time market data ingestion from multiple sources
  • WebSocket server for live data streaming
  • REST API for market data queries
  • Event publishing to Dragonfly streams

• 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
│   └── 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