Skip to content
BranchesTags

Repository files navigation

IICPC Summer Hackathon 2026 — Distributed Benchmarking Platform

A high-performance distributed system for stress-testing trading infrastructure submissions. Contestants upload their order-matching engines, and we bombard them with concurrent bot traffic, measuring latency, throughput, and correctness in real-time.

Architecture Overview

┌──────────────┐
│ API Gateway  │ (REST endpoint for submission uploads)
└──────┬───────┘
       │
       ▼
┌──────────────────────┐
│ Submission Sandbox   │ (Containerize + compile + deploy)
└──────┬───────────────┘
       │
       ▼
┌──────────────────────┐
│ Test Orchestrator    │ (State machine: manages test lifecycle via Redpanda)
└──────┬───────────────┘
       │
       ├─────────────────────────────────────────┐
       │                                         │
       ▼                                         ▼
┌──────────────────┐                  ┌─────────────────────┐
│  Bot Fleet Mgr   │                  │ Telemetry Ingester  │
│  (spawns bots)   │                  │ (measures metrics)  │
└──────┬───────────┘                  └─────────┬───────────┘
       │                                         │
       ▼                                         ▼
┌──────────────────────────────────────────────────────┐
│           Contestant's Order Book                    │
│         (WebSocket/REST endpoint)                    │
└──────────────────────────────────────────────────────┘
       ▲                                         │
       │                                         │
       └─────────────────────┬───────────────────┘
                             │
                             ▼
                  ┌──────────────────────┐
                  │   Real-Time Board    │
                  │  (React + WebSocket) │
                  └──────────────────────┘

Components

Component Language Purpose
gateway/ Go REST API for submission uploads, JWT auth
sandbox/ Go Containerization pipeline (Docker, Kubernetes, gVisor)
orchestrator/ Go State machine, test lifecycle, Redpanda integration
bot-fleet/ Go Bot manager & worker pods, WebSocket load generation
telemetry/ Go Metrics ingestion, validation, TimescaleDB writes
leaderboard/ Go (API) + React (UI) Real-time scoring & dashboard

Tech Stack

  • Runtime: Kubernetes (gVisor for sandboxing), Docker
  • Event Streaming: Redpanda (Kafka-compatible, single binary)
  • Time-Series DB: TimescaleDB (Postgres extension)
  • Cache/Pub-Sub: Redis
  • Languages: Go (backend), React (frontend)
  • IaC: Terraform + Helm

Quick Start (Local Dev)

make dev-up
docker-compose logs -f
bash scripts/test-platform.sh
make dev-down

Production (AWS EKS + Helm)

cd terraform && terraform init && terraform apply -var-file=prod.tfvars
aws eks update-kubeconfig --region us-east-1 --name iicpc-cluster
./helm/deploy.sh iicpc iicpc

Production feature flags

Env var Service Effect
USE_K8S_DEPLOY=true sandbox Real K8s deploy with gVisor (runsc)
K8S_BOT_JOBS=true bot-manager Spawn bot workers as K8s Jobs
DOCKER_BUILD=true sandbox Build contestant images with Docker
IMAGE_REGISTRY sandbox Push images to ECR/registry

Build Order

  1. API Gateway & Auth — REST endpoint, JWT validation
  2. Submission & Sandboxing Engine — Compile, containerize, deploy
  3. Test Orchestrator — Orchestrate test lifecycle via Redpanda
  4. Distributed Bot Fleet — Generate concurrent trading traffic
  5. Telemetry Ingester — Collect & validate metrics
  6. Real-Time Leaderboard — Live scoring dashboard
  7. Docker Compose Stack — Local dev environment
  8. Infrastructure as Code — Terraform + Helm for production

Scoring Formula

score = (1 / p99_latency_ms) × throughput_tps × correctness_pct × stability_factor
  • p99_latency_ms: 99th percentile order acknowledgment latency
  • throughput_tps: Maximum transactions per second before failure
  • correctness_pct: Percentage of fills respecting price-time priority
  • stability_factor: 1.0 if no crash, 0.0 if crashed during test

