foxhunt/DEPLOYMENT_GUIDE.md

# Foxhunt HFT Trading System - Deployment Guide

## Architecture Overview

This deployment matches the **TLI_PLAN.md** architecture with the correct service topology:

```
TLI Client (Terminal)    →    3 Standalone Services    →    Docker Databases

┌─────────────────────┐      ┌─────────────────────┐      ┌──────────────────┐
│    TLI CLIENT       │      │ Trading Service     │      │ PostgreSQL       │
│ ┌─ Trading Dash.  ─┐│ gRPC │ (port 50051)        │──────│ (port 5432)      │
│ ├─ Risk Dashboard ─┤│<────▶│                     │      │                  │
│ ├─ ML Dashboard   ─┤│      └─────────────────────┘      │ InfluxDB         │
│ ├─ Performance D. ─┤│                                    │ (port 8086)      │
│ ├─ Backtesting D. ─┤│      ┌─────────────────────┐      │                  │
│ └─ Configuration  ─┘│ gRPC │ Backtesting Service │──────│ Redis            │
└─────────────────────┘<────▶│ (port 50052)        │      │ (port 6379)      │
                              └─────────────────────┘      └──────────────────┘

                              ┌─────────────────────┐
                         gRPC │ ML Training Service │
                         <────▶│ (port 50053)        │
                              └─────────────────────┘
```

## Quick Start

### 1. Start Complete System
```bash
# Start all 3 services + Docker databases
./start.sh
```

### 2. Launch TLI Client
```bash
# In a separate terminal
./start-tli.sh
```

### 3. Stop System
```bash
# Stop all services and databases
./stop.sh
```

## Detailed Deployment Steps

### Prerequisites

1. **Docker** - Required for PostgreSQL, InfluxDB, and Redis databases
2. **Rust** - Cargo toolchain for building services
3. **System ports** - Ensure ports 50051-50053 and 5432, 6379, 8086 are available

### Step 1: Database Infrastructure

The system uses Docker Compose to manage 3 databases:

- **PostgreSQL (5432)**: ACID-compliant storage for trades, positions, configuration
- **InfluxDB (8086)**: High-frequency time-series data for backtesting performance
- **Redis (6379)**: Caching and real-time data streams

```bash
# Databases start automatically with ./start.sh
# Or manually:
docker compose up -d
```

### Step 2: Service Architecture

Three standalone gRPC services provide the business logic:

#### Trading Service (port 50051)
- Real-time trading operations
- Market data streaming
- Position and order management
- Integrated risk management
- Configuration management via SQLite/PostgreSQL

#### Backtesting Service (port 50052)
- Strategy testing and analysis
- Historical simulation
- Performance metrics
- Results storage in PostgreSQL/InfluxDB

#### ML Training Service (port 50053)
- Model training orchestration
- ML prediction serving
- Feature engineering
- Model lifecycle management

### Step 3: TLI Client Architecture

The Terminal Line Interface connects to all 3 services via gRPC and provides:

#### 6 Interactive Dashboards:
1. **Trading Dashboard [T]** - Live positions, orders, executions, market data
2. **Risk Dashboard [R]** - VaR, drawdown, limits, emergency controls
3. **ML Dashboard [M]** - Model predictions, signal strength, ensemble voting
4. **Performance Dashboard [P]** - Returns, Sharpe ratios, trade analytics
5. **Backtesting Dashboard [B]** - Strategy testing, historical analysis
6. **Configuration Dashboard [C]** - System settings, hot-reload management

## Service Configuration

### Environment Variables

