jedarden/ai-code-battle
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
ai-code-battle/PROGRESS.md
jedarden 70bde20472 Add Go index builder (cmd/acb-index-builder) 
Per plan §11.1, the index builder reads PostgreSQL and generates all JSON
index files for Cloudflare Pages deployment:

- main.go: Build cycle orchestration with configurable timeout, self-restart
- config.go: Environment-based configuration with sensible defaults
- db.go: PostgreSQL data fetching for bots, matches, series, seasons, predictions
- generator.go: JSON index generation (leaderboard, bots, matches, playlists)
- deploy.go: Cloudflare Pages deployment via wrangler, R2 warm cache pruning
- Dockerfile: Multi-stage build with Go + Node.js + wrangler CLI
- main_test.go: Tests for config, index generation, playlists

Index builder runs on 15-minute cycles, deploys to Pages every ~90 minutes,
and prunes R2 warm cache weekly to stay within 10GB free tier.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-29 03:15:47 -04:00

29 KiB
Raw Blame History

AI Code Battle - Implementation Progress

Current Phase: Phase 9 - Platform Depth

Status: 🔄 In Progress

Last Updated: 2026-03-29 (Go index-builder implementation)

Recent Changes (2026-03-29)

  • Go Index Builder (cmd/acb-index-builder/): New Go implementation per plan §11.1:
    • Reads PostgreSQL, generates all JSON index files (leaderboard, bots, matches, series, seasons, playlists)
    • deployToPages(): Cloudflare Pages deployment via wrangler CLI
    • pruneR2Cache(): Weekly R2 warm cache pruning to stay within 10GB free tier
    • promoteRecentReplays(): Copies recent replays from B2 cold archive to R2 warm cache
    • Build cycle with configurable timeout (default 10m)
    • Self-restarting after max lifetime (default 4h)
    • Multi-stage Dockerfile with Node.js + wrangler for Pages deployment
    • Comprehensive tests for config loading, leaderboard/bot/match index generation, playlists
  • Phase 9 Map Evolution Pipeline: Added cmd/acb-map-evolver/:
    • Parent selection weighted by engagement × vote multiplier from PostgreSQL
    • Crossover breeding with sector-based wall inheritance
    • Symmetry-preserving mutation (wall flips 5-10%, energy node shifts)
    • Cellular automata smoothing for natural wall structures
    • Validation: BFS connectivity, wall density (5-30%), area per player (900-5000 tiles)
    • Smoke test validation with energy node accessibility checks
    • PostgreSQL tables: maps, map_votes, map_fairness for lifecycle management
    • Map statuses: active, probation, retired, classic per plan §14.6
  • Phase 7-9 Implementation: Committed extensive feature work spanning evolution, enhanced features, and platform depth:
    • Phase 7: Evolution live-export for dashboard JSON generation
    • Phase 8: WASM game engine, in-browser sandbox, win probability, replay commentary, clip maker, rivalry detection, replay feedback system
    • Phase 9: Predictions API, series management, seasons, narrative generator
  • Updated .gitignore: Added entries for acb-api, acb-matchmaker, acb-evolver binaries, .beads/ directory, and .needle.yaml
  • All tests pass (engine + cmd packages)

Previous Changes (2026-03-29)

  • Architecture Conformance Fix: Separated matchmaker from acb-api into acb-matchmaker per plan §12 Phase 4:
    • Plan specifies "Matchmaker Deployment (acb-matchmaker): internal tickers for pairing bots (1 min), health checking (15 min), stale job reaping (5 min). No external exposure."
    • Created cmd/acb-matchmaker/ with main.go, tickers.go, config.go, crypto.go, alerts.go
    • Removed tickers.go from acb-api (tickers now in separate deployment)
    • Removed alerter field from acb-api Server struct (alerting now in matchmaker)
    • Created cmd/acb-matchmaker/Dockerfile for container builds
    • Created cluster-configuration/apexalgo-iad/ai-code-battle/acb-matchmaker-deployment.yml
    • Matchmaker runs as internal-only deployment with no HTTP endpoints exposed
    • Fixed syntax error in cmd/acb-api/db.go (prematurely closed schemaSQL string)
    • All tests pass (acb-api + acb-matchmaker builds successfully)