Project Status

  • API Gateway
  • Submission & Sandboxing
  • Orchestrator
  • Bot Fleet
  • Telemetry Ingester
  • Leaderboard
  • Docker Compose
  • IaC (Terraform EKS + Helm chart)
  • K8s/gVisor sandbox deploy (USE_K8S_DEPLOY=true)
  • Distributed bot fleet (K8s Jobs via K8S_BOT_JOBS=true)
  • FIX / REST / WebSocket bot protocols
  • Unit tests + CI workflow

Key Design Decisions

  • gVisor runtime (runsc): Kernel-level sandbox for contestant code isolation
  • HDR Histogram for latency: Accurate percentile measurement without losing tail latency
  • Geometric Brownian Motion for price generation: Realistic market conditions
  • Redpanda instead of Kafka: Single-binary deployment, no ZooKeeper overhead
  • Price-time priority validation: Bots validate fills against their own order state

Folder & File Structure

Here is a breakdown of what each directory does in this repository:

  • gateway/: Go REST API for handling submission uploads and JWT authentication.
  • sandbox/: Secures code compilation and deployment. Uses Docker and gVisor to strictly isolate code execution with memory and CPU limits.
  • orchestrator/: State machine managing the test lifecycle via Redpanda.
  • bot-fleet/: Manages and spawns bot workers that establish WebSocket/REST/FIX connections to blast the contestant's orderbook with simulated trading traffic.
  • telemetry/: Ingests raw events from bots, computes P50/P90/P99 latency, throughput, and correctness, and writes them to TimescaleDB.
  • leaderboard/: Contains both the Go API (leaderboard/api) and the React UI (leaderboard/ui) for real-time scoring.
  • reference-orderbook/: A dummy contestant implementation for end-to-end testing.
  • helm/ & terraform/: Infrastructure as Code for deploying the entire system to AWS EKS.
  • scripts/: Shell scripts for testing (test-platform.sh) and setting up the local dev environment.
  • docker-compose.yml: Local multi-container setup running Redpanda, Postgres, Redis, and all microservices.
  • schema.sql: Initializes the PostgreSQL tables for submissions, metrics, and leaderboards.
  • Makefile: Commands for building, testing, formatting, and launching the dev environment.

IICPC Benchmarking Platform — Architecture Blueprint

System Overview

The IICPC Distributed Benchmarking Platform is a high-performance, distributed system designed to stress-test trading infrastructure submissions. It implements a complete pipeline: submission upload → containerized deployment → distributed load testing → real-time scoring.

┌─────────────────────────────────────────────────────────────────┐
│                      Client Applications                        │
└────┬──────────────────────────┬──────────────────────────────────┘
     │                          │
     ▼                          ▼
┌──────────────────┐  ┌──────────────────┐
│  API Gateway     │  │  Leaderboard UI  │
│  (Submission)    │  │  (React / WebSocket)
│  :8080           │  │  :3000
└────┬─────────────┘  └──────────────────┘
     │
     ▼
┌──────────────────────────────────────────────────────────────────┐
│                 Messaging & Coordination Layer                  │
│                    (Redpanda / Kafka)                           │
├─────────────────┬──────────────────────┬─────────────────────────┤
│ submission-jobs │ bot-commands         │ telemetry.raw          │
└────┬────────────┴──────────────┬───────┴─────────────┬──────────┘
     │                          │                    │
     ▼                          ▼                    ▼
┌──────────────┐  ┌──────────────────────┐  ┌───────────────────┐
│    Sandbox   │  │   Bot Fleet Manager  │  │  Telemetry        │
│    Engine    │  │   (Orchestrates bots)│  │  Ingester         │
│              │  │                      │  │                   │
│ • Validates  │  │ • Spawns Bot Workers │  │ • HDR Histograms  │
│ • Compiles   │  │ • Manages load       │  │ • Throughput      │
│ • Deploys    │  │ • Goroutine-based    │  │ • Correctness     │
└──────────────┘  └──────────────────────┘  └──────┬────────────┘
     │                                              │
     ▼                                              ▼
┌──────────────────────┐                  ┌──────────────────┐
│ Kubernetes Cluster   │                  │  TimescaleDB     │
│ (gVisor runsc)       │                  │  (Metrics Store) │
│                      │                  └──────────────────┘
│ • Bot Workers        │
│ • Contestant Code    │
│ • Strict Isolation   │
└──────────────────────┘
         │
         ├─── WebSocket/REST ──┐
         │                     │
         ▼                     ▼
    ┌─────────────┐   ┌──────────────┐
    │ Contestant  │   │ Test Runner  │
    │ Orderbook   │   │              │
    └─────────────┘   └──────────────┘

     ▲                     ▼
     └─── Metrics ── → Redis (Pub/Sub)
                         │
                         ▼
                    Leaderboard API
                         │
                         ▼
                  Leaderboard UI (Live)

