Documentation

PQAP system documentation and architecture

PQAP Environment Configuration

This document describes the three PQAP environments and how to run, deploy, and manage each.

Environment Overview

Environment URL Purpose Trading Mode Capital
dev http://localhost:8080 Local development and testing Paper $100
staging https://staging.pqap.tailwindtech.ai Pre-production validation Paper $1,000
prod https://pqap.tailwindtech.ai Live trading Real $5,000

Environment Comparison

Configuration Differences

Setting dev staging prod
debug true true false
initial_capital $100 $1,000 $5,000
max_capital_per_market $5,000 $500 $500
max_capital_per_strategy $2,000 $400 $2,000
daily_loss_limit $500 $100 $250
max_drawdown_pct 10% 10% 10%
Strategies enabled 3 5 3
Private key None None Required

Database Locations

Environment Database File Location
dev pqap_dev.db data/pqap_dev.db (local)
staging pqap_staging.db data/pqap_staging.db or Docker volume
prod pqap.db /app/data/pqap.db (EC2/Docker)

Development Environment (dev)

Purpose

  • Local code development and testing
  • Quick iteration on new features
  • Debugging and troubleshooting

Configuration

  • Config file: configs/dev.yaml
  • URL: http://localhost:8080
  • Database: data/pqap_dev.db
  • Trading mode: Paper only (no private key)

Running Locally (Native Python)

# 1. Activate virtual environment
source venv/bin/activate

# 2. Start PQAP
python -m src.main configs/dev.yaml

# 3. Access dashboard
open http://localhost:8080

Running Locally (Docker)

# From the deploy/ directory
cd deploy

# Start dev environment
docker compose --profile dev up

# Or build and run
docker compose --profile dev up --build

# Stop
docker compose --profile dev down

Environment Variables

Create .env in the project root:

# .env (development)
PQAP_ENV=dev
PQAP_DEBUG=true

# Polymarket API (optional for dev - paper trading works without)
POLYMARKET_API_KEY=
POLYMARKET_API_SECRET=
# NO POLYMARKET_PRIVATE_KEY - paper trading only

# Telegram (optional for dev)
TELEGRAM_BOT_TOKEN=
TELEGRAM_CHAT_ID=

Staging Environment (staging)

Purpose

  • Pre-production validation
  • Testing all strategies together
  • Configuration verification before prod deployment
  • Training and demos

Configuration

  • Config file: configs/staging.yaml
  • URL: https://staging.pqap.tailwindtech.ai
  • Database: data/pqap_staging.db
  • Trading mode: Paper only (no private key)

Running Locally

# Start with staging config
python -m src.main configs/staging.yaml

# Access dashboard (same port, different config)
open http://localhost:8080

Deploying to Server (Docker)

# From the deploy/ directory
cd deploy

# Start staging environment
docker compose --profile staging up -d

# View logs
docker compose --profile staging logs -f

# Stop staging
docker compose --profile staging down

Running on EC2 (Alongside Production)

# SSH to EC2
ssh tailwindtech-ec2

# Run staging on different port
python -m src.main configs/staging.yaml --port 8081

# Or with Docker on port 8081
docker compose --profile staging up -d
# Staging accessible at https://staging.pqap.tailwindtech.ai

Environment Variables

Create .env.staging:

# .env.staging
PQAP_ENV=staging
PQAP_DEBUG=true

# Polymarket API (required for live data)
POLYMARKET_API_KEY=your_api_key
POLYMARKET_API_SECRET=your_api_secret
# NO POLYMARKET_PRIVATE_KEY - paper trading only

# Telegram (optional - use staging bot or same as prod)
TELEGRAM_BOT_TOKEN=your_staging_bot_token
TELEGRAM_CHAT_ID=your_chat_id

# Slack (optional)
SLACK_WEBHOOK_URL=

Staging Validation Checklist

