How hp6/ai-arena works
Tiny AI Arena is a browser-based spectator and replay app for four-model battles on an 8×8 grid. A spectator starts a match from the menu; the API starts a background game loop, which requests model actions, validates and resolves turns, and saves frames for live viewing and later replay. The client also presents leaderboard and match history, while recorded matches can be exported for offline static viewing. The graph follows sampled call sites and README-documented features; unsampled internals are represented only where their paths are supported by the tree.
Main entry points: GameRunner.ts Game loop · database.ts SQLite records · ArenaScene.ts Replay scene · OpenRouterClient.ts OpenRouter client
Components 26
Spectator client
- Client startup
client/src/main.ts - App shell
client/src/ui/AppShell.ts - Menu and stats
client/src/ui/MenuView.ts - Replay scene
client/src/scenes/ArenaScene.ts - Arena renderer
client/src/objects/Arena.ts - Fighter renderer
client/src/objects/Fighter.ts - Arena HUD
client/src/ui/ArenaHud.ts - API URLs
client/src/utils/api.ts
Match server
- Server startup
server/src/index.ts - Game API
server/src/routes/game.ts - Leaderboard stats
server/src/stats.ts - Replay export
server/src/export.ts
Game and AI
- Game loop
server/src/game/GameRunner.ts - Game setup
server/src/game/GameState.ts - Action referee
server/src/game/MoveValidator.ts - Combat resolver
server/src/game/CombatResolver.ts - Model roster
server/src/ai/AgentConfig.ts - Prompt builder
server/src/ai/PromptBuilder.ts - Move schema
server/src/ai/MoveSchema.ts - OpenRouter client
server/src/ai/OpenRouterClient.ts - Shared game types
shared/src/index.ts
Match records
- SQLite records
server/src/db/database.ts
Other components
- Spectator
- HTTP client
- OpenRouter
- Arena database
Connections 31
- Spectator → Menu and stats: uses
- Client startup → App shell: creates
- App shell → Menu and stats: shows
- App shell → Replay scene: switches to
- Menu and stats → API URLs: requests stats
- Menu and stats → Replay scene: selects match
- Replay scene → API URLs: requests game data
- Replay scene → Arena renderer: renders board
- Replay scene → Fighter renderer: renders fighters
- Replay scene → Arena HUD: updates display
- API URLs → HTTP client: sends requests
- HTTP client → Server startup: calls API
- Server startup → Game API: mounts routes
- Server startup → Leaderboard stats: computes stats
- Game API → Game loop: starts match
- Game API → SQLite records: reads records
- Game loop → Game setup: creates state
- Game loop → Model roster: selects models
- Game loop → OpenRouter client: requests moves
- Game loop → Action referee: validates actions
- Game loop → Combat resolver: resolves attacks
- Game loop → SQLite records: writes frames
- OpenRouter client → Prompt builder: builds prompts
- OpenRouter client → Move schema: formats moves
- OpenRouter client → OpenRouter: requests completion
- OpenRouter client → SQLite records: logs calls
- Server startup → SQLite records: initializes records
- Leaderboard stats → SQLite records: reads match data
- Replay export → SQLite records: exports matches
- SQLite records → Arena database: reads and writes
- Shared game types → Game loop: defines game types