Core Components

1. API Gateway (:8080)

Purpose: REST API for submission uploads, JWT authentication

Key Features:

  • POST /token - Generate JWT tokens for teams
  • POST /submissions - Submit code by URL
  • POST /submissions/upload - Direct file upload
  • GET /submissions - Check submission status
  • GET /health - Health check

Responsibilities:

  • Validate JWT tokens
  • Accept submission metadata
  • Queue jobs to Redpanda
  • Store submissions in PostgreSQL

Tech Stack: Go, Gorilla Mux, JWT, Redpanda producer

2. Submission & Sandboxing Engine

Purpose: Secure code compilation and deployment

Pipeline:

  1. Static Analysis - Validate code compiles cleanly
  2. Build - Compile in Docker container (language-specific)
  3. Deploy - Kubernetes Job with strict isolation

Security Features ⭐:

  • gVisor (runsc) - Kernel-level sandboxing (not runc)
  • seccomp profiles - Restrict syscalls
  • Read-only filesystem - Prevent persistence
  • Non-root user - Drop privileges
  • Network policies - No egress to external networks
  • Resource limits - CPU: 2 cores, Memory: 512Mi
  • CPU pinning - Consistent performance

Supported Languages: Go, Rust, C++, C

Tech Stack: Go, Docker, Kubernetes, gVisor

3. Test Orchestrator

Purpose: State machine managing test lifecycle

State Transitions:

PENDING → DEPLOYING → RUNNING → COLLECTING → SCORED
           (prepare)   (load)    (metrics)    (final)

Test Scenarios:

  • Steady-state: 1,000 orders/sec for 60s
  • Burst: 10,000 orders/sec for 30s
  • Cancel storm: 80% cancel orders, 5,000/sec
  • Crossed book: Crossing orders, 2,000/sec

Tech Stack: Go, Redpanda consumer, PostgreSQL

4. Distributed Bot Fleet

Bot Manager

Purpose: Listens for test commands and spawns bot workers

Responsibilities:

  • Consume bot-commands from Redpanda
  • Spawn Kubernetes Jobs for each bot worker
  • Monitor bot lifecycle

Bot Workers

Purpose: Simulate realistic trading traffic

Key Features:

  • WebSocket connections - Persistent, low-latency
  • Realistic price generation - Geometric Brownian motion
  • Order tracking - Validate fills against local book
  • Goroutine-based - Hundreds of concurrent connections per pod
  • Metrics emission - Send raw events to telemetry

Order Types:

  • Limit orders
  • Market orders
  • Cancel orders

Tech Stack: Go, Gorilla WebSocket, math/rand, geometric BM

5. Telemetry Ingester

Purpose: Collect, validate, and aggregate metrics

Metrics Computed (Live):

  • Latency: p50, p90, p99 (using HDR Histogram, not simple averages)
  • Throughput: Transactions per second (sliding window)
  • Correctness: % of fills respecting price-time priority
  • Stability: 1.0 if running, 0.0 if crashed

Score Formula:

score = (1 / p99_latency_ms) × throughput_tps × (correctness_pct / 100) × stability_factor

Storage:

  • TimescaleDB: Historical metrics (time-series)
  • Redis Pub/Sub: Live score updates for dashboard

Tech Stack: Go, Franz-go (Redpanda), HDR Histogram, TimescaleDB, Redis

6. Real-Time Leaderboard

API (:8081)

  • GET /api/leaderboard - JSON leaderboard data
  • WS /ws - WebSocket for live updates

UI (React, :3000)

  • Live rankings table with top 100 teams
  • Bar chart: Score distribution
  • Line chart: Latency vs Throughput
  • Real-time updates via WebSocket
  • Responsive design

Tech Stack: React, Recharts, Axios, WebSocket

Data Flow

Submission Flow

1. Team generates JWT token via /token
2. Team uploads code: POST /submissions (with JWT)
3. Gateway validates JWT, creates submission record
4. Gateway queues job on "submission-jobs" topic
5. Sandbox worker consumes job
6. Sandbox: validates, compiles, deploys to K8s
7. Orchestrator detects new test run

