# caesar723/magic architecture

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

- Interactive diagram: https://gitdiagram.com/caesar723/magic
- Repository: https://github.com/caesar723/magic

## Overview

Magic-Fan-Made is a collectible card-game application with account/deck management, matchmaking, live games, shops and a roguelike mode. The primary workflow is an authenticated player selecting a validated deck, entering matchmaking, and playing through a game room. The repository also contains an extensive reinforcement-learning training and inference stack and a synthesis-artifact viewer. Edges reflect the sampled server, database, inference and viewer code; internal game-room and training wiring is only included where supported by module responsibilities and paths.

Main entry points: [`src/server.py`](https://github.com/caesar723/magic/blob/main/src/server.py) (Web API), [`src/game/room.py`](https://github.com/caesar723/magic/blob/main/src/game/room.py) (Game rooms), [`src/game/rlearning/train.py`](https://github.com/caesar723/magic/blob/main/src/game/rlearning/train.py) (RL training), [`src/game/room_server.py`](https://github.com/caesar723/magic/blob/main/src/game/room_server.py) (Room matchmaking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web and accounts"]
  node_server["Web API<br/>[server.py]"]
  node_db[("Game database<br/>[database.py]")]
end

subgraph group_game["Game runtime"]
  node_room_server["Room matchmaking<br/>[room_server.py]"]
  node_room["Game rooms<br/>[room.py]"]
  node_player_model["Player state<br/>[player.py]"]
  node_card_model["Card rules<br/>[card.py]"]
  node_card_defs["Card definitions"]
  node_studio["Game studio<br/>[studio_room.py]"]
end

subgraph group_rogue["Roguelike mode"]
  node_rogue_room["Rogue rooms<br/>[rogue_room.py]"]
  node_rogue_manager["Rogue map<br/>[rogue_manager.py]"]
end

subgraph group_rl["Learning and analysis"]
  node_rl_train["RL training<br/>[train.py]"]
  node_parallel_env["Parallel environments"]
  node_rollout["Rollout workers<br/>[rollout_agent.py]"]
  node_inference_client["Inference client<br/>[client.py]"]
  node_inference_server["Batched inference<br/>[server.py]"]
  node_policy["Policy models"]
  node_synthesis["Synthesis artifacts"]
  node_viewer["Artifact viewer<br/>[app.py]"]
  node_artifact_repo["Artifact repository<br/>[repository.py]"]
end

node_player(("Player"))

node_player -->|"uses"| node_server
node_server -->|"authenticates; loads decks"| node_db
node_server -->|"requests matchmaking"| node_room_server
node_room_server -->|"assigns game room"| node_room
node_room -->|"updates state"| node_player_model
node_room -->|"resolves card actions"| node_card_model
node_card_model -->|"uses definitions"| node_card_defs
node_server -->|"reads shop and account data"| node_db
node_server -->|"serves rogue play"| node_rogue_room
node_rogue_room -->|"builds map data"| node_rogue_manager
node_rl_train -->|"trains against"| node_parallel_env
node_parallel_env -->|"runs rollouts"| node_rollout
node_rollout -->|"requests actions"| node_inference_client
node_inference_client -->|"queues requests"| node_inference_server
node_inference_server -->|"loads and evaluates"| node_policy
node_rl_train -.->|"writes artifacts"| node_synthesis
node_player -->|"browses experiments"| node_viewer
node_viewer -->|"reads artifacts"| node_artifact_repo

click node_server "https://github.com/caesar723/magic/blob/main/src/server.py"
click node_db "https://github.com/caesar723/magic/blob/main/src/database.py"
click node_room_server "https://github.com/caesar723/magic/blob/main/src/game/room_server.py"
click node_room "https://github.com/caesar723/magic/blob/main/src/game/room.py"
click node_player_model "https://github.com/caesar723/magic/blob/main/src/game/player.py"
click node_card_model "https://github.com/caesar723/magic/blob/main/src/game/card.py"
click node_card_defs "https://github.com/caesar723/magic/tree/main/src/game/type_cards"
click node_studio "https://github.com/caesar723/magic/blob/main/src/game/studio_room.py"
click node_rogue_room "https://github.com/caesar723/magic/blob/main/src/game/rogue/rogue_room.py"
click node_rogue_manager "https://github.com/caesar723/magic/blob/main/src/game/rogue/rogue_manager.py"
click node_rl_train "https://github.com/caesar723/magic/blob/main/src/game/rlearning/train.py"
click node_parallel_env "https://github.com/caesar723/magic/tree/main/src/game/rlearning/parallel_env"
click node_rollout "https://github.com/caesar723/magic/blob/main/src/game/rlearning/rollout/rollout_agent.py"
click node_inference_client "https://github.com/caesar723/magic/blob/main/src/game/rlearning/inference/client.py"
click node_inference_server "https://github.com/caesar723/magic/blob/main/src/game/rlearning/inference/server.py"
click node_policy "https://github.com/caesar723/magic/tree/main/src/game/rlearning/module"
click node_synthesis "https://github.com/caesar723/magic/tree/main/src/game/rlearning/synthesis"
click node_viewer "https://github.com/caesar723/magic/blob/main/src/game/rlearning/synthesis_viewer/app.py"
click node_artifact_repo "https://github.com/caesar723/magic/blob/main/src/game/rlearning/synthesis_viewer/repository.py"

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_server,node_db toneBlue
class node_room_server,node_room,node_player_model,node_card_model,node_card_defs,node_studio toneAmber
class node_rogue_room,node_rogue_manager toneMint
class node_rl_train,node_parallel_env,node_rollout,node_inference_client,node_inference_server,node_policy,node_synthesis,node_viewer,node_artifact_repo toneRose
class node_player toneIndigo
```

## Components

### Web and accounts

- [Web API](https://github.com/caesar723/magic/blob/main/src/server.py): `src/server.py`
- [Game database](https://github.com/caesar723/magic/blob/main/src/database.py): `src/database.py`

### Game runtime

- [Room matchmaking](https://github.com/caesar723/magic/blob/main/src/game/room_server.py): `src/game/room_server.py`
- [Game rooms](https://github.com/caesar723/magic/blob/main/src/game/room.py): `src/game/room.py`
- [Player state](https://github.com/caesar723/magic/blob/main/src/game/player.py): `src/game/player.py`
- [Card rules](https://github.com/caesar723/magic/blob/main/src/game/card.py): `src/game/card.py`
- [Card definitions](https://github.com/caesar723/magic/tree/main/src/game/type_cards): `src/game/type_cards`
- [Game studio](https://github.com/caesar723/magic/blob/main/src/game/studio_room.py): `src/game/studio_room.py`

### Roguelike mode

- [Rogue rooms](https://github.com/caesar723/magic/blob/main/src/game/rogue/rogue_room.py): `src/game/rogue/rogue_room.py`
- [Rogue map](https://github.com/caesar723/magic/blob/main/src/game/rogue/rogue_manager.py): `src/game/rogue/rogue_manager.py`

### Learning and analysis

- [RL training](https://github.com/caesar723/magic/blob/main/src/game/rlearning/train.py): `src/game/rlearning/train.py`
- [Parallel environments](https://github.com/caesar723/magic/tree/main/src/game/rlearning/parallel_env): `src/game/rlearning/parallel_env`
- [Rollout workers](https://github.com/caesar723/magic/blob/main/src/game/rlearning/rollout/rollout_agent.py): `src/game/rlearning/rollout/rollout_agent.py`
- [Inference client](https://github.com/caesar723/magic/blob/main/src/game/rlearning/inference/client.py): `src/game/rlearning/inference/client.py`
- [Batched inference](https://github.com/caesar723/magic/blob/main/src/game/rlearning/inference/server.py): `src/game/rlearning/inference/server.py`
- [Policy models](https://github.com/caesar723/magic/tree/main/src/game/rlearning/module): `src/game/rlearning/module`
- [Synthesis artifacts](https://github.com/caesar723/magic/tree/main/src/game/rlearning/synthesis): `src/game/rlearning/synthesis`
- [Artifact viewer](https://github.com/caesar723/magic/blob/main/src/game/rlearning/synthesis_viewer/app.py): `src/game/rlearning/synthesis_viewer/app.py`
- [Artifact repository](https://github.com/caesar723/magic/blob/main/src/game/rlearning/synthesis_viewer/repository.py): `src/game/rlearning/synthesis_viewer/repository.py`

### Other components

- **Player**

## Connections

- Player → Web API: uses
- Web API → Game database: authenticates; loads decks
- Web API → Room matchmaking: requests matchmaking
- Room matchmaking → Game rooms: assigns game room
- Game rooms → Player state: updates state
- Game rooms → Card rules: resolves card actions
- Card rules → Card definitions: uses definitions
- Web API → Game database: reads shop and account data
- Web API → Rogue rooms: serves rogue play
- Rogue rooms → Rogue map: builds map data
- RL training → Parallel environments: trains against
- Parallel environments → Rollout workers: runs rollouts
- Rollout workers → Inference client: requests actions
- Inference client → Batched inference: queues requests
- Batched inference → Policy models: loads and evaluates
- RL training → Synthesis artifacts: writes artifacts
- Player → Artifact viewer: browses experiments
- Artifact viewer → Artifact repository: reads artifacts