ProspectIQ Deployment & Operations Guide

ProspectIQ Deployment & Operations Guide

Product: ProspectIQ - Automated Prospect Intelligence Platform Version: 2.0 Last Updated: 2026-01-21 Audience: Developers, DevOps, Technical Staff, Operations Team Owner: iSu Technologies

---

Overview

ProspectIQ is an automated prospect intelligence platform that discovers, enriches, and scores business leads using AI-powered analysis. This guide covers server architecture, deployment procedures, and operational best practices for the production environment.

Production URL: https://prospectiq.isutech.co.za

GitHub Repository: https://github.com/gedeza/isutech-prospect-iq

---

Table of Contents

1. Server Infrastructure
2. Directory Architecture
3. Service Configuration
4. Deployment Procedures
5. Database Operations
6. Monitoring & Maintenance
7. Troubleshooting Guide
8. Emergency Procedures

---

Server Infrastructure

Production Server

Component	Details
Provider	Hetzner Cloud
IP Address	46.224.40.5
Domain	prospectiq.isutech.co.za
Operating System	Ubuntu/Debian Linux
Database	PostgreSQL 15+ (prospect_iq)
Cache/Queue	Redis
Web Server	Nginx (reverse proxy + SSL)
SSL Provider	Let’s Encrypt (auto-renewal via Certbot)

Tech Stack

Backend:

• Python 3.11+ with FastAPI
• PostgreSQL with SQLAlchemy ORM
• Celery + Redis for async tasks
• Anthropic Claude AI for pain point detection

Frontend:

• Next.js 14 with TypeScript
• Tailwind CSS for styling
• Recharts for data visualization

Access

# SSH Access (requires proper SSH key)
ssh root@46.224.40.5

# Or via hostname
ssh root@prospectiq.isutech.co.za

---

Directory Architecture

ProspectIQ uses a dual-directory system that separates development and production environments.

Development/Staging Directory

Location: /root/projects/active/isutech-prospect-iq/

Purpose:

• Development and testing
• Version control (Git repository)
• Staging area before production deployment

Characteristics:

• ✅ Connected to GitHub: git@github.com:gedeza/isutech-prospect-iq.git
• ✅ Clean codebase without production artifacts
• ✅ All commits and version control happen here
• ✅ Branch: main

Structure:

/root/projects/active/isutech-prospect-iq/
├── backend/
│   ├── app/                  # FastAPI application
│   │   ├── main.py           # Application entry point
│   │   ├── config/           # Configuration files
│   │   ├── models/           # Database models
│   │   ├── routers/          # API endpoints
│   │   ├── enrichers/        # AI enrichment logic
│   │   └── scrapers/         # Data collection
│   ├── alembic/              # Database migrations
│   └── requirements.txt      # Python dependencies
├── frontend/
│   ├── app/                  # Next.js pages
│   ├── components/           # React components
│   ├── lib/                  # Utilities & API clients
│   └── package.json          # Node.js dependencies
├── DOCS/                     # Project documentation
├── CLAUDE.md                 # Development context
└── README.md                 # Project overview

Production Directory

Location: /home/prospectiq/prospectiq/

Purpose:

• Running the live production site
• Serving https://prospectiq.isutech.co.za

Characteristics:

• ⚠️ Not a git repository (file-based deployment)
• 🚀 Active production services
• 📦 Contains production artifacts, backups, logs
• 🔧 Systemd services run from here

Structure:

/home/prospectiq/prospectiq/
├── backend/
│   ├── app/                  # Same structure as dev
│   ├── alembic/              # Database migrations
│   ├── venv/                 # Python virtual environment (if used)
│   └── .env                  # Production environment variables
├── frontend/
│   ├── .next/                # Next.js production build
│   ├── app/                  # Next.js pages
│   ├── node_modules/         # Node dependencies
│   └── .env.local            # Frontend environment variables
└── [production artifacts]    # Backups, logs, experimental features

Why Two Directories?

