229 lines
8.2 KiB
Markdown
229 lines
8.2 KiB
Markdown
# 📋 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**
|
|
```bash
|
|
# 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
|
|
- [x] Monorepo setup with Turborepo
|
|
- [x] Market Data Gateway with real-time streaming
|
|
- [x] Professional React dashboard with Tremor UI
|
|
- [x] Docker infrastructure with Dragonfly/PostgreSQL/QuestDB
|
|
- [x] 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
|