# bytadaniel/open-datsmagic architecture

> Architecture diagram of the GitHub repository bytadaniel/open-datsmagic, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bytadaniel/open-datsmagic
- Repository: https://github.com/bytadaniel/open-datsmagic

## Overview

StadMagic is a multi-service arena game: teams register and receive tokens through a web Hub, then bots submit commands to a Rust simulation API. The Hub also selects worlds, controls arena lifecycle, and presents standings; browser and native visualizers expose spectator and manual-play experiences. The graph separates platform, simulation stages, and clients. Hub capabilities and service links are based on the README; server internals use the supplied source excerpts and SOURCE INDEX, so unsampled implementation details are not expanded.

Main entry points: [`modules/arena-hub/hub.py`](https://github.com/bytadaniel/open-datsmagic/blob/master/modules/arena-hub/hub.py) (Web Hub), [`lib/arena-server/src/engine/loop_runner.rs`](https://github.com/bytadaniel/open-datsmagic/blob/master/lib/arena-server/src/engine/loop_runner.rs) (Game loop), [`lib/arena-server/src/spatial/manager.rs`](https://github.com/bytadaniel/open-datsmagic/blob/master/lib/arena-server/src/spatial/manager.rs) (Spatial resolution), [`lib/arena-server/src/api/handlers.rs`](https://github.com/bytadaniel/open-datsmagic/blob/master/lib/arena-server/src/api/handlers.rs) (Arena API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_platform["Arena platform"]
  node_hub["Web Hub<br/>[hub.py]"]
  node_browser["Hub browser UI"]
  node_runtime["Arena lifecycle<br/>[runtime.py]"]
end

subgraph group_simulation["Simulation server"]
  node_arena["Arena API<br/>[handlers.rs]"]
  node_dto["API contracts<br/>[dto.rs]"]
  node_engine["Game loop<br/>[loop_runner.rs]"]
  node_commands["Command buffer<br/>[command_buffer.rs]"]
  node_state[("World state<br/>[state.rs]")]
  node_config["World configuration<br/>[config.rs]"]
  node_leaderboard["Session leaderboard<br/>[leaderboard.rs]"]
end

subgraph group_world["World mechanics"]
  node_physics["Physics integration<br/>[integrator.rs]"]
  node_forces["Forces and vectors<br/>[forces.rs]"]
  node_vector["2D vectors<br/>[vector2d.rs]"]
  node_spatial["Spatial resolution<br/>[manager.rs]"]
  node_entities["World entities<br/>[entities.rs]"]
  node_collisions["Collision detection"]
  node_coins["Coin spawning<br/>[coin_spawner.rs]"]
  node_anomalies["Anomaly spawning<br/>[spawner.rs]"]
end

subgraph group_clients["Players and viewers"]
  node_bot["Bot clients"]
end

subgraph group_visualization["Visualization"]
  node_webviz["Browser arena view"]
  node_nativeviz["Native visualizer<br/>[main.rs]"]
end

node_team(("Teams"))

node_team -->|"registers"| node_hub
node_hub -->|"issues tokens"| node_team
node_bot -->|"submits commands"| node_arena
node_hub -->|"controls lifecycle"| node_runtime
node_runtime -->|"starts process"| node_arena
node_hub -->|"serves web app"| node_browser
node_browser -.->|"plays arena"| node_arena
node_browser -.->|"views standings"| node_hub
node_arena -->|"registers commands"| node_engine
node_arena -->|"formats responses"| node_dto
node_engine -->|"drains commands"| node_commands
node_engine -->|"advances state"| node_state
node_engine -->|"steps physics"| node_physics
node_engine -->|"resolves world"| node_spatial
node_engine -->|"loads settings"| node_config
node_physics -->|"uses forces"| node_forces
node_physics -->|"uses vectors"| node_vector
node_forces -->|"uses vectors"| node_vector
node_physics -->|"reads anomaly forces"| node_spatial
node_spatial -->|"resolves entities"| node_entities
node_spatial -->|"checks collisions"| node_collisions
node_spatial -->|"spawns coins"| node_coins
node_spatial -->|"spawns anomalies"| node_anomalies
node_nativeviz -->|"reads game state"| node_arena
node_nativeviz -->|"reads standings"| node_hub
node_team -->|"manually controls"| node_nativeviz
node_hub -.->|"presents standings"| node_leaderboard

click node_bot "https://github.com/bytadaniel/open-datsmagic/tree/master/lib/arena-bots"
click node_hub "https://github.com/bytadaniel/open-datsmagic/blob/master/modules/arena-hub/hub.py"
click node_browser "https://github.com/bytadaniel/open-datsmagic/blob/master/modules/arena-hub/static/arena-visualizer.js"
click node_runtime "https://github.com/bytadaniel/open-datsmagic/blob/master/modules/arena-runtime/runtime.py"
click node_arena "https://github.com/bytadaniel/open-datsmagic/blob/master/lib/arena-server/src/api/handlers.rs"
click node_dto "https://github.com/bytadaniel/open-datsmagic/blob/master/lib/arena-server/src/api/dto.rs"
click node_engine "https://github.com/bytadaniel/open-datsmagic/blob/master/lib/arena-server/src/engine/loop_runner.rs"
click node_commands "https://github.com/bytadaniel/open-datsmagic/blob/master/lib/arena-server/src/engine/command_buffer.rs"
click node_state "https://github.com/bytadaniel/open-datsmagic/blob/master/lib/arena-server/src/engine/state.rs"
click node_config "https://github.com/bytadaniel/open-datsmagic/blob/master/lib/arena-server/src/config.rs"
click node_leaderboard "https://github.com/bytadaniel/open-datsmagic/blob/master/lib/arena-server/src/leaderboard.rs"
click node_physics "https://github.com/bytadaniel/open-datsmagic/blob/master/lib/arena-server/src/physics/integrator.rs"
click node_forces "https://github.com/bytadaniel/open-datsmagic/blob/master/lib/arena-server/src/physics/forces.rs"
click node_vector "https://github.com/bytadaniel/open-datsmagic/blob/master/lib/arena-server/src/physics/vector2d.rs"
click node_spatial "https://github.com/bytadaniel/open-datsmagic/blob/master/lib/arena-server/src/spatial/manager.rs"
click node_entities "https://github.com/bytadaniel/open-datsmagic/blob/master/lib/arena-server/src/spatial/entities.rs"
click node_collisions "https://github.com/bytadaniel/open-datsmagic/blob/master/lib/arena-server/src/spatial/collision_detector.rs"
click node_coins "https://github.com/bytadaniel/open-datsmagic/blob/master/lib/arena-server/src/spatial/coin_spawner.rs"
click node_anomalies "https://github.com/bytadaniel/open-datsmagic/blob/master/lib/arena-server/src/spatial/spawner.rs"
click node_webviz "https://github.com/bytadaniel/open-datsmagic/blob/master/modules/arena-hub/static/arena-visualizer.js"
click node_nativeviz "https://github.com/bytadaniel/open-datsmagic/blob/master/lib/arena-visualizer/src/main.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_hub,node_browser,node_runtime toneBlue
class node_arena,node_dto,node_engine,node_commands,node_state,node_config,node_leaderboard toneAmber
class node_physics,node_forces,node_vector,node_spatial,node_entities,node_collisions,node_coins,node_anomalies toneMint
class node_bot toneRose
class node_webviz,node_nativeviz,node_team toneIndigo
```

## Components

### Arena platform

- [Web Hub](https://github.com/bytadaniel/open-datsmagic/blob/master/modules/arena-hub/hub.py): `modules/arena-hub/hub.py`
- [Hub browser UI](https://github.com/bytadaniel/open-datsmagic/blob/master/modules/arena-hub/static/arena-visualizer.js): `modules/arena-hub/static/arena-visualizer.js`
- [Arena lifecycle](https://github.com/bytadaniel/open-datsmagic/blob/master/modules/arena-runtime/runtime.py): `modules/arena-runtime/runtime.py`

### Simulation server

- [Arena API](https://github.com/bytadaniel/open-datsmagic/blob/master/lib/arena-server/src/api/handlers.rs): `lib/arena-server/src/api/handlers.rs`
- [API contracts](https://github.com/bytadaniel/open-datsmagic/blob/master/lib/arena-server/src/api/dto.rs): `lib/arena-server/src/api/dto.rs`
- [Game loop](https://github.com/bytadaniel/open-datsmagic/blob/master/lib/arena-server/src/engine/loop_runner.rs): `lib/arena-server/src/engine/loop_runner.rs`
- [Command buffer](https://github.com/bytadaniel/open-datsmagic/blob/master/lib/arena-server/src/engine/command_buffer.rs): `lib/arena-server/src/engine/command_buffer.rs`
- [World state](https://github.com/bytadaniel/open-datsmagic/blob/master/lib/arena-server/src/engine/state.rs): `lib/arena-server/src/engine/state.rs`
- [World configuration](https://github.com/bytadaniel/open-datsmagic/blob/master/lib/arena-server/src/config.rs): `lib/arena-server/src/config.rs`
- [Session leaderboard](https://github.com/bytadaniel/open-datsmagic/blob/master/lib/arena-server/src/leaderboard.rs): `lib/arena-server/src/leaderboard.rs`

### World mechanics

- [Physics integration](https://github.com/bytadaniel/open-datsmagic/blob/master/lib/arena-server/src/physics/integrator.rs): `lib/arena-server/src/physics/integrator.rs`
- [Forces and vectors](https://github.com/bytadaniel/open-datsmagic/blob/master/lib/arena-server/src/physics/forces.rs): `lib/arena-server/src/physics/forces.rs`
- [2D vectors](https://github.com/bytadaniel/open-datsmagic/blob/master/lib/arena-server/src/physics/vector2d.rs): `lib/arena-server/src/physics/vector2d.rs`
- [Spatial resolution](https://github.com/bytadaniel/open-datsmagic/blob/master/lib/arena-server/src/spatial/manager.rs): `lib/arena-server/src/spatial/manager.rs`
- [World entities](https://github.com/bytadaniel/open-datsmagic/blob/master/lib/arena-server/src/spatial/entities.rs): `lib/arena-server/src/spatial/entities.rs`
- [Collision detection](https://github.com/bytadaniel/open-datsmagic/blob/master/lib/arena-server/src/spatial/collision_detector.rs): `lib/arena-server/src/spatial/collision_detector.rs`
- [Coin spawning](https://github.com/bytadaniel/open-datsmagic/blob/master/lib/arena-server/src/spatial/coin_spawner.rs): `lib/arena-server/src/spatial/coin_spawner.rs`
- [Anomaly spawning](https://github.com/bytadaniel/open-datsmagic/blob/master/lib/arena-server/src/spatial/spawner.rs): `lib/arena-server/src/spatial/spawner.rs`

### Players and viewers

- [Bot clients](https://github.com/bytadaniel/open-datsmagic/tree/master/lib/arena-bots): `lib/arena-bots`

### Visualization

- [Browser arena view](https://github.com/bytadaniel/open-datsmagic/blob/master/modules/arena-hub/static/arena-visualizer.js): `modules/arena-hub/static/arena-visualizer.js`
- [Native visualizer](https://github.com/bytadaniel/open-datsmagic/blob/master/lib/arena-visualizer/src/main.rs): `lib/arena-visualizer/src/main.rs`

### Other components

- **Teams**

## Connections

- Teams → Web Hub: registers (evidence: `README.md`)
- Web Hub → Teams: issues tokens (evidence: `README.md`)
- Bot clients → Arena API: submits commands (evidence: `README.md`)
- Web Hub → Arena lifecycle: controls lifecycle (evidence: `README.md`)
- Arena lifecycle → Arena API: starts process (evidence: `README.md`)
- Web Hub → Hub browser UI: serves web app (evidence: `README.md`)
- Hub browser UI → Arena API: plays arena (evidence: `README.md`)
- Hub browser UI → Web Hub: views standings (evidence: `README.md`)
- Arena API → Game loop: registers commands (evidence: `lib/arena-server/src/api/handlers.rs`)
- Arena API → API contracts: formats responses (evidence: `lib/arena-server/src/api/handlers.rs`)
- Game loop → Command buffer: drains commands (evidence: `lib/arena-server/src/engine/loop_runner.rs`)
- Game loop → World state: advances state (evidence: `lib/arena-server/src/engine/loop_runner.rs`)
- Game loop → Physics integration: steps physics (evidence: `lib/arena-server/src/engine/loop_runner.rs`)
- Game loop → Spatial resolution: resolves world (evidence: `lib/arena-server/src/engine/loop_runner.rs`)
- Game loop → World configuration: loads settings (evidence: `lib/arena-server/src/engine/loop_runner.rs`)
- Physics integration → Forces and vectors: uses forces (evidence: `lib/arena-server/src/physics/integrator.rs`)
- Physics integration → 2D vectors: uses vectors (evidence: `lib/arena-server/src/physics/integrator.rs`)
- Forces and vectors → 2D vectors: uses vectors (evidence: `lib/arena-server/src/physics/forces.rs`)
- Physics integration → Spatial resolution: reads anomaly forces
- Spatial resolution → World entities: resolves entities (evidence: `lib/arena-server/src/spatial/manager.rs`)
- Spatial resolution → Collision detection: checks collisions (evidence: `lib/arena-server/src/spatial/manager.rs`)
- Spatial resolution → Coin spawning: spawns coins (evidence: `lib/arena-server/src/spatial/manager.rs`)
- Spatial resolution → Anomaly spawning: spawns anomalies (evidence: `lib/arena-server/src/spatial/manager.rs`)
- Native visualizer → Arena API: reads game state (evidence: `README.md`)
- Native visualizer → Web Hub: reads standings (evidence: `README.md`)
- Teams → Native visualizer: manually controls (evidence: `README.md`)
- Web Hub → Session leaderboard: presents standings (evidence: `README.md`)