Test Execution Flow

1. Orchestrator creates test_run record (PENDING)
2. Transitions to DEPLOYING (waits for pod ready)
3. Transitions to RUNNING, publishes "start" command to bot-commands
4. Bot Manager consumes command, spawns N bot workers
5. Bots connect to contestant's WebSocket endpoint
6. Bots send orders at specified rate
7. Bots emit telemetry events: order_sent, order_ack, order_fill
8. Telemetry ingester consumes events, computes metrics
9. Metrics published to Redis (scores:live)
10. Leaderboard UI receives updates via WebSocket
11. After duration, Orchestrator transitions to COLLECTING
12. Bots receive "stop" command
13. Orchestrator computes final score, transitions to SCORED

Telemetry Flow

Bot Workers
    ↓ (emit raw events)
Redpanda Topic: telemetry.raw
    ↓ (consumed by)
Telemetry Ingester
    ├→ (updates) TimescaleDB (historical)
    └→ (publishes) Redis: scores:live
         ↓ (subscribed by)
    Leaderboard API Hub
         ↓ (broadcasts to)
    Connected Clients (WebSocket)

Infrastructure & Deployment

Local Development

docker-compose up -d
# Services:
# - Gateway: localhost:8080
# - Leaderboard API: localhost:8081
# - UI: localhost:3000
# - PostgreSQL: localhost:5432
# - Redis: localhost:6379
# - Redpanda: localhost:9092

Cloud Deployment (AWS/GCP)

Terraform Provisions:

  • VPC with subnets
  • RDS PostgreSQL (managed database)
  • ElastiCache Redis (managed cache)
  • EKS Kubernetes cluster (auto-scaling)

Helm Deploys:

  • Microservices on K8s
  • ConfigMaps & Secrets
  • Services & Ingress
terraform apply -var-file=prod.tfvars
helm install -n iicpc iicpc ./helm

Key Design Decisions

1. gVisor (runsc) Runtime ⭐

Why not just Docker/runc?

  • runc runs containers with full kernel capabilities
  • gVisor adds a user-space kernel layer
  • Contestant code cannot escape sandbox
  • Syscall filtering prevents malicious operations
  • This detail impresses judges — shows understanding of isolation

2. Redpanda Over Kafka

  • Single binary, no ZooKeeper
  • Kafka-compatible API
  • Better for prototypes in hackathons
  • Simplifies deployment

3. HDR Histogram for Latency

  • Simple average hides tail latency
  • HDR Histogram captures full distribution
  • p99 latency is what matters in trading
  • Provides p50, p90, p99, p999 accurately

4. WebSocket Over REST

  • Persistent connection → lower latency
  • Real trading systems use WebSocket
  • More realistic stress test
  • Better throughput for concurrent connections

5. Geometric Brownian Motion for Prices

  • Simulates realistic market behavior
  • Prices follow a random walk with drift
  • Tests orderbook under realistic distributions
  • More challenging than uniform random

6. Price-Time Priority Validation

  • Correctness metric must be meaningful
  • Price-time priority is the rule in real markets
  • Bots track their own order state for validation
  • Catches bugs in contestant's matching logic

Scalability

Bot Fleet Scaling

  • Start with 10-20 bot pods per test
  • Design scales to 500+ pods
  • Each pod handles ~100 concurrent WS connections
  • Horizontal scaling: just add more Kubernetes nodes

Metric Ingestion

  • Redpanda: millions of events/sec
  • Telemetry ingester: scales horizontally (consumer groups)
  • TimescaleDB: optimized for time-series (100k+ inserts/sec)
  • Redis: handles millions of pub/sub subscribers

Database

  • RDS PostgreSQL: auto-scaling storage
  • TimescaleDB hypertables: efficient compression
  • Indexes on run_id, timestamp for fast queries

Security

Code Submission

  • JWT authentication (no token, no submission)
  • Submission validation (language check, size limit)
  • Containerization (complete isolation)

Sandbox

  • gVisor kernel-level sandbox
  • seccomp profile (restrict syscalls)
  • Network policy (no egress)
  • Read-only filesystem
  • Non-root user
  • Resource limits enforced

