institutional-trader/README/QUICK_START.md

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

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

cd backend
npm install

Step 2: Configure Environment

Python Service

Create backend/python_service/.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:

PYTHON_SERVICE_URL=http://localhost:8010
USE_PYTHON_SERVICE=true

# Your existing database config...

Step 3: Start Services

Terminal 1: Python Service

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

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

curl http://localhost:3010/health

Expected response:

{
  "status": "ok",
  "database": { "status": "connected" },
  "pythonService": { "available": true, "status": "healthy" }
}

Test Options Flow

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:

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.