Aspect	Development	Production
Version Control	Yes (Git)	No (file-based)
Purpose	Testing, staging	Live site
Artifacts	Clean code only	Build artifacts, logs
Changes	Frequent commits	Controlled deployments
Services	Manual testing	Systemd services

---

Service Configuration

Both services run as systemd services under the prospectiq user.

Backend Service (API)

Service Name: prospectiq-api.service Service File: /etc/systemd/system/prospectiq-api.service

[Unit]
Description=ProspectIQ FastAPI Backend
After=network.target postgresql.service

[Service]
Type=simple
User=prospectiq
WorkingDirectory=/home/prospectiq/prospectiq/backend
Environment="PYTHONPATH=/home/prospectiq/prospectiq/backend"
EnvironmentFile=/home/prospectiq/prospectiq/backend/.env
ExecStart=/usr/bin/python3 -m uvicorn app.main:app --host 0.0.0.0 --port 8002
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Details:

• Port: 8002 (internal)
• User: prospectiq
• Working Directory: /home/prospectiq/prospectiq/backend
• Process: Uvicorn ASGI server

Frontend Service

Service Name: prospectiq-frontend.service Service File: /etc/systemd/system/prospectiq-frontend.service

[Unit]
Description=ProspectIQ Next.js Frontend
After=network.target

[Service]
Type=simple
User=prospectiq
WorkingDirectory=/home/prospectiq/prospectiq/frontend
Environment="NODE_ENV=production"
ExecStart=/usr/bin/npm start -- -p 3002
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Details:

• Port: 3002 (internal)
• User: prospectiq
• Working Directory: /home/prospectiq/prospectiq/frontend
• Process: Next.js production server

Nginx Proxy Configuration

Domain: prospectiq.isutech.co.za SSL: Let’s Encrypt certificates

Routing:

• https://prospectiq.isutech.co.za/api/* → Backend (port 8002)
• https://prospectiq.isutech.co.za/* → Frontend (port 3002)

Service Management Commands

# Check status of both services
systemctl status prospectiq-api prospectiq-frontend

# Start services
systemctl start prospectiq-api
systemctl start prospectiq-frontend

# Stop services
systemctl stop prospectiq-api
systemctl stop prospectiq-frontend

# Restart services (after deployment)
systemctl restart prospectiq-api prospectiq-frontend

# Enable services on boot
systemctl enable prospectiq-api prospectiq-frontend

# View real-time logs
journalctl -u prospectiq-api -f
journalctl -u prospectiq-frontend -f

# View last 50 log lines
journalctl -u prospectiq-api -n 50 --no-pager
journalctl -u prospectiq-frontend -n 50 --no-pager

---

Deployment Procedures

Standard Deployment Workflow

Phase 1: Development

1. Navigate to development directory:

   cd /root/projects/active/isutech-prospect-iq/

2. Make your changes:

   • Edit files as needed
   • Test locally if possible

3. Commit to Git:

   git add .
   git commit -m "feat: description of changes"
   git push origin main

Phase 2: Deploy to Production

