How aiarena/aiarena-web works
1. Overall shape
- This is a monolithic Django application with multiple presentation layers, a service layer, background workers, and a set of operational scripts for AWS deployment.
- The main runtime is Python/Django; the modern UI is a separate React + TypeScript SPA under aiarena/frontend-spa, while the older site still uses Django templates and classic views.
2. Core domain backend
- The central business data lives in aiarena/core/models: bots, competitions, matches, rounds, results, map pools, arena clients, users, trophies, and related statistics.
- aiarena/core/services and aiarena/core/services/service_implementations are the main domain orchestration layer. They separate “business operations” like matches, ladders, bots, supporters, arena clients, and internal match/round/statistics flows from the view layer.
3. Primary data store
- PostgreSQL is the authoritative store for all domain data.
- The repo contains a long migration history in aiarena/core/migrations and aiarena/patreon/migrations, showing that schema evolution is a major part of the system.
- There are also storage helpers for file-backed entities such as bot uploads, replays, logs, and map assets.
4. External file/object storage
- The application uses file uploads and downloads heavily: bot zip files, match logs, replays, map files, images, and static media.
- aiarena/core/s3_helpers.py and deployment/backup tooling indicate S3 is used for backups and likely other object storage flows.
- The presence of media/, private-media/, and download views for bot zips/logs/replays indicates a clear boundary between public static assets and private generated artifacts.
5. Background execution and asynchronous work
- aiarena/celery.py, aiarena/core/tasks.py, and the worker scripts show a Celery-based async layer backed by Redis.
- This layer is used for operational work such as match lifecycle management, timeouts, stats generation, cleanup, backup-related tasks, and other deferred processing that should not happen in request/response paths.
6. Arena client subsystem
- aiarena/api/arenaclient is a dedicated API surface for external “arena clients” that connect to the platform, submit results, exchange match-related data, and report status.
- It has versioned APIs (v1, v2, v3), indicating compatibility boundaries for different client generations.
- The tests and integration test harness in aiarena/api/arenaclient/integration_tests suggest this is a critical external integration point, not just an internal endpoint.
7. Public API and GraphQL
- aiarena/api contains the REST-style API surface used by the site and clients, with many view modules grouped by domain: bots, matches, competitions, users, map pools, results, news, permissions, etc.
- aiarena/graphql provides a GraphQL schema and mutations, and aiarena/frontend/views/graphql.py indicates the frontend consumes GraphQL for the SPA.
- The SPA workflow in the README explicitly requires generating the schema, which means GraphQL is a first-class contract between backend and React frontend.
8. User-facing web layer
- The legacy Django web UI lives in aiarena/frontend/views and aiarena/frontend/templates, with a large set of page-specific views for authors, bots, matches, competitions, rounds, profiles, match queues, and downloads.
- aiarena/frontend/dashboard.py, forms, context processors, and template tags support the server-rendered site.
- This layer remains important for downloads, admin-like workflows, and pages that have not moved to the SPA.
9. Modern SPA frontend
- aiarena/frontend-spa is a separate React application built with TypeScript, Vite, Tailwind, Relay, and a substantial component/page structure.
- It is organized around reusable components, layouts, hooks, and page modules for authors, bots, competitions, competition participation stats, results, user bots, match requests, settings, and landing pages.
- The SPA talks to the backend primarily through GraphQL, and the Relay-specific context/hooks show that the data-fetch boundary is intentionally centralized.
10. Live/streaming features
- The aiarena/api/stream app and the frontend’s relay connection context imply a real-time or near-real-time update channel for live UI features.
- This is likely used for things like live match queues, matchmaking state, or streamed updates without requiring full page reloads.
11. Operational and maintenance workflows
- aiarena/core/management/commands contains a large set of domain-specific maintenance jobs: seeding, match cancellation, timeout handling, cleanup, repair/check of bot hashes, competition finalization, stats generation, and user migration.
- These commands are part of the architecture, not just tooling: they encode the offline lifecycle of competitions, matches, and bot artifacts.
12. Authentication, permissions, and integrations
- The backend has dedicated auth and permission modules, plus user/Discord/Patreon-related views and models.
- aiarena/patreon and related templates show an external supporter/account-linking integration.
- Discord linking and Patreon account binding are separate functional boundaries layered on top of the core user model.
13. Deployment and infrastructure
- Production runs in AWS ECS/Fargate, with Docker images built and deployed via GitHub Actions.
- deploy/ contains AWS, ECS, Docker, and CloudFormation generation logic; docker/ contains runtime images; nginx/ is the edge reverse proxy configuration.
- The deployment flow is: build image, push to ECR, run migrations, roll ECS services, then monitor the rollout.
14. Testing strategy
- The repo has substantial automated coverage across backend, API, service-layer logic, GraphQL, and frontend behavior.
- There are Django unit/integration tests, service tests, Playwright browser tests, API tests with fixture media, and arena-client integration test scaffolding.
- This indicates the architecture is validated at several boundaries: domain logic, HTTP contracts, and user-facing flows.
15. Diagram-friendly boundary summary
- At a high level, draw these main zones: browser SPA / legacy web UI, Django application layer, core domain services + models, Celery worker, PostgreSQL, Redis, S3/object storage, and external arena clients.
- The most important flows are: browser → GraphQL/REST/Django → PostgreSQL; arena clients → versioned arena-client API → match/result processing; Django/Celery → async jobs and maintenance; application → S3 for backups and file artifacts; deployment pipeline → Docker/ECS.
Main entry points: aiarena/urls.py Django app · api/urls.py REST API · arenaclient/urls.py Arena client API · __init__.py Core models
Components 17
Backend
Django app, domain logic, APIs, and async work
- Django app · Main Django runtime and URL entrypoints
aiarena/urls.py - REST API · Site and client API endpoints by domain
aiarena/api/urls.py - Arena client API · External arena-client contract with v1/v2/v3 surfaces
aiarena/api/arenaclient/urls.py - GraphQL · Backend GraphQL schema and mutations used by the SPA
aiarena/graphql/mutations.py - Core models · Competitions, matches, bots, results, users, and related state
aiarena/core/models/__init__.py - Domain services · Business workflows for bots, matches, competitions, ladders, and supporters
aiarena/core/services/service_implementations/__init__.py - Match internals · Lower-level match, round, request, map, and statistics coordination
aiarena/core/services/service_implementations/internal/matches.py
Frontends
Legacy server-rendered UI and modern SPA
- Legacy UI · Classic Django templates, views, forms, and dashboard pages
aiarena/frontend/views/frontend.py - SPA frontend · React + TypeScript + Relay single-page application
aiarena/frontend-spa/src/App.tsx
Infra
Runtime services, storage, and deployment
- Celery worker · Deferred match lifecycle, cleanup, stats, and maintenance jobs
aiarena/celery.py - Ops commands · Offline repair, seeding, timeout, cleanup, and finalization commands
aiarena/core/management/commands/finalizecompetition.py - Deploy stack · Docker, ECS/Fargate, CloudFormation, and rollout tooling
deploy/aws.py - Nginx edge · Front-door web proxy configuration
nginx/nginx.conf
External systems
Datastores and outside clients
- PostgreSQL · Authoritative relational store for domain data
- Redis · Celery broker/backend and transient async coordination
- S3 / media · Bot uploads, replays, logs, maps, media, and backups
aiarena/core/s3_helpers.py - Arena clients · Third-party game runners that exchange match data and results
aiarena/api/arenaclient/common/views.py
Connections 23
- Django app → REST API: routes · Main Django URLconf includes the REST API
- Django app → Arena client API: routes · Main Django URLconf exposes arena-client endpoints
- Django app → GraphQL: routes · Main Django URLconf exposes GraphQL
- Django app → Legacy UI: serves · Legacy pages are rendered from Django views and templates
- SPA frontend → GraphQL: queries · SPA fetches backend data through GraphQL
- SPA frontend → REST API: calls · SPA also relies on backend API endpoints where needed
- REST API → Domain services: orchestrates · HTTP endpoints delegate business operations to domain services
- Arena client API → Domain services: orchestrates · Arena-client requests flow into match/result service logic
- GraphQL → Domain services: reads/writes · GraphQL resolvers and mutations use service-layer operations
- Domain services → Core models: uses · Services operate on the domain model layer
- Match internals → Core models: uses · Lower-level workflows coordinate model state and transitions
- Celery worker → Match internals: runs · Async tasks execute deferred match and statistics workflows
- Ops commands → Match internals: repairs · Management commands reuse the same internal operational flows
- Core models → PostgreSQL: persists · Domain state is stored in PostgreSQL
- Core models → S3 / media: stores files · Models reference uploads, replays, maps, and generated artifacts
- REST API → S3 / media: downloads/uploads · API exposes file-backed artifacts to users and clients
- Arena client API → S3 / media: exchanges files · Arena clients upload and download match-related files
- Celery worker → Redis: brokers · Celery uses Redis for queued background work
- Deploy stack → Nginx edge: publishes · Deployment includes the edge proxy configuration
- Deploy stack → Django app: rolls out · Containerized Django services are deployed through AWS tooling
- Arena clients → Arena client API: integrates · External arena clients connect to the versioned API
- Legacy UI → PostgreSQL: renders from · Server-rendered pages are backed by relational data
- SPA frontend → Nginx edge: served via · SPA traffic is delivered behind the web proxy