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