Before promoting to production:

  • [ ] All enabled strategies initialize without errors
  • [ ] Signals are being generated appropriately
  • [ ] Risk limits are enforced correctly
  • [ ] No memory leaks over 24+ hour run
  • [ ] Telegram alerts working (if configured)
  • [ ] Dashboard displays correct data
  • [ ] Paper trades execute at expected frequency
  • [ ] No ERROR level log entries

Production Environment (prod)

Purpose

  • Live trading with real capital
  • 24/7 operation
  • Revenue generation

Configuration

  • Config file: configs/prod.yaml
  • URL: https://pqap.tailwindtech.ai
  • Database: /app/data/pqap.db
  • Trading mode: Real (private key required)

Deploying to Production

# From local machine
# 1. Sync code to EC2
python scripts/pqap_manager.py sync

# 2. Deploy (includes dependency update)
python scripts/pqap_manager.py deploy ec2

# 3. Start production
python scripts/pqap_manager.py start ec2

# 4. Monitor logs
python scripts/pqap_manager.py logs ec2

Option 2: Using Docker Compose

# On EC2
cd ~/pqap/deploy

# Start production
docker compose --profile prod up -d

# View logs
docker compose --profile prod logs -f pqap-prod

# Stop production
docker compose --profile prod down

Option 3: Using systemd

# On EC2
sudo systemctl start pqap
sudo systemctl status pqap

# Enable auto-start
sudo systemctl enable pqap

Environment Variables

Create .env on EC2 (~/pqap/.env):

# .env (production)
PQAP_ENV=prod
PQAP_DEBUG=false

# Polymarket API (REQUIRED)
POLYMARKET_API_KEY=your_production_api_key
POLYMARKET_API_SECRET=your_production_api_secret
POLYMARKET_PRIVATE_KEY=your_wallet_private_key  # REQUIRED for real trading

# Telegram (RECOMMENDED)
TELEGRAM_BOT_TOKEN=your_production_bot_token
TELEGRAM_CHAT_ID=your_chat_id

# Slack (optional)
SLACK_WEBHOOK_URL=your_webhook_url

Production Checklist

Before going live:

  • [ ] Staging validation completed successfully
  • [ ] All environment variables configured
  • [ ] Private key securely stored
  • [ ] Backup scripts configured and tested
  • [ ] Monitoring and alerts configured
  • [ ] Rollback procedure documented and tested

Environment Variables Reference

Required Variables

Variable dev staging prod Description
PQAP_ENV dev staging prod Environment identifier
POLYMARKET_API_KEY Optional Required Required Polymarket API key
POLYMARKET_API_SECRET Optional Required Required Polymarket API secret
POLYMARKET_PRIVATE_KEY No No Required Wallet private key (real trading)

Optional Variables

Variable Description
PQAP_DEBUG Enable debug logging (default: from config)
PQAP_DB_PATH Override database path
PQAP_CONFIG_FILE Override config file path
TELEGRAM_BOT_TOKEN Telegram bot token for alerts
TELEGRAM_CHAT_ID Telegram chat ID for alerts
SLACK_WEBHOOK_URL Slack webhook for alerts

Promotion Workflow

dev -> staging

# 1. Test locally with dev config
python -m src.main configs/dev.yaml

# 2. Run with staging config to validate
python -m src.main configs/staging.yaml

# 3. Deploy to staging server
cd deploy && docker compose --profile staging up -d

staging -> prod

# 1. Verify staging has run successfully for 24-48 hours
python scripts/pqap_manager.py status

# 2. Review staging logs for errors
ssh tailwindtech-ec2 'grep ERROR ~/pqap/pqap.log'

# 3. Sync code to production
python scripts/pqap_manager.py sync

# 4. Stop production (brief downtime)
python scripts/pqap_manager.py stop ec2

# 5. Start production with new code
python scripts/pqap_manager.py start ec2

# 6. Monitor startup
python scripts/pqap_manager.py logs ec2

