# 🚀 PRODUCTION DEPLOYMENT GUIDE

This guide covers deploying the Institutional Trader platform to production.

## Table of Contents

1. [Environment Configuration](#1-environment-configuration)
2. [Backend Deployment (Railway)](#2-backend-deployment-railway)
3. [Frontend Deployment (Vercel)](#3-frontend-deployment-vercel)
4. [Self-Hosting with Nginx](#4-self-hosting-with-nginx)
5. [Monitoring & Health Checks](#5-monitoring--health-checks)
6. [Security Checklist](#6-security-checklist)

---

## 1. Environment Configuration

### Backend Production `.env`

Create a `.env` file in the `backend` directory with the following variables:

```env
# Production Environment Variables
NODE_ENV=production
PORT=3000

# Supabase Configuration
SUPABASE_URL=your_production_supabase_url
SUPABASE_ANON_KEY=your_production_anon_key
SUPABASE_SERVICE_KEY=your_service_role_key

# Direct PostgreSQL Connection (optional, for heavy queries)
# Get this from: Supabase Dashboard > Settings > Database > Connection String (URI)
DATABASE_URL=postgresql://postgres:[password]@db.[project-ref].supabase.co:5432/postgres

# CORS Configuration
CORS_ORIGIN=https://your-frontend-domain.com

# Security
JWT_SECRET=your_super_secret_jwt_key_min_32_chars
RATE_LIMIT_WINDOW=15
RATE_LIMIT_MAX=100

# Error Tracking (optional)
SENTRY_DSN=your_sentry_dsn_here
```

### Frontend Production `.env`

Create a `.env.production` file in the `frontend` directory:

```env
VITE_API_URL=https://your-backend-domain.com
VITE_WS_URL=wss://your-backend-domain.com
VITE_SUPABASE_URL=your_supabase_url
VITE_SUPABASE_ANON_KEY=your_anon_key
```

---

## 2. Backend Deployment (Railway)

### Prerequisites

1. Install Railway CLI:
```bash
npm install -g railway
```

2. Login to Railway:
```bash
railway login
```

### Deployment Steps

1. Initialize Railway project:
```bash
cd backend
railway init
```

2. Link to existing project (if applicable):
```bash
railway link
```

3. Set environment variables:
```bash
railway variables set NODE_ENV=production
railway variables set PORT=3000
railway variables set SUPABASE_URL=your_url
railway variables set SUPABASE_ANON_KEY=your_anon_key
railway variables set SUPABASE_SERVICE_KEY=your_service_key
railway variables set CORS_ORIGIN=https://your-frontend-domain.com
railway variables set RATE_LIMIT_WINDOW=15
railway variables set RATE_LIMIT_MAX=100
railway variables set JWT_SECRET=your_jwt_secret_min_32_chars
```

Or set them via Railway Dashboard:
- Go to your project → Variables tab
- Add each variable individually

4. Deploy:
```bash
railway up
```

5. View logs:
```bash
railway logs
```

### Railway Configuration

The `railway.toml` file is already configured with:
- Build command: `npm install && npm run build`
- Start command: `npm start`
- Health check endpoint: `/health`
- Auto-restart on failure

---

## 3. Frontend Deployment (Vercel)

### Prerequisites

1. Install Vercel CLI:
```bash
npm install -g vercel
```

2. Login to Vercel:
```bash
vercel login
```

### Deployment Steps

1. Navigate to frontend directory:
```bash
cd frontend
```

2. Deploy to preview:
```bash
vercel
```

3. Deploy to production:
```bash
vercel --prod
```

4. Set environment variables in Vercel Dashboard:
   - Go to your project → Settings → Environment Variables
   - Add all `VITE_*` variables for Production environment

### Vercel Configuration

The `vercel.json` file is already configured for:
- Static build from `dist` directory
- SPA routing (all routes → `index.html`)
- Environment variables support

---

## 4. Self-Hosting with Nginx

### Prerequisites

- Ubuntu/Debian server with Nginx installed
- SSL certificate (Let's Encrypt recommended)
- Node.js installed on server

### Setup Steps

1. **Install dependencies on server:**
```bash
# Backend
cd backend
npm install --production

# Frontend
cd frontend
npm install
npm run build
```

2. **Set up systemd service for backend:**
```bash
sudo nano /etc/systemd/system/flow-api.service
```

Add:
```ini
[Unit]
Description=Flow Platform API
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/institutional_trader/backend
Environment=NODE_ENV=production
ExecStart=/usr/bin/node src/server.js
Restart=always

[Install]
WantedBy=multi-user.target
```

Enable and start:
```bash
sudo systemctl enable flow-api
sudo systemctl start flow-api
```

3. **Configure Nginx:**

Copy `nginx.conf.example` to `/etc/nginx/sites-available/your-domain` and update:
- Replace `yourdomain.com` with your domain
- Update SSL certificate paths
- Update root path for frontend
- Update proxy_pass URLs if needed

Enable site:
```bash
sudo ln -s /etc/nginx/sites-available/your-domain /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
```

4. **Set up SSL with Let's Encrypt:**
```bash
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com -d api.yourdomain.com
```

---

## 5. Monitoring & Health Checks

### Health Check Endpoint

The backend includes an enhanced health check at `/health`:

```bash
curl https://api.yourdomain.com/health
```

Response includes:
- Status (ok/degraded)
- Timestamp
- Uptime
- Database connection status
- Database latency

### Uptime Monitoring

Set up monitoring with:
- **UptimeRobot** (free): Monitor `/health` endpoint
- **Pingdom**: Full-page monitoring
- **Sentry**: Error tracking (configure `SENTRY_DSN`)

### Logs

**Railway:**
```bash
railway logs --tail
```

**Vercel:**
- View in Dashboard → Deployments → Logs

**Self-hosted:**
```bash
# Backend logs
sudo journalctl -u flow-api -f

# Nginx logs
sudo tail -f /var/log/nginx/access.log
sudo tail -f /var/log/nginx/error.log
```

---

## 6. Security Checklist

- [ ] All environment variables set in production
- [ ] `JWT_SECRET` is at least 32 characters and random
- [ ] `SUPABASE_SERVICE_KEY` is kept secret (never in frontend)
- [ ] CORS origin set to production frontend URL only
- [ ] Rate limiting enabled (default: 100 requests per 15 minutes)
- [ ] SSL/TLS certificates installed and valid
- [ ] Security headers configured (Helmet)
- [ ] Health check endpoint configured
- [ ] Error tracking configured (Sentry)
- [ ] Database connection pooling enabled
- [ ] Caching layer configured for performance
- [ ] `.env` files excluded from git (verify `.gitignore`)
- [ ] Production build optimized (check bundle sizes)

---

## Performance Optimizations

### Already Implemented

1. **Backend:**
   - Compression middleware (gzip)
   - Connection pooling (PostgreSQL)
   - Request caching (NodeCache)
   - Rate limiting

2. **Frontend:**
   - Code splitting (vendor chunks)
   - Asset optimization
   - Production build minification

### Additional Recommendations

1. **CDN:** Use Cloudflare or similar for static assets
2. **Database:** Enable connection pooling in Supabase
3. **Caching:** Consider Redis for distributed caching
4. **Monitoring:** Set up APM (Application Performance Monitoring)

---

## Troubleshooting

### Backend won't start

1. Check environment variables:
```bash
railway variables
```

2. Check logs:
```bash
railway logs
```

3. Verify database connection:
```bash
curl https://api.yourdomain.com/health
```

### Frontend build fails

1. Check environment variables are set
2. Verify API URLs are correct
3. Check build logs:
```bash
vercel logs [deployment-url]
```

### WebSocket connection fails

1. Verify `VITE_WS_URL` uses `wss://` (not `ws://`)
2. Check Nginx WebSocket configuration
3. Verify backend WebSocket route is accessible

---

## Support

For issues or questions:
1. Check logs first
2. Verify environment variables
3. Test health check endpoint
4. Review security checklist

Your platform is now production-ready! 🎉