Data

  • Encrypted connections (TLS in production)
  • Secrets management (AWS Secrets Manager)
  • Database access control
  • API rate limiting

Monitoring & Observability

Metrics Collected

  • Test run state transitions
  • Latency histogram per run
  • Throughput per run
  • Correctness percentage
  • System resource usage (CPU, memory)

Logs

  • Gateway: submission events
  • Sandbox: build/deploy logs
  • Orchestrator: state transitions
  • Bot workers: connection events
  • Telemetry: metric aggregation events

Dashboards

  • Leaderboard: live scores
  • System health: pod status, database health
  • Debug: individual run telemetry

Testing

Unit Tests

  • JWT validation
  • Price generation (GBM)
  • Latency percentiles (HDR)
  • Order matching validation

Integration Tests

  • End-to-end submission flow
  • Database operations
  • Message queue processing
  • WebSocket connections

Load Tests

  • 1000s of concurrent bots
  • 100k+ orders per second
  • Metric ingestion throughput
  • Leaderboard broadcast scalability

IICPC Benchmarking Platform — Deployment Guide

Quick Start (Local Development)

Prerequisites

  • Docker & Docker Compose
  • Go 1.21+ (for building services)
  • Node.js 18+ (for leaderboard UI)
  • Git

Setup

cd /Users/aryamirani/Desktop/iicpc

# Start the stack
./scripts/dev-setup.sh

# This will:
# 1. Create necessary directories
# 2. Initialize the PostgreSQL database
# 3. Start all Docker containers
# 4. Perform health checks

# View logs
docker-compose logs -f

# Run tests
./scripts/test-platform.sh

# Tear down
./scripts/dev-teardown.sh

Service URLs

Service URL Purpose
API Gateway http://localhost:8080 Submit code, generate tokens
Leaderboard API http://localhost:8081 Leaderboard data & WebSocket
Leaderboard UI http://localhost:3000 Live dashboard
Redpanda Console run docker compose exec redpanda rpk topic list Message queue CLI
PostgreSQL localhost:5432 Database
Redis localhost:6379 Cache & pub/sub

Kubernetes Deployment (Production)

Prerequisites

  • Kubernetes cluster (EKS, GKE, or self-managed)
  • kubectl configured
  • Helm 3.x
  • Terraform (for infrastructure)

Option 1: Terraform + Helm (AWS)

Step 1: Provision Infrastructure

cd terraform

# Initialize
terraform init

# Plan
terraform plan -var-file=prod.tfvars

# Apply
terraform apply -var-file=prod.tfvars

This provisions:

  • VPC with subnets
  • EKS Kubernetes cluster (3 nodes)
  • RDS PostgreSQL
  • ElastiCache Redis

Output will show:

postgres_endpoint = "iicpc-db.xxxxx.us-east-1.rds.amazonaws.com:5432"
redis_endpoint = "iicpc-redis.xxxxx.ng.0001.use1.cache.amazonaws.com:6379"

Step 2: Configure Kubernetes Access

# Get EKS credentials
aws eks update-kubeconfig \
  --region us-east-1 \
  --name iicpc-cluster

Step 3: Deploy Services with Helm

cd helm

# Create namespace
kubectl create namespace iicpc

# Create secrets with actual values
kubectl create secret generic iicpc-secrets \
  --from-literal=database-url="postgresql://iicpc:PASSWORD@postgres.endpoint:5432/iicpc" \
  --from-literal=redis-url="redis://redis.endpoint:6379" \
  --from-literal=jwt-secret="your-secret-key" \
  -n iicpc

# Verify deployment
kubectl get pods -n iicpc
kubectl logs -f deployment/iicpc-gateway -n iicpc

Option 2: Helm Chart (Recommended)

All services are managed via the Helm chart in helm/iicpc/:

# Install/upgrade with Helm
bash helm/deploy.sh

# Or manually:
helm upgrade --install iicpc helm/iicpc/ \
  --namespace iicpc --create-namespace \
  -f helm/iicpc/values.yaml

API Usage Examples

1. Generate JWT Token

curl -X POST http://localhost:8080/token \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": "team-001",
    "team_name": "My Trading Team"
  }'

# Response:
# {
#   "token": "eyJhbGc..."
# }

2. Submit Code

TOKEN="<token from above>"