Previous Changes (2026-03-28)

  • Architecture Conformance Fix: Migrated K8s manifests from deploy/k8s/ to cluster-configuration/apexalgo-iad/ai-code-battle/ per plan specification:
    • Plan §9.3 and §9.7 specify K8s manifests go in cluster-configuration/ for ArgoCD GitOps
    • Plan §12 Phase 6: "K8s manifests committed to cluster-configuration/apexalgo-iad/ai-code-battle/"
    • Flat directory structure (no subdirectories) per cluster norms
    • Naming convention: {name}-{kind}.yml (e.g., acb-worker-deployment.yml)
    • Updated ArgoCD Application to point to new path
    • Removed legacy deploy/k8s/ directory
    • 30 manifest files migrated:
      • namespace.yml, argocd-application.yml
      • Deployments: acb-api, acb-worker, acb-index-builder, 6 strategy bots
      • Services: acb-api, 6 strategy bot services
      • Ingress: acb-api-ingressroute (Traefik), acb-api-certificate (cert-manager)
      • CI: EventSource, Sensor, ServiceAccount+RBAC, WorkflowTemplates
      • SealedSecrets: api-key, r2-credentials, bot-secrets, cloudflare-api-token, registry-credentials

Previous Changes (2026-03-26)

  • Added Discord/Slack alerting webhooks to Go API server (cmd/acb-api/alerts.go):
    • Alerter module sends notifications to Discord and/or Slack incoming webhook URLs
    • Discord embeds with color-coded severity (blue=info, yellow=warning, red=error) + timestamps
    • Slack attachments with color-coded severity + footer
    • Rate limiting with per-key dedup cooldown (5 min default) to prevent alert storms
    • Garbage collection of expired dedup entries
    • Helper methods: BotMarkedInactive, BotRecovered, StaleJobsReaped, MatchError
    • Integrated into health checker ticker (alerts on bot inactive/recovered transitions)
    • Integrated into stale job reaper ticker (alerts when stale jobs re-enqueued)
    • Config via ACB_DISCORD_WEBHOOK and ACB_SLACK_WEBHOOK env vars
    • 15 unit tests: enabled detection, Discord/Slack payload format, color codes, rate limiting, cooldown expiry, no-dedup bypass, webhook errors, both-webhook dispatch, helper methods, GC
    • Updated .env.example with Go API and alerting webhook configuration
    • All tests pass (45 API tests total, 15 new + 30 existing)