# 7. Verify health
curl https://pqap.tailwindtech.ai/health

Rollback Procedures

Quick Rollback (Git)

# Find last working commit
git log --oneline -10

# Checkout previous version
git checkout <commit-hash>

# Sync to production
python scripts/pqap_manager.py sync
python scripts/pqap_manager.py stop ec2
python scripts/pqap_manager.py start ec2

Database Rollback

# On EC2
pqap-ctl stop
~/pqap/scripts/restore_from_s3.sh
pqap-ctl start

Troubleshooting

Environment Detection Issues

If the wrong environment is being used:

# Check which config is loaded
curl http://localhost:8080/api/status | jq '.environment'

# Verify environment variable
echo $PQAP_ENV

# Check config file being used
ps aux | grep pqap

Database Conflicts

Each environment should use a separate database:

# Verify database files
ls -la data/*.db

# Expected:
# data/pqap_dev.db     - Development
# data/pqap_staging.db - Staging
# data/pqap.db         - Production (on EC2)

Port Conflicts

Default ports: - dev: 8080 (localhost) - staging: 8081 (or 8080 if running alone) - prod: 8080 (behind Traefik proxy)

# Check what's using a port
lsof -i :8080

# Kill process on port
kill -9 $(lsof -t -i:8080)

Files Reference

File Purpose
configs/dev.yaml Development configuration
configs/staging.yaml Staging configuration
configs/prod.yaml Production configuration
.env Environment variables (local)
.env.staging Staging environment variables
.env.example Template for .env files
deploy/docker-compose.yml Docker Compose for all environments
deploy/Dockerfile Docker image build

System Overview

Polymarket API

Market data source

↓

Data Collector

Every 5 minutes

↓

SQLite Database

Price history + trades

↓

Strategy Engine

Signal generation

ML Model

XGBoost (72% acc)

↓

Execution Engine

Paper trading

↓

Dashboard

You are here!

Telegram

Alerts & updates

Trading Strategies

Each strategy looks for different market inefficiencies:

Dual Arbitrage Active

Finds when YES + NO prices don't add to 100%. Risk-free profit.

Mean Reversion Active

Buys when price drops too far from average, sells when it recovers.

Market Maker Active

Places bid/ask orders to capture the spread.

Time Arbitrage Active

Exploits predictable price patterns at certain hours.

ML Prediction Active

Uses machine learning to predict 6-hour price direction.

Value Betting Disabled

Finds underpriced outcomes based on implied probability.

Data Storage (Single Source of Truth)

All data lives on EC2. Local machines are for development only. The EC2 instance is the authoritative source for all market data, trades, and positions.
Database Purpose Location
market_history.db Price snapshots every 5 minutes (8.2 MB) EC2 (primary)
pqap_staging.db Trades, positions, P&L history EC2 (primary)
paper_trading_state.json Current portfolio state EC2 (primary)

Environment Architecture

EC2 (Production)

  • Runs 24/7
  • All databases live here
  • Executes all trades
  • Single source of truth

Local (Development)

  • For code changes only
  • Syncs code to EC2
  • No production data
  • Can be turned off

Environment Details

Component Details
Dashboard URL https://pqap.tailwindtech.ai
Server AWS EC2 (us-east-1)
SSL Let's Encrypt via Traefik
Mode Paper Trading (simulated)

How It Works (Simple Version)

1. Data Collection: Every 5 minutes, we fetch prices from Polymarket for 50 markets and save them to our database.

2. Analysis: Our strategies analyze this data looking for patterns - like prices that moved too far from normal, or markets where the math doesn't add up.

3. Signals: When a strategy finds an opportunity, it generates a "signal" - a recommendation to buy or sell.

4. Execution: The execution engine takes these signals and simulates trades (paper trading). Eventually, this will place real orders.

5. Monitoring: This dashboard shows you what's happening. Telegram sends alerts for important events.