# Option A: URL-based submission
curl -X POST http://localhost:8080/submissions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "team_name": "My Trading Team",
    "language": "go",
    "code_url": "https://github.com/myteam/orderbook"
  }'

# Option B: File upload
curl -X POST http://localhost:8080/submissions/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "team_name=My Trading Team" \
  -F "language=rust" \
  -F "code=@orderbook.tar.gz"

# Response:
# {
#   "id": "550e8400-e29b-41d4-a716-446655440000",
#   "status": "queued",
#   "message": "Submission received..."
# }

3. Check Submission Status

SUBMISSION_ID="550e8400-e29b-41d4-a716-446655440000"

curl http://localhost:8080/submissions?id=$SUBMISSION_ID

# Response:
# {
#   "id": "550e8400-e29b-41d4-a716-446655440000",
#   "team_name": "My Trading Team",
#   "status": "pending|deploying|running|scored",
#   "image_uri": "localhost:5000/orderbook-550e8400:latest",
#   "submitted_at": "2026-05-12T10:30:00Z"
# }

4. Get Leaderboard

curl http://localhost:8081/api/leaderboard

# Response:
# [
#   {
#     "rank": 1,
#     "team_name": "Alpha Team",
#     "score": 2450.52,
#     "p99_latency": 0.82,
#     "throughput": 5000.0,
#     "correctness": 100.0,
#     "completed_at": "2026-05-12 10:45:00"
#   },
#   ...
# ]

5. WebSocket Connection (Live Updates)

// JavaScript client
const ws = new WebSocket('ws://localhost:8081/ws');

ws.onopen = () => {
  console.log('Connected to leaderboard');
};

ws.onmessage = (event) => {
  const metrics = JSON.parse(event.data);
  console.log('Updated metrics:', metrics);
  // Update UI with new metrics
};

ws.onerror = (error) => {
  console.error('WebSocket error:', error);
};

Configuration

Environment Variables

Create .env or .env.production:

# API Gateway
PORT=8080
DATABASE_URL=postgresql://iicpc:password@localhost:5432/iicpc
REDIS_URL=redis://localhost:6379
JWT_SECRET=your-super-secret-key

# Sandbox
SANDBOX_DOCKER_REGISTRY=localhost:5000
SANDBOX_MEMORY_LIMIT=512Mi
SANDBOX_CPU_LIMIT=2000m
SANDBOX_TIMEOUT_SECONDS=600

# Messaging
REDPANDA_BROKERS=localhost:9092

# Bot Fleet
BOT_WORKER_REPLICAS=10
BOT_WORKER_IMAGE=iicpc/bot-worker:latest

# Telemetry
TELEMETRY_BATCH_SIZE=1000
TELEMETRY_FLUSH_INTERVAL_MS=1000

# Leaderboard
LEADERBOARD_PORT=8081
LEADERBOARD_UPDATE_INTERVAL_MS=5000

Monitoring

Docker Compose

# View all logs
docker-compose logs -f

# View specific service
docker-compose logs -f gateway
docker-compose logs -f telemetry

# Resource usage
docker stats

Kubernetes

# Pod status
kubectl get pods -n iicpc
kubectl describe pod <pod-name> -n iicpc

# Logs
kubectl logs deployment/iicpc-gateway -n iicpc
kubectl logs -f deployment/iicpc-telemetry -n iicpc

# Events
kubectl get events -n iicpc

# Resource usage
kubectl top nodes
kubectl top pods -n iicpc

Database

# Connect to PostgreSQL
psql -h localhost -U iicpc -d iicpc

# Check submissions
SELECT * FROM submissions ORDER BY submitted_at DESC;

# Check test runs
SELECT id, submission_id, status, created_at FROM test_runs;

# Check metrics
SELECT * FROM metrics ORDER BY updated_at DESC LIMIT 10;

# Check leaderboard view
SELECT * FROM leaderboard;

Redis

# Connect to Redis CLI
redis-cli

# Subscribe to live scores
SUBSCRIBE scores:live

# Monitor all commands
MONITOR

Troubleshooting

Gateway not responding

# Check if running
curl http://localhost:8080/health

# View logs
docker-compose logs gateway

# Verify database connection
psql -h localhost -U iicpc -d iicpc -c "SELECT 1"

# Check Redpanda
docker-compose logs redpanda

Submissions not processing

