Documentation

PQAP system documentation and architecture

PQAP Platform Vision

Executive Summary

PQAP (Polymarket Quantitative Automation Platform) is designed to be a professional-grade systematic trading platform for prediction markets. This document outlines the end-state vision for what the platform will look like in 1 year when fully operational.

End-State Vision (1 Year)

What Success Looks Like

A fully operational PQAP platform where:

  1. New strategies can be developed, tested, and deployed in hours, not days
  2. All trading activity is transparent, auditable, and explainable
  3. The system runs autonomously 24/7 with minimal human intervention
  4. Risk is managed systematically with automatic safeguards
  5. Performance is tracked and attributed to specific strategies

Platform Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                        PQAP PLATFORM                                │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌────────────┐ │
│  │   DATA      │  │  STRATEGY   │  │  EXECUTION  │  │ REPORTING  │ │
│  │   LAYER     │  │   ENGINE    │  │   ENGINE    │  │  & ALERTS  │ │
│  └─────────────┘  └─────────────┘  └─────────────┘  └────────────┘ │
│         │                │                │               │         │
│  ┌──────┴────────────────┴────────────────┴───────────────┴──────┐ │
│  │                     CORE SERVICES                             │ │
│  │  • Configuration  • Risk Management  • Position Tracking      │ │
│  │  • Database       • Health Checks    • Audit Logging          │ │
│  └───────────────────────────────────────────────────────────────┘ │
│                                                                     │
│  ┌───────────────────────────────────────────────────────────────┐ │
│  │                     INFRASTRUCTURE                            │ │
│  │  • Local Dev  • EC2 Production  • CI/CD Pipeline  • Backups   │ │
│  └───────────────────────────────────────────────────────────────┘ │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Core Components

1. Data Layer

Purpose: Ingest, store, and serve market data

Component Current State Target State
Market Data Ingestion Gamma API polling Real-time WebSocket + polling fallback
Historical Database SQLite (market_history.db) SQLite + partitioned archives
Feature Engineering Ad-hoc in strategies Centralized feature store
Data Quality None Automated quality checks

2. Strategy Engine

Purpose: Develop, test, and run trading strategies

Component Current State Target State
Strategy Interface BaseStrategy class Enhanced with lifecycle hooks
Backtesting Basic framework exists Full backtesting with metrics
Paper Trading Working Enhanced with realistic slippage
Live Trading Not implemented Polymarket CLOB integration
Strategy Registry Manual config Dynamic discovery + hot-reload

3. Execution Engine

Purpose: Execute trades safely and efficiently

Component Current State Target State
Order Management Paper trading only Full order lifecycle
Position Tracking JSON state file Database-backed with history
Risk Checks Basic per-strategy Global + per-strategy limits
Slippage Model None Configurable slippage simulation

4. Reporting & Alerts

Purpose: Monitor performance and alert on issues

Component Current State Target State
Dashboard Basic Flask app Full-featured web UI
Telegram Alerts Working Enhanced with commands
Performance Reports Manual analysis Automated daily/weekly reports
Audit Trail Basic logging Full trade journal

User Workflows

Workflow 1: Developing a New Strategy

1. Create strategy from template
   $ pqap strategy new my_strategy_v1

2. Implement strategy logic
   - Edit src/strategies/my_strategy/strategy.py
   - Define entry/exit conditions
   - Configure parameters in YAML

3. Backtest strategy
   $ pqap backtest my_strategy_v1 --start 2024-01-01 --end 2024-12-01

4. Paper trade strategy
   $ pqap paper my_strategy_v1 --duration 7d

5. Deploy to production
   $ pqap deploy my_strategy_v1 --env prod

Workflow 2: Monitoring the System

1. Check system health
   $ pqap status

2. View current positions
   $ pqap positions

3. Check strategy performance
   $ pqap performance --period 7d

4. View recent trades
   $ pqap trades --last 50

5. Access web dashboard
   https://pqap.tailwindtech.ai

Workflow 3: Deploying Changes

1. Make changes locally
2. Run tests
   $ pqap test
3. Deploy to EC2
   $ pqap deploy --env prod
4. Verify deployment
   $ pqap status --env prod

Environment Setup

Local Development

  • Purpose: Strategy development, testing, debugging
  • Database: data/pqap_dev.db
  • Config: configs/dev.yaml
  • Trading: Paper trading only

EC2 Production

  • Purpose: 24/7 operation, production trading
  • URL: https://pqap.tailwindtech.ai
  • Database: Persistent SQLite + S3 backups
  • Config: configs/prod.yaml
  • Trading: Paper trading (upgradeable to live)

Documentation Structure

All documentation lives in /docs/ and is accessible via the web dashboard:

docs/
├── README.md                 # Quick start guide
├── PLATFORM_VISION.md        # This document
├── USER_GUIDE.md             # How to use the platform
├── STRATEGY_GUIDE.md         # How to develop strategies
├── DEPLOYMENT_GUIDE.md       # How to deploy changes
├── API_REFERENCE.md          # API documentation
├── ARCHITECTURE.md           # Technical architecture
├── OPERATIONS_RUNBOOK.md     # Operational procedures
└── research_log.md           # Ongoing research notes

Key Milestones

Phase 1: Foundation (Current → Week 2)

  • [ ] Complete documentation structure
  • [ ] Implement CLI tool (pqap command)
  • [ ] Set up proper testing framework
  • [ ] Create strategy development template

Phase 2: Testing Infrastructure (Week 2-4)

  • [ ] Full backtesting framework
  • [ ] Integration tests
  • [ ] Paper trading enhancements
  • [ ] Performance attribution

Phase 3: Operations (Week 4-6)

  • [ ] CI/CD pipeline
  • [ ] Automated deployments
  • [ ] Monitoring dashboards
  • [ ] Automated backups

Phase 4: Enhancement (Week 6-12)

  • [ ] Live trading integration
  • [ ] Advanced risk management
  • [ ] ML model pipeline
  • [ ] Multi-strategy coordination

Success Metrics

Metric Current Target
Time to develop new strategy Days Hours
Time to deploy changes Manual (30 min) Automated (5 min)
Test coverage ~0% >80%
Documentation coverage Partial Complete
System uptime Manual monitoring 99.9% with auto-recovery
Strategy performance visibility Manual analysis Real-time dashboard

Next Actions

  1. Create comprehensive documentation - All user-facing docs
  2. Build CLI tool - pqap command for all operations
  3. Implement testing framework - Unit, integration, backtest
  4. Set up CI/CD - Automated testing and deployment
  5. Enhance dashboard - Real-time monitoring and reporting

Last Updated: 2025-12-25

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_prod.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.