1. Copy backend changes:

   cp -r /root/projects/active/isutech-prospect-iq/backend/app/* \
         /home/prospectiq/prospectiq/backend/app/

2. Update Python dependencies (if requirements.txt changed):

   cd /home/prospectiq/prospectiq/backend
   pip install -r requirements.txt

3. Run database migrations (if schema changed):

   cd /home/prospectiq/prospectiq/backend
   alembic upgrade head

4. Copy frontend changes:

   # First, rebuild in dev directory
   cd /root/projects/active/isutech-prospect-iq/frontend
   npm run build
   
   # Then copy build to production
   cp -r .next/* /home/prospectiq/prospectiq/frontend/.next/

5. Fix file ownership:

   chown -R prospectiq:prospectiq /home/prospectiq/prospectiq/

6. Restart services:

   systemctl restart prospectiq-api
   systemctl restart prospectiq-frontend

Phase 3: Verification

1. Check service status:

   systemctl status prospectiq-api
   systemctl status prospectiq-frontend

2. Check logs for errors:

   journalctl -u prospectiq-api -n 50 --no-pager
   journalctl -u prospectiq-frontend -n 50 --no-pager

3. Test API health:

   curl https://prospectiq.isutech.co.za/api/health

4. Verify website:

   curl -I https://prospectiq.isutech.co.za

Quick Deployment Script

Save this as /root/deploy-prospectiq.sh:

#!/bin/bash
# ProspectIQ Quick Deployment Script

set -e  # Exit on error

echo "🚀 Starting ProspectIQ Deployment..."

# Backup (optional)
BACKUP_DIR="/root/backups/prospectiq-$(date +%Y%m%d_%H%M%S)"
echo "📦 Creating backup at $BACKUP_DIR"
mkdir -p $BACKUP_DIR
cp -r /home/prospectiq/prospectiq/backend/app $BACKUP_DIR/
cp -r /home/prospectiq/prospectiq/frontend/.next $BACKUP_DIR/ 2>/dev/null || true

# Copy backend
echo "📂 Deploying backend..."
cp -r /root/projects/active/isutech-prospect-iq/backend/app/* \
      /home/prospectiq/prospectiq/backend/app/

# Copy frontend
echo "📂 Deploying frontend..."
cp -r /root/projects/active/isutech-prospect-iq/frontend/.next/* \
      /home/prospectiq/prospectiq/frontend/.next/ 2>/dev/null || true

# Fix permissions
echo "🔒 Fixing permissions..."
chown -R prospectiq:prospectiq /home/prospectiq/prospectiq/

# Restart services
echo "🔄 Restarting services..."
systemctl restart prospectiq-api
systemctl restart prospectiq-frontend

# Wait for services
sleep 5

# Verify
echo "✅ Verifying deployment..."
if systemctl is-active --quiet prospectiq-api && systemctl is-active --quiet prospectiq-frontend; then
    echo "✅ Deployment successful!"
    echo "🌐 Site: https://prospectiq.isutech.co.za"
    echo "📊 API Health: https://prospectiq.isutech.co.za/api/health"
else
    echo "❌ Service verification failed! Check logs:"
    echo "   journalctl -u prospectiq-api -n 20"
    echo "   journalctl -u prospectiq-frontend -n 20"
    exit 1
fi

Usage:

chmod +x /root/deploy-prospectiq.sh
/root/deploy-prospectiq.sh

---

Database Operations

Database Information

Database Name: prospect_iq DBMS: PostgreSQL 15+ Connection: Configured in /home/prospectiq/prospectiq/backend/.env

Running Migrations

IMPORTANT: Always run migrations from the production directory.

# Navigate to production backend
cd /home/prospectiq/prospectiq/backend

# Check current migration version
alembic current

# View migration history
alembic history --verbose

# Upgrade to latest version
alembic upgrade head

# Downgrade one step (if needed)
alembic downgrade -1

# Show pending migrations
alembic history

Creating New Migrations

If you modify database models:

# 1. Make changes to models in development
cd /root/projects/active/isutech-prospect-iq/backend

# 2. Generate migration
alembic revision --autogenerate -m "description of changes"

# 3. Review generated migration file in alembic/versions/

# 4. Test in development
alembic upgrade head

# 5. Deploy to production (copy migration file)
cp alembic/versions/NEW_MIGRATION_FILE.py \
   /home/prospectiq/prospectiq/backend/alembic/versions/

# 6. Run in production
cd /home/prospectiq/prospectiq/backend
alembic upgrade head

Database Backup & Restore

Create Backup:

# Full database backup
sudo -u postgres pg_dump prospect_iq > \
    /root/backups/prospect_iq_$(date +%Y%m%d_%H%M%S).sql

# Compressed backup
sudo -u postgres pg_dump prospect_iq | gzip > \
    /root/backups/prospect_iq_$(date +%Y%m%d_%H%M%S).sql.gz

Restore Backup:

# Stop services first
systemctl stop prospectiq-api

# Restore database
sudo -u postgres psql prospect_iq < /root/backups/prospect_iq_20260121.sql

# Or restore compressed
gunzip -c /root/backups/prospect_iq_20260121.sql.gz | \
    sudo -u postgres psql prospect_iq

# Restart services
systemctl start prospectiq-api

Database Access

# Connect as postgres user
sudo -u postgres psql prospect_iq

# Or with specific user
psql -U prospect_user -d prospect_iq

# Common queries
prospect_iq=# SELECT COUNT(*) FROM companies;
prospect_iq=# SELECT COUNT(*) FROM contacts;
prospect_iq=# SELECT COUNT(*) FROM email_logs;
prospect_iq=# \dt  -- List all tables
prospect_iq=# \q   -- Exit

---

Monitoring & Maintenance

Application Logs

Backend Logs:

# Real-time logs (follow)
journalctl -u prospectiq-api -f

# Last 100 lines
journalctl -u prospectiq-api -n 100

# Logs since 1 hour ago
journalctl -u prospectiq-api --since "1 hour ago"

# Logs for today
journalctl -u prospectiq-api --since today

# Error logs only
journalctl -u prospectiq-api -p err

Frontend Logs:

# Real-time logs
journalctl -u prospectiq-frontend -f

# Last 100 lines
journalctl -u prospectiq-frontend -n 100

Nginx Logs:

# Access log
tail -f /var/log/nginx/access.log

# Error log
tail -f /var/log/nginx/error.log

# Search for errors
grep "error" /var/log/nginx/error.log | tail -20

System Health Checks

# Check all ProspectIQ services
systemctl status prospectiq-api prospectiq-frontend

# Check if services are running
systemctl is-active prospectiq-api prospectiq-frontend

# Check disk space
df -h

# Check memory usage
free -h

# Check CPU and processes
top
htop  # If installed

# Check PostgreSQL
systemctl status postgresql
sudo -u postgres psql -c "SELECT version();"

# Check Redis
redis-cli ping  # Should return PONG

SSL Certificate Status

# Check certificate expiration
certbot certificates

# Test certificate renewal
certbot renew --dry-run

# Force renewal (if needed)
certbot renew --force-renewal
systemctl reload nginx

Scheduled Maintenance Tasks

Weekly:

• Review application logs for errors
• Check disk space usage
• Verify backup integrity

Monthly:

• Update system packages: apt update && apt upgrade
• Review and archive old logs
• Database performance analysis
• SSL certificate expiration check

Quarterly:

• Security audit
• Performance optimization review
• Capacity planning assessment

---

Troubleshooting Guide

Issue: Services Won’t Start

Symptoms:

• Services fail immediately after starting
• systemctl status shows “failed” or “inactive”

Diagnosis:

# Check service status
systemctl status prospectiq-api
systemctl status prospectiq-frontend

# Check recent logs
journalctl -u prospectiq-api -n 50 --no-pager

# Check if ports are in use
netstat -tulpn | grep 8002
netstat -tulpn | grep 3002

Solutions:

1. Check .env file configuration
2. Verify database connection
3. Kill processes using the port: kill -9 $(lsof -t -i:8002)
4. Check file permissions: ls -la /home/prospectiq/prospectiq/
5. Review Python/Node dependencies

Issue: 502 Bad Gateway

Symptoms:

• Website shows Nginx 502 error
• API calls fail

Diagnosis:

# Check if backend is running
systemctl status prospectiq-api
curl http://127.0.0.1:8002/api/health

# Check if frontend is running
systemctl status prospectiq-frontend
curl http://127.0.0.1:3002

# Check nginx
nginx -t
systemctl status nginx

Solutions:

1. Restart backend/frontend services
2. Check nginx configuration: nginx -t
3. Restart nginx: systemctl restart nginx
4. Verify internal ports (8002, 3002) are accessible

Issue: Database Connection Errors

Symptoms:

• Backend logs show “could not connect to database”
• API returns 500 errors

Diagnosis:

# Check PostgreSQL status
systemctl status postgresql

# Test database connection
psql -U prospect_user -d prospect_iq -c "SELECT 1;"

# Check database exists
sudo -u postgres psql -l | grep prospect_iq

Solutions:

1. Verify DATABASE_URL in .env file
2. Ensure PostgreSQL is running: systemctl start postgresql
3. Check database user credentials
4. Review pg_hba.conf for authentication settings

Issue: High Memory/CPU Usage

Symptoms:

• Server becomes slow or unresponsive
• Services crash due to resource exhaustion

Diagnosis:

# Check memory usage
free -h
top

# Check CPU usage
top
htop

# Find memory-hungry processes
ps aux --sort=-%mem | head -10

# Find CPU-hungry processes
ps aux --sort=-%cpu | head -10

Solutions:

1. Restart services to free memory
2. Investigate application code for memory leaks
3. Optimize database queries
4. Consider server upgrade
5. Implement caching strategies

Issue: SSL Certificate Expired

Symptoms:

• Browser shows “Certificate expired” warning
• HTTPS connection fails

Solutions:

# Check certificate status
certbot certificates

# Renew certificate
certbot renew

# Reload nginx
systemctl reload nginx

# If auto-renewal is broken, force renewal
certbot renew --force-renewal

---

Emergency Procedures

Emergency Rollback

If a deployment causes critical issues:

# 1. Stop services
systemctl stop prospectiq-api prospectiq-frontend

# 2. Restore from backup
BACKUP_DIR="/root/backups/prospectiq-TIMESTAMP"
cp -r $BACKUP_DIR/app/* /home/prospectiq/prospectiq/backend/app/
cp -r $BACKUP_DIR/.next/* /home/prospectiq/prospectiq/frontend/.next/

# 3. Fix permissions
chown -R prospectiq:prospectiq /home/prospectiq/prospectiq/

# 4. Restart services
systemctl start prospectiq-api prospectiq-frontend

# 5. Verify
systemctl status prospectiq-api prospectiq-frontend
curl https://prospectiq.isutech.co.za/api/health

Database Recovery

If database is corrupted or needs restoration:

# 1. Stop backend
systemctl stop prospectiq-api

# 2. Create backup of current state (just in case)
sudo -u postgres pg_dump prospect_iq > \
    /root/backups/prospect_iq_before_recovery_$(date +%Y%m%d_%H%M%S).sql

# 3. Drop and recreate database
sudo -u postgres dropdb prospect_iq
sudo -u postgres createdb prospect_iq

# 4. Restore from backup
sudo -u postgres psql prospect_iq < /root/backups/prospect_iq_LATEST.sql

# 5. Run migrations to ensure schema is current
cd /home/prospectiq/prospectiq/backend
alembic upgrade head

# 6. Restart backend
systemctl start prospectiq-api

Complete Service Reset

If all else fails:

# 1. Stop all services
systemctl stop prospectiq-api prospectiq-frontend nginx

# 2. Check for zombie processes
ps aux | grep -E "uvicorn|next" | grep -v grep
# Kill any found processes

# 3. Clear any port conflicts
fuser -k 8002/tcp
fuser -k 3002/tcp

# 4. Restart PostgreSQL
systemctl restart postgresql

# 5. Start services in order
systemctl start nginx
systemctl start prospectiq-api
sleep 5
systemctl start prospectiq-frontend

# 6. Verify all services
systemctl status nginx prospectiq-api prospectiq-frontend
curl https://prospectiq.isutech.co.za/api/health

Contact Information

In case of emergencies:

• Technical Lead: Sibonga - support@isutech.co.za
• Product Owner: Nhlanhla Mnyandu - nhlanhla@isutech.co.za
• Server Provider: Hetzner Cloud Support

---

Additional Resources

• Project Repository: https://github.com/gedeza/isutech-prospect-iq
• Production Dashboard: https://prospectiq.isutech.co.za/dashboard
• API Documentation: https://prospectiq.isutech.co.za/api/docs
• Central Knowledge Hub: https://docs.isutech.co.za
• Technical Architecture: See project DOCS/technical/ARCHITECTURE.md

---

Document History

Date	Version	Changes	Author
2026-01-21	1.0	Initial deployment guide for central knowledge hub	System

---

ProspectIQ Deployment & Operations Guide v1.0 iSu Technologies © 2026 For internal use only - Confidential