Previous Changes (2026-03-26)

  • Added Traefik IngressRoute, cert-manager Certificate, and CI/CD pipeline manifests (deploy/k8s/):
    • ingress/acb-api-ingressroute.yaml — Traefik IngressRoute for api.aicodebattle.com with CORS middleware (allow origins for aicodebattle.com), security headers, rate limiting (100 req/min burst 200)
    • ingress/acb-api-certificate.yaml — cert-manager Certificate (Let's Encrypt prod, ECDSA P-256)
    • ci/event-source.yaml — Argo Events webhook EventSource (port 12000)
    • ci/sensor.yaml — Argo Events Sensor: triggers Argo Workflow on push to master with DAG of parallel Kaniko builds for all 10 container images + site build
    • ci/workflow-template-build-image.yaml — WorkflowTemplate: Kaniko build with layer caching
    • ci/workflow-template-build-site.yaml — WorkflowTemplate: npm ci + build for web SPA
    • ci/service-account.yaml — ServiceAccount + Role + RoleBinding for CI workflows
    • sealed-secrets/registry-credentials.yaml — SealedSecret template for Forgejo registry auth
    • All 30 K8s manifest files validated (valid YAML with correct apiVersion/kind)
    • All tests pass (engine + worker + mapgen + api)

Previous Changes (2026-03-26)

  • Built Go API server (cmd/acb-api/) — the K8s-native API service per plan architecture:
    • HTTP server with graceful shutdown, configurable via environment variables
    • PostgreSQL schema: bots, matches, match_participants, jobs, rating_history tables
    • Health (/health) and readiness (/ready) endpoints checking PostgreSQL and Valkey
    • Bot registration (POST /api/register) with health check, HMAC secret generation, AES-256-GCM encryption
    • Key rotation (POST /api/rotate-key) with retire option
    • Bot status (GET /api/status/{bot_id}) with conservative display rating
    • Job claim (POST /api/jobs/claim) via Valkey BRPOP + PostgreSQL state update
    • Job result submission (POST /api/jobs/{job_id}/result) with transaction, participant scores, Glicko-2 rating update
    • Glicko-2 rating system in Go: multi-player pairwise adaptation, volatility update (Illinois algorithm)
    • Background tickers: matchmaker (1 min), health checker (15 min), stale job reaper (5 min)
    • Worker API key authentication (Bearer token or X-API-Key header)
    • Dockerfile: multi-stage Go build, non-root user, Alpine runtime
    • K8s deployment manifest + ClusterIP Service
    • 30 unit tests: Glicko-2 (8 tests), crypto (5 tests), config (3 tests), server/handlers (14 tests)
    • All tests pass (engine + worker + mapgen + api)

Previous Changes (2026-03-26)

  • Fixed math bug: replaced broken Taylor series sin/cos approximations with math.Sin/math.Cos in engine/match.go and cmd/acb-mapgen/main.go. The Taylor series produced incorrect results for angles > π, causing incorrect core/energy/wall placement in 3+ player maps.
  • Replaced random wall scatter with cellular automata wall generation in cmd/acb-mapgen/main.go:
    • Seeds full grid at 40% density
    • Runs 4 iterations of B5/S4 cellular automata smoothing
    • Enforces rotational symmetry by mirroring sector 0
    • Thins to target density
    • Protected zones around cores (3-tile radius) and energy nodes
    • Produces natural cave-like wall structures instead of scattered dots
  • Added comprehensive map generation tests (cmd/acb-mapgen/mapgen_test.go):
    • Connectivity validation across all player counts and 10 seeds each
    • Core count and ownership verification
    • Energy node/wall non-overlap
    • Wall density bounds checking
    • Disconnected map detection (BFS validation)
    • Small grid generation
    • Determinism (same seed = same map)
  • Added dominance win condition tests (engine/turn_test.go):
    • 100-turn consecutive dominance threshold verification
    • Dominance counter reset when falling below 80%
  • All tests pass (engine + worker + mapgen)

Previous Changes (2026-03-26)

  • Added Kubernetes manifests for GitOps deployment via ArgoCD (deploy/k8s/)
    • Namespace, ArgoCD Application with auto-sync and self-heal
    • Deployments: match worker (2 replicas), index builder, 6 strategy bots
    • ClusterIP Services for all 6 bots (cluster DNS: acb-strategy-*.ai-code-battle.svc:8080)
    • SealedSecret templates: API key, R2 credentials, bot HMAC secrets, Cloudflare API token
    • All manifests validated (20 files, valid YAML with correct apiVersion/kind)
    • Container images from forgejo.ardenone.com/ai-code-battle/ registry
    • Health/readiness probes on all deployments
    • Resource requests/limits on all containers
  • All tests pass (engine + worker)

Previous Changes (2026-03-26)

  • Added Prometheus-compatible metrics endpoint to match worker (cmd/acb-worker/metrics.go)
    • Counters: matches_total, match_errors_total, jobs_claimed/failed, replays_uploaded, poll_cycles, heartbeats
    • Histograms: match_duration_seconds, replay_upload_duration_seconds, replay_size_bytes
    • Worker info gauge with worker_id label
    • /health and /ready endpoints on metrics HTTP server (default :9090)
    • Configurable via ACB_METRICS_ADDR environment variable
  • Instrumented worker execution flow with metrics recording
  • Added comprehensive tests (cmd/acb-worker/metrics_test.go)
    • Health/ready endpoint tests, counter accuracy, histogram bucket correctness
    • Concurrency safety test (10 goroutines x 100 operations)
  • All tests pass (engine + worker)

Previous Changes (2026-03-24)

  • Added GitHub Actions CI workflow (.github/workflows/ci.yml)
  • Added README.md with project overview and quick start guide
  • Added .gitignore and package-lock.json files

Phase 6 Progress

  • Match worker container (cmd/acb-worker/Dockerfile)
    • Multi-stage Go build
    • Non-root user for security
    • Environment variable configuration
  • Bot-host deployment (docker-compose.bots.yml)
    • Orchestrates all 6 strategy bots
    • Health checks for each bot
    • Environment-based secret configuration
  • Worker deployment (docker-compose.workers.yml)
    • Match worker with scaling support
    • Index builder for periodic runs
    • R2 and API configuration
  • Environment configuration (.env.example)
    • Documented all required environment variables
  • Deployment documentation (DEPLOYMENT.md)
    • Architecture overview
    • Cloudflare setup instructions
    • Container deployment commands
    • Troubleshooting guide
  • D1 database schema and migrations
    • Complete schema.sql with all tables from plan
    • Added: predictions, predictor_stats, map_votes, replay_feedback, series, series_games, seasons
    • Added evolution fields to bots table (evolved, island, generation, parent_ids)
    • Created migrations/0001_initial.sql for D1 migrations
    • Updated wrangler.toml with migrations_dir config
  • Monitoring endpoints
    • /health - Liveness probe (always returns 200)
    • /ready - Readiness probe (checks database connectivity, returns 503 if unavailable)
    • Documented in DEPLOYMENT.md
  • Prometheus metrics endpoint (cmd/acb-worker/metrics.go)
    • Counters: matches, errors, jobs, replays, polls, heartbeats
    • Histograms: match duration, replay upload duration, replay size
    • Worker info gauge with labels
    • Separate HTTP server on configurable port (default :9090)
    • Integrated into worker execution flow with full instrumentation
  • GitHub Actions CI workflow
    • .github/workflows/ci.yml for automated testing
    • Go tests with race detector
    • TypeScript tests for worker-api and indexer
    • Web build verification
    • Go binary builds
  • Go API server (cmd/acb-api/)
    • HTTP server with graceful shutdown and env-var configuration
    • PostgreSQL schema with all core tables (bots, matches, match_participants, jobs, rating_history)
    • /health and /ready endpoints (PostgreSQL + Valkey connectivity)
    • Bot registration, key rotation, status endpoints
    • Job claim (Valkey BRPOP) and result submission with Glicko-2 rating update
    • Glicko-2 rating system: multi-player pairwise, volatility (Illinois algorithm)
    • Background tickers: matchmaker (1 min), health checker (15 min), stale job reaper (5 min)
    • AES-256-GCM encryption for shared secrets at rest
    • Worker API key authentication
    • Dockerfile + K8s Deployment + Service manifests
    • 30 unit tests covering all components
  • Kubernetes manifests for ArgoCD GitOps (deploy/k8s/)
    • namespace.yaml - Dedicated ai-code-battle namespace
    • argocd-application.yaml - Auto-sync with prune and self-heal
    • deployments/acb-api.yaml - Go API (2 replicas, :8080)
    • deployments/acb-worker.yaml - Match worker (2 replicas, metrics on :9090)
    • deployments/acb-index-builder.yaml - Index builder (1 replica, Recreate strategy)
    • deployments/acb-strategy-{random,gatherer,rusher,guardian,swarm,hunter}.yaml - 6 strategy bots
    • services/acb-api.yaml - ClusterIP service for Go API
    • services/acb-strategy-*.yaml - ClusterIP services for bot DNS resolution
    • sealed-secrets/ - Templates for API key, R2 creds, bot secrets, Cloudflare token
    • All containers from forgejo.ardenone.com/ai-code-battle/ registry
    • Health/readiness probes and resource limits on all deployments
  • Traefik IngressRoute + TLS (deploy/k8s/ingress/)
    • acb-api-ingressroute.yaml - IngressRoute for api.aicodebattle.com (websecure entrypoint)
    • CORS middleware: allow origins for aicodebattle.com, security headers (nosniff, DENY, strict-origin)
    • Rate limiting middleware: 100 req/min, burst 200
    • acb-api-certificate.yaml - cert-manager Certificate (Let's Encrypt prod, ECDSA P-256)
  • Argo Events + Workflows CI/CD pipeline (deploy/k8s/ci/)
    • event-source.yaml - Webhook EventSource (port 12000)
    • sensor.yaml - Sensor triggers on master push, submits build-all DAG Workflow
    • workflow-template-build-image.yaml - Kaniko build with layer caching for container images
    • workflow-template-build-site.yaml - npm build for web SPA (outputs dist/ artifact)
    • service-account.yaml - CI ServiceAccount + RBAC (pods, workflows access)
    • DAG builds all 10 images in parallel: acb-api, acb-worker, acb-indexer, 6 strategy bots, plus site build
  • Registry credentials SealedSecret template (deploy/k8s/sealed-secrets/registry-credentials.yaml)
  • Discord/Slack alerting webhooks (cmd/acb-api/alerts.go)
    • Alerter module with Discord embeds and Slack attachments
    • Color-coded severity levels (info/warning/error)
    • Per-key rate limiting with configurable cooldown
    • Integrated into health checker and stale job reaper tickers
    • Helper methods for common alert events
    • 15 unit tests covering all functionality

Remaining Phase 6 Work (requires Cloudflare account access)

  • Cloudflare Pages project creation and deployment
  • R2 bucket creation and custom domain
  • Worker API deployment via Wrangler (wrangler deploy)
  • DNS configuration

Phase 5 Completed ✅

  • SPA application shell (web/app.html)
    • Navigation header with links to all sections
    • Dark theme with CSS custom properties
    • Responsive layout
  • Hash-based router (web/src/router.ts)
    • Pattern matching with parameter extraction
    • Navigation and history support
  • Page components (web/src/pages/)
    • Home page with hero, features, quick links
    • Leaderboard with ranking table
    • Match history with match cards
    • Bot directory with bot cards
    • Bot profile with stats, rating chart, recent matches
    • Registration form with API key display
    • Replay viewer (integrated from Phase 3)
    • Docs/Getting Started page
  • API client (web/src/api-types.ts)
    • fetchLeaderboard()
    • fetchBotDirectory()
    • fetchBotProfile()
    • fetchMatchIndex()
    • registerBot()
    • rotateApiKey()
  • Cloudflare Pages deployment configuration
    • web/pages.json - Project configuration
    • web/public/_headers - Cache control headers
    • web/public/robots.txt - SEO
    • web/public/data/ - Placeholder index file structure
  • R2 bucket custom domain documentation
    • Documented in web/pages.json data_paths section

Phase 7 Completed ✅

  • Evolution pipeline (cmd/acb-evolver/)
    • Programs database with island model (4 islands)
    • MAP-Elites behavior grid integration
    • Validation pipeline: syntax → schema → sandbox smoke test
    • Evaluation arena: 10-match mini-tournament
    • Promotion gate: Nash equilibrium computation + MAP-Elites niche fill
    • Retirement policy: auto-retire low-rated evolved bots
    • Live export: generates live.json for dashboard
  • LLM integration (cmd/acb-evolver/internal/llm/)
    • Prompt builder for parent sampling and replay analysis
    • Ensemble support (fast + strong model tiers)
  • Selector and prompt modules for evolution

Phase 8 Completed ✅

  • WASM game engine (cmd/acb-wasm/)
    • GOOS=js GOARCH=wasm build with JS bindings
    • loadState(), step(), runMatch() API
    • Pre-compiled strategy bot WASM builds
  • In-browser sandbox (web/src/pages/sandbox.ts)
    • Monaco editor with TypeScript quick-start
    • WASM upload mode
    • Opponent selector + replay viewer integration
  • Win probability computation (web/src/win-probability.ts)
    • Monte Carlo rollout
    • Critical moments detection
  • Replay commentary (web/src/commentary.ts)
    • AI-generated commentary for featured matches
  • Clip maker (web/src/pages/clip-maker.ts)
    • GIF + MP4 export
    • 5 social media format presets
  • Rivalry detection (web/src/pages/rivalries.ts)
    • Rival detection query
    • Template-generated narratives
  • Replay feedback system (web/src/pages/feedback.ts)
    • Tagged annotations
    • Feeds evolution pipeline

Phase 9 In Progress 🔄

  • Predictions API (cmd/acb-api/predictions.go)
    • PostgreSQL predictions table
    • Submit + resolve endpoints
  • Series management (cmd/acb-api/series.go)
    • PostgreSQL series/series_games tables
    • Multi-game series scheduler
  • Seasons API (cmd/acb-api/seasons.go)
    • PostgreSQL seasons table
    • Ladder reset logic
  • Narrative generator (cmd/acb-indexer/src/narrative.ts)
    • Rivalry narrative templates
  • Embeddable replay widget (web/embed.html, web/src/embed.ts)
    • /embed/{match_id} route on static site
    • Minimal chrome, auto-play, ~7KB gzipped
    • Open Graph tags, Twitter Card player
    • Progress bar, speed control, keyboard shortcuts
    • Score overlay, match end overlay
    • R2 warm cache + B2 cold archive fallback
  • Replay playlists (cmd/acb-indexer/src/playlists.ts, web/src/pages/playlists.ts)
    • Auto-curated collections: featured, upsets, comebacks, domination, close games, long games, weekly
    • Index builder generates playlists from match data
    • SPA page for browsing playlists
    • Embed code copy button
    • Placeholder data directory
  • Map evolution pipeline (cmd/acb-map-evolver/)
    • Parent selection by engagement × vote multiplier
    • Crossover breeding with sector-based inheritance
    • Symmetry-preserving mutation
    • Validation: connectivity, density, energy access
    • PostgreSQL tables: maps, map_votes, map_fairness
  • Bot profile cards

Phase 4 Completed

Phase 3 Completed

Phase 2 Completed

Phase 5 Exit Criteria

Criterion Status
SPA with navigation (leaderboard, matches, bots, register) ✅ Complete
Home page with getting started info ✅ Complete
Registration form with API key display ✅ Complete
Bot profiles with rating history chart ✅ Complete
Match history page ✅ Complete
Leaderboard with rankings ✅ Complete
Getting started / docs page ✅ Complete
Cloudflare Pages deployment config ✅ Complete
R2 bucket custom domain for replays ✅ Documented

Phase 1 Completed

File Structure

ai-code-battle/
├── go.mod
├── go.sum
├── .env.example              # Environment configuration template
├── DEPLOYMENT.md             # Deployment guide
├── docker-compose.bots.yml   # Bot-host orchestration
├── docker-compose.workers.yml # Worker orchestration
├── .github/
│   └── workflows/
│       └── ci.yml            # GitHub Actions CI workflow
├── engine/
│   ├── types.go        # Core data types
│   ├── grid.go         # Toroidal grid implementation
│   ├── game.go         # Game state management
│   ├── turn.go         # Turn execution phases
│   ├── replay.go       # Replay recording
│   ├── match.go        # Match runner
│   ├── bot_local.go    # Local bot interface
│   ├── bot_http.go     # HTTP bot client
│   ├── auth.go         # HMAC authentication
│   └── *_test.go       # Test files
├── cmd/
│   ├── acb-api/        # Go API server (K8s-native)
│   │   ├── main.go      # Server entry point
│   │   ├── server.go    # Route registration
│   │   ├── config.go    # Environment configuration
│   │   ├── db.go        # PostgreSQL schema
│   │   ├── health.go    # Health/ready endpoints
│   │   ├── register.go  # Bot registration, key rotation, status
│   │   ├── jobs.go      # Job claim and result submission
│   │   ├── glicko2.go   # Glicko-2 rating system
│   │   ├── crypto.go    # ID generation, AES-256-GCM encryption
│   │   ├── tickers.go   # Matchmaker, health checker, stale reaper
│   │   ├── Dockerfile   # API container
│   │   └── *_test.go    # Test files (30 tests)
│   ├── acb-local/      # CLI match runner
│   ├── acb-mapgen/     # Map generator
│   ├── acb-worker/     # Match execution worker
│   │   ├── main.go      # Worker entry point
│   │   ├── api.go       # Worker API client
│   │   ├── api_test.go  # API client tests
│   │   ├── r2.go        # R2 upload client
│   │   └── Dockerfile   # Worker container
│   └── acb-indexer/    # Index builder
│       ├── package.json
│       ├── Dockerfile
│       └── src/
│           ├── index.ts       # Entry point
│           ├── api.ts         # Worker API client
│           ├── generator.ts   # Index file generator
│           ├── writer.ts      # File system writer
│           ├── narrative.ts   # Rivalry narrative generator
│           └── generator.test.ts
├── cmd/
│   ├── acb-evolver/    # Evolution pipeline
│   │   ├── main.go      # CLI entry point
│   │   └── internal/
│   │       ├── db/       # Programs database
│   │       ├── arena/    # Tournament evaluation
│   │       ├── validator/# 3-stage validation
│   │       ├── promoter/ # Promotion gate
│   │       ├── selector/ # Parent sampling
│   │       ├── prompt/   # LLM prompt builder
│   │       ├── llm/      # LLM client
│   │       ├── mapelites/ # Behavior grid
│   │       └── live/     # Dashboard export
│   ├── acb-wasm/       # WASM game engine
│   │   ├── main.go      # JS bindings
│   │   ├── bots.go      # Bot interface
│   │   ├── build.sh     # Build script
│   │   ├── strategies/  # Strategy implementations
│   │   └── botmain/     # Per-bot main packages
│   └── acb-matchmaker/ # Internal matchmaker
│       ├── main.go      # Ticker orchestration
│       ├── tickers.go   # Pairing, health, reaping
│       ├── config.go    # Configuration
│       ├── crypto.go    # Shared crypto
│       └── alerts.go    # Discord/Slack alerts
├── worker-api/
│   ├── package.json    # npm dependencies
│   ├── wrangler.toml   # Cloudflare Worker config
│   ├── schema.sql      # Complete D1 schema (all tables)
│   ├── migrations/     # D1 migration files
│   │   └── 0001_initial.sql
│   └── src/
│       ├── index.ts        # Router + cron dispatcher
│       ├── types.ts        # TypeScript types
│       ├── glicko2.ts      # Glicko-2 rating system
│       ├── glicko2.test.ts # Rating system tests
│       ├── jobs.ts         # Job coordination endpoints
│       ├── bots.ts         # Bot management endpoints
│       ├── export.ts       # Data export endpoint
│       └── cron.ts         # Cron handlers
├── web/
│   ├── package.json    # npm dependencies
│   ├── tsconfig.json   # TypeScript config
│   ├── vite.config.ts  # Vite bundler config
│   ├── pages.json      # Cloudflare Pages project config
│   ├── index.html      # Standalone replay viewer
│   ├── app.html        # SPA shell with navigation
│   ├── public/         # Static assets (copied to dist/)
│   │   ├── _headers    # Cloudflare cache headers
│   │   ├── robots.txt  # SEO
│   │   └── data/       # Placeholder index files
│   │       ├── leaderboard.json
│   │       ├── bots/index.json
│   │       └── matches/index.json
│   └── src/
│       ├── types.ts        # Replay type definitions
│       ├── api-types.ts    # API client and types
│       ├── router.ts       # Hash-based SPA router
│       ├── replay-viewer.ts # Canvas viewer class
│       ├── engine.ts       # Browser game engine
│       ├── commentary.ts   # AI replay commentary
│       ├── win-probability.ts # Monte Carlo win prob
│       ├── main.ts         # Standalone replay viewer
│       ├── app.ts          # SPA entry point
│       └── pages/          # SPA page components
│           ├── home.ts
│           ├── leaderboard.ts
│           ├── matches.ts
│           ├── bots.ts
│           ├── bot-profile.ts
│           ├── register.ts
│           ├── sandbox.ts      # In-browser bot editor
│           ├── evolution.ts    # Evolution dashboard
│           ├── clip-maker.ts   # GIF/MP4 export
│           ├── rivalries.ts    # Rivalry pages
│           └── feedback.ts     # Replay feedback
├── bots/
│   ├── random/         # Python - RandomBot
│   ├── gatherer/       # Go - GathererBot
│   ├── rusher/         # Rust - RusherBot
│   ├── guardian/       # PHP - GuardianBot
│   ├── swarm/          # TypeScript - SwarmBot
│   └── hunter/         # Java - HunterBot
├── cluster-configuration/
│   └── apexalgo-iad/
│       └── ai-code-battle/   # K8s manifests (ArgoCD GitOps, flat structure)
│           ├── namespace.yml
│           ├── argocd-application.yml
│           ├── acb-worker-deployment.yml
│           ├── acb-api-deployment.yml + service.yml
│           ├── acb-index-builder-deployment.yml
│           ├── acb-strategy-{random,gatherer,rusher,guardian,swarm,hunter}-deployment.yml + service.yml
│           ├── acb-api-ingressroute.yml (Traefik + Middlewares)
│           ├── acb-api-certificate.yml
│           ├── acb-ci-{eventsource,sensor,serviceaccount}.yml
│           ├── acb-build-{image,site}-workflowtemplate.yml
│           └── acb-*-sealedsecret.yml (5 SealedSecret templates)
└── docs/
    └── plan/
        └── plan.md     # Full implementation plan

Strategy Bot Summary

Bot Language Strategy Expected Rank
RandomBot Python Random valid moves 6th (floor)
GathererBot Go Energy collection, avoid combat 4th-5th
RusherBot Rust Rush enemy cores aggressively 4th-5th
GuardianBot PHP Defend cores, cautious expansion 3rd-4th
SwarmBot TypeScript Formation cohesion, group advance 1st-2nd
HunterBot Java Target isolated enemies 1st-2nd

Running Tests

# Go engine tests
go test ./engine/... -v

# Web build verification
cd web && npm run build

Building CLI Tools

go build ./cmd/acb-local
go build ./cmd/acb-mapgen

Running a Match

./acb-local -seed 42 -max-turns 100 -output replay.json -verbose

Viewing a Replay

cd web
npm run dev
# Standalone viewer: http://localhost:3000/index.html
# Full SPA: http://localhost:3000/app.html (then go to #/replay)