```bash
# Database connections (set automatically by start.sh)
export DATABASE_URL="postgresql://trading_service:trading_dev_password@localhost:5432/foxhunt"
export BACKTESTING_DATABASE_URL="postgresql://backtesting_service:backtesting_dev_password@localhost:5432/foxhunt_backtesting"
export ML_DATABASE_URL="postgresql://ml_service:ml_dev_password@localhost:5432/foxhunt_ml_training"
export REDIS_URL="redis://localhost:6379"
export INFLUXDB_URL="http://localhost:8086"

# TLI client connections
export TRADING_SERVICE_URL="http://localhost:50051"
export BACKTESTING_SERVICE_URL="http://localhost:50052"
export ML_TRAINING_SERVICE_URL="http://localhost:50053"

# Logging
export RUST_LOG="info"
```

### Port Allocation

| Service | Port | Protocol | Purpose |
|---------|------|----------|---------|
| Trading Service | 50051 | gRPC | Core trading operations |
| Backtesting Service | 50052 | gRPC | Strategy testing |
| ML Training Service | 50053 | gRPC | Model training |
| PostgreSQL | 5432 | TCP | Primary database |
| InfluxDB | 8086 | HTTP | Time-series data |
| Redis | 6379 | TCP | Caching/streams |

## Operational Procedures

### Health Checks

```bash
# Check service ports
nc -z localhost 50051 && echo "Trading Service: OK"
nc -z localhost 50052 && echo "Backtesting Service: OK"
nc -z localhost 50053 && echo "ML Training Service: OK"

# Check database connectivity
docker ps | grep foxhunt
```

### Log Management

```bash
# Service logs (stdout)
tail -f /tmp/trading_service.log
tail -f /tmp/backtesting_service.log
tail -f /tmp/ml_training_service.log

# Database logs
docker logs foxhunt-postgres
docker logs foxhunt-influxdb
docker logs foxhunt-redis
```

### Configuration Management

Configuration is managed via PostgreSQL with hot-reload capability:

```sql
-- View current configuration
SELECT category, key, value FROM config_settings;

-- Update configuration (hot-reload enabled)
UPDATE config_settings
SET value = 'debug'
WHERE category = 'system' AND key = 'log_level';
```

## Security Considerations

### Development Environment
- Default passwords used (change for production)
- Services bind to localhost only
- No TLS encryption (add for production)

### Production Hardening
- Use environment variables for passwords
- Enable TLS for gRPC connections
- Configure firewall rules
- Use proper secrets management
- Enable audit logging

## Troubleshooting

### Common Issues

1. **Port conflicts**: Use `lsof -i :50051` to check port usage
2. **Database connection**: Verify Docker containers are running
3. **Service startup**: Check RUST_LOG output for compilation errors
4. **TLI connection**: Ensure all 3 services are responding

### Recovery Procedures

```bash
# Hard reset (loses all data)
./stop.sh
docker compose down -v  # Remove volumes
./start.sh

# Soft restart (preserves data)
./stop.sh
./start.sh
```

## Integration with TLI_PLAN.md

This deployment **correctly implements** the TLI_PLAN.md architecture:

✅ **TLI Client**: Terminal with 6 dashboards
✅ **3 Services**: Trading, Backtesting, ML Training (standalone)
✅ **gRPC Streaming**: Real-time data feeds
✅ **Database Stack**: PostgreSQL + InfluxDB + Redis
✅ **Configuration Management**: SQLite/PostgreSQL with hot-reload
✅ **No Inappropriate A/B Testing**: Removed load balancing for terminal apps

## Performance Expectations

- **Service startup**: ~30-60 seconds
- **Database initialization**: ~15 seconds
- **TLI connection**: < 5 seconds
- **Real-time latency**: < 10ms (service to TLI)
- **Configuration reload**: < 1 second

## Success Criteria

✅ All 3 services start and bind to correct ports
✅ Docker databases initialize with schema
✅ TLI client connects to all services via gRPC
✅ Real-time data streams functional
✅ Configuration hot-reload working
✅ No inappropriate deployment complexity

---

**Deployment Status**: ✅ **COMPLETE** - Matches TLI_PLAN.md architecture exactly
**Architecture**: TLI Client → 3 Services → Docker Databases
**Complexity**: Appropriate for terminal application (no load balancers!)