# Quick Start Guide

Get the hybrid Node.js + Python architecture running in 5 minutes.

## Prerequisites

- Node.js 18+ installed
- Python 3.11+ installed
- PostgreSQL database running
- Database credentials configured

## Step 1: Install Dependencies

### Python Service
```bash
cd backend/python_service
python -m venv venv

# Activate virtual environment
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

pip install -r requirements.txt
```

### Node.js Backend
```bash
cd backend
npm install
```

## Step 2: Configure Environment

### Python Service
Create `backend/python_service/.env`:
```env
USE_LOCAL_DB=true
LOCAL_DB_HOST=localhost
LOCAL_DB_PORT=5432
LOCAL_DB_USER=postgres
LOCAL_DB_PASSWORD=your_password
LOCAL_DB_NAME=institutional_trader
```

### Node.js Backend
Add to `backend/.env`:
```env
PYTHON_SERVICE_URL=http://localhost:8010
USE_PYTHON_SERVICE=true

# Your existing database config...
```

## Step 3: Start Services

### Terminal 1: Python Service
```bash
cd backend/python_service
source venv/bin/activate  # or venv\Scripts\activate on Windows
uvicorn main:app --reload --port 8010
```

You should see:
```
INFO:     Uvicorn running on http://0.0.0.0:8010
INFO:     Application startup complete.
```

### Terminal 2: Node.js Backend
```bash
cd backend
npm run dev
```

You should see:
```
🚀 Server running on http://localhost:3010
🐍 Starting Python service health checks...
✅ Python service is healthy
```

## Step 4: Test Integration

### Test Health Endpoint
```bash
curl http://localhost:3010/health
```

Expected response:
```json
{
  "status": "ok",
  "database": { "status": "connected" },
  "pythonService": { "available": true, "status": "healthy" }
}
```

### Test Options Flow
```bash
curl "http://localhost:3010/api/options/flow?startDate=2024-01-01&endDate=2024-01-02"
```

Check Node.js logs - you should see:
```
✅ Using Python service: 150 rows
```

## Step 5: Verify Fallback

Stop the Python service (Ctrl+C in Terminal 1), then test again:

```bash
curl "http://localhost:3010/api/options/flow?startDate=2024-01-01&endDate=2024-01-02"
```

Check Node.js logs - you should see:
```
⚠️ Python service unavailable, falling back to SQL
📊 Using SQL query (fallback or Python disabled)
```

## Troubleshooting

### Python Service Won't Start
- Check database credentials in `.env`
- Verify PostgreSQL is running
- Check port 8010 is available
- Review Python service logs

### Node.js Can't Connect
- Verify `PYTHON_SERVICE_URL` in `.env`
- Check Python service is running
- Test: `curl http://localhost:8010/health`

### No Data Returned
- Check database has data
- Verify date range has data
- Review database connection
- Check service logs

## Next Steps

1. ✅ Services running
2. Run validation: `cd backend/python_service && python scripts/validate_against_sql.py`
3. Review `INTEGRATION_COMPLETE.md` for full documentation
4. Check `TESTING.md` for testing guide

## Production Deployment

For production:
- Use process managers (PM2, systemd)
- Set up proper logging
- Configure monitoring
- Use environment-specific configs
- Set up health check alerts

See `INTEGRATION_COMPLETE.md` for deployment details.