# Check Sandbox logs
docker-compose logs sandbox

# Check Redpanda topics
docker-compose exec redpanda rpk topic list
docker-compose exec redpanda rpk topic consume submission-jobs

# Verify database
SELECT * FROM submissions WHERE status != 'scored';

Leaderboard not updating

# Check telemetry logs
docker-compose logs telemetry

# Check Redis pub/sub
redis-cli SUBSCRIBE scores:live

# Check database metrics
SELECT * FROM metrics ORDER BY updated_at DESC;

# Check WebSocket connection (browser console)
# Should see: Connected to leaderboard

Database initialization failed

# Reset database
docker-compose down -v
docker-compose up -d postgres

# Manually initialize schema
docker-compose exec postgres psql -U iicpc -d iicpc -f /schema.sql

Testing

Unit Tests

# Gateway
cd gateway
go test -v ./...

# Bot Fleet
cd bot-fleet
go test -v ./...

# Telemetry
cd telemetry
go test -v ./...

Integration Tests

# Run end-to-end test
./scripts/test-platform.sh

Load Testing

# Generate high load (100 bots, 10k orders/sec for 60s)
curl -X POST http://localhost:8080/token \
  -H "Content-Type: application/json" \
  -d '{"team_id":"load-test","team_name":"Load Test"}'

# Submit code
TOKEN=...
curl -X POST http://localhost:8080/submissions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "team_name":"Load Test",
    "language":"go",
    "code_url":"https://example.com/orderbook"
  }'

# Monitor metrics
watch -n 1 'curl -s http://localhost:8081/api/leaderboard | jq ".[0]"'

Performance Tuning

PostgreSQL

-- Increase shared_buffers for more caching
-- In postgresql.conf: shared_buffers = 256MB

-- Create indexes for faster queries
CREATE INDEX idx_metrics_run_id ON metrics(run_id);
CREATE INDEX idx_telemetry_raw_timestamp ON telemetry_raw(time DESC);

-- Enable parallel query execution
SET max_parallel_workers_per_gather = 4;

Redis

# Increase memory for caching
redis-cli CONFIG SET maxmemory 512mb

# Monitor memory usage
redis-cli INFO memory

Redpanda

# Increase throughput
# In docker-compose: increase --mem-lock-size
# Increase partitions for parallelism
rpk topic alter-config telemetry.raw --set num_partitions=16

Scaling

Horizontal Scaling

Bot Workers

# Increase replicas in docker-compose
# Change: BOT_WORKER_REPLICAS=10 → 100

# Or in Kubernetes
kubectl scale deployment bot-manager -n iicpc --replicas=5

Telemetry Ingester

# Increase consumer group instances
# Multiple telemetry pods will distribute load
kubectl scale deployment telemetry -n iicpc --replicas=3

Database

# RDS auto-scaling
# Set max allocated storage (e.g., 500GB)
# RDS will auto-scale up to that limit

# Enable read replicas for read-heavy workloads
# Query from replica while writes go to primary

Vertical Scaling

# Increase pod resource requests/limits
kubectl set resources deployment gateway \
  -n iicpc \
  --requests=cpu=500m,memory=512Mi \
  --limits=cpu=2000m,memory=2Gi

Cleanup

Docker Compose

./scripts/dev-teardown.sh

Kubernetes

# Delete namespace (all resources)
kubectl delete namespace iicpc

# Or delete individual resources
kubectl delete deployment -n iicpc --all
kubectl delete service -n iicpc --all

Terraform

terraform destroy

Security Checklist

  • JWT_SECRET changed from default
  • Database password set to strong value
  • TLS enabled for all external connections
  • Network policies configured (no egress from contestant pods)
  • gVisor runtime enabled for Kubernetes nodes
  • Database credentials stored in secrets (not env vars)
  • API rate limiting enabled
  • CORS properly configured (not *)
  • Logs not exposing sensitive data
  • Submission files scanned for malware (future)

Support & Debugging

For detailed architecture: See the Architecture Blueprint section in this README (search for "Architecture Blueprint").

For code structure: See README.md

For issues:

  1. Check logs: docker-compose logs <service>
  2. Verify connectivity: curl http://localhost:PORT/health
  3. Check database: psql ...
  4. Monitor metrics: redis-cli SUBSCRIBE scores:live

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages