# atcasanova/jogo architecture

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

- Interactive diagram: https://gitdiagram.com/atcasanova/jogo
- Repository: https://github.com/atcasanova/jogo

## Overview

Board Game Online is a four-player, two-team browser game, with a separate Python reinforcement-learning system and a Node.js game wrapper for training and bot inference. The main player flow is lobby and team setup, turn-based card and piece actions, then replay access after a finished game. The graph also shows the game rules engine and the AI training/inference branch. Source excerpts are partial, so uncertain internal wiring—especially replay persistence—is not drawn.

Main entry points: [`server/server.js`](https://github.com/atcasanova/jogo/blob/main/server/server.js) (HTTP and sockets), [`game-ai-training/bot_service.py`](https://github.com/atcasanova/jogo/blob/main/game-ai-training/bot_service.py) (Bot service), [`game-ai-training/ai/trainer.py`](https://github.com/atcasanova/jogo/blob/main/game-ai-training/ai/trainer.py) (Training manager), [`public/js/index.js`](https://github.com/atcasanova/jogo/blob/main/public/js/index.js) (Lobby UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser client"]
  node_lobby["Lobby UI<br/>[index.js]"]
  node_gameui["Game UI<br/>[game.js]"]
  node_replayui["Replay UI<br/>[replay.js]"]
end

subgraph group_server["Game service"]
  node_webserver["HTTP and sockets<br/>[server.js]"]
  node_rooms["Room lifecycle<br/>[server.js]"]
  node_rules["Game rules<br/>[game.js]"]
  node_gameutils["Board utilities<br/>[utils.js]"]
  node_botmanager["Bot manager<br/>[bot_manager.js]"]
end

subgraph group_ai["AI system"]
  node_botservice["Bot service<br/>[bot_service.py]"]
  node_environment["Training environment<br/>[environment.py]"]
  node_agents["AI agents<br/>[bot.py]"]
  node_trainer["Training manager<br/>[trainer.py]"]
  node_trainentry["Training entry<br/>[main.py]"]
  node_wrapper["Game wrapper<br/>[game_wrapper.js]"]
  node_trainingengine["Training game<br/>[game.js]"]
end

subgraph group_replay["Replay access"]
  node_replayroutes["Replay routes<br/>[server.js]"]
  node_replayutils["Replay utilities<br/>[replay_utils.js]"]
  node_replayfiles["Replay files"]
end

node_player(("Players"))
node_browser(("Web browser"))

node_player -->|"enters lobby"| node_lobby
node_lobby -->|"socket events"| node_webserver
node_webserver -->|"room updates"| node_lobby
node_webserver -->|"handles rooms"| node_rooms
node_rooms -->|"creates and updates"| node_rules
node_rules -->|"uses board rules"| node_gameutils
node_webserver -.->|"starts bot play"| node_botmanager
node_botmanager -.->|"JSON commands"| node_botservice
node_botservice -->|"builds state"| node_environment
node_botservice -->|"requests actions"| node_agents
node_environment -->|"starts game process"| node_wrapper
node_wrapper -->|"uses game rules"| node_trainingengine
node_trainentry -->|"starts training"| node_trainer
node_trainer -->|"runs episodes"| node_environment
node_trainer -->|"trains models"| node_agents
node_browser -->|"HTTP and sockets"| node_webserver
node_webserver -->|"serves replay routes"| node_replayroutes
node_replayroutes -->|"resolves replay paths"| node_replayutils
node_replayroutes -->|"lists and serves"| node_replayfiles
node_player -->|"plays game"| node_gameui
node_gameui -->|"game actions"| node_webserver
node_webserver -->|"game updates"| node_gameui
node_player -->|"opens replay"| node_replayui
node_replayui -->|"requests replay"| node_webserver

click node_lobby "https://github.com/atcasanova/jogo/blob/main/public/js/index.js"
click node_gameui "https://github.com/atcasanova/jogo/blob/main/public/js/game.js"
click node_replayui "https://github.com/atcasanova/jogo/blob/main/public/js/replay.js"
click node_webserver "https://github.com/atcasanova/jogo/blob/main/server/server.js"
click node_rooms "https://github.com/atcasanova/jogo/blob/main/server/server.js"
click node_rules "https://github.com/atcasanova/jogo/blob/main/server/game.js"
click node_gameutils "https://github.com/atcasanova/jogo/blob/main/server/utils.js"
click node_botmanager "https://github.com/atcasanova/jogo/blob/main/server/bot_manager.js"
click node_replayroutes "https://github.com/atcasanova/jogo/blob/main/server/server.js"
click node_replayutils "https://github.com/atcasanova/jogo/blob/main/server/replay_utils.js"
click node_botservice "https://github.com/atcasanova/jogo/blob/main/game-ai-training/bot_service.py"
click node_environment "https://github.com/atcasanova/jogo/blob/main/game-ai-training/ai/environment.py"
click node_agents "https://github.com/atcasanova/jogo/blob/main/game-ai-training/ai/bot.py"
click node_trainer "https://github.com/atcasanova/jogo/blob/main/game-ai-training/ai/trainer.py"
click node_trainentry "https://github.com/atcasanova/jogo/blob/main/game-ai-training/main.py"
click node_wrapper "https://github.com/atcasanova/jogo/blob/main/game-ai-training/game/game_wrapper.js"
click node_trainingengine "https://github.com/atcasanova/jogo/blob/main/game-ai-training/game/game.js"

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_lobby,node_gameui,node_replayui,node_browser toneBlue
class node_webserver,node_rooms,node_rules,node_gameutils,node_botmanager toneAmber
class node_botservice,node_environment,node_agents,node_trainer,node_trainentry,node_wrapper,node_trainingengine toneMint
class node_replayroutes,node_replayutils,node_replayfiles toneRose
class node_player toneIndigo
```

## Components

### Browser client

- [Lobby UI](https://github.com/atcasanova/jogo/blob/main/public/js/index.js): `public/js/index.js`
- [Game UI](https://github.com/atcasanova/jogo/blob/main/public/js/game.js): `public/js/game.js`
- [Replay UI](https://github.com/atcasanova/jogo/blob/main/public/js/replay.js): `public/js/replay.js`

### Game service

- [HTTP and sockets](https://github.com/atcasanova/jogo/blob/main/server/server.js): `server/server.js`
- [Room lifecycle](https://github.com/atcasanova/jogo/blob/main/server/server.js): `server/server.js`
- [Game rules](https://github.com/atcasanova/jogo/blob/main/server/game.js): `server/game.js`
- [Board utilities](https://github.com/atcasanova/jogo/blob/main/server/utils.js): `server/utils.js`
- [Bot manager](https://github.com/atcasanova/jogo/blob/main/server/bot_manager.js): `server/bot_manager.js`

### AI system

- [Bot service](https://github.com/atcasanova/jogo/blob/main/game-ai-training/bot_service.py): `game-ai-training/bot_service.py`
- [Training environment](https://github.com/atcasanova/jogo/blob/main/game-ai-training/ai/environment.py): `game-ai-training/ai/environment.py`
- [AI agents](https://github.com/atcasanova/jogo/blob/main/game-ai-training/ai/bot.py): `game-ai-training/ai/bot.py`
- [Training manager](https://github.com/atcasanova/jogo/blob/main/game-ai-training/ai/trainer.py): `game-ai-training/ai/trainer.py`
- [Training entry](https://github.com/atcasanova/jogo/blob/main/game-ai-training/main.py): `game-ai-training/main.py`
- [Game wrapper](https://github.com/atcasanova/jogo/blob/main/game-ai-training/game/game_wrapper.js): `game-ai-training/game/game_wrapper.js`
- [Training game](https://github.com/atcasanova/jogo/blob/main/game-ai-training/game/game.js): `game-ai-training/game/game.js`

### Replay access

- [Replay routes](https://github.com/atcasanova/jogo/blob/main/server/server.js): `server/server.js`
- [Replay utilities](https://github.com/atcasanova/jogo/blob/main/server/replay_utils.js): `server/replay_utils.js`
- **Replay files**

### Other components

- **Players**
- **Web browser**

## Connections

- Players → Lobby UI: enters lobby
- Lobby UI → HTTP and sockets: socket events
- HTTP and sockets → Lobby UI: room updates
- HTTP and sockets → Room lifecycle: handles rooms
- Room lifecycle → Game rules: creates and updates
- Game rules → Board utilities: uses board rules
- HTTP and sockets → Bot manager: starts bot play
- Bot manager → Bot service: JSON commands
- Bot service → Training environment: builds state
- Bot service → AI agents: requests actions
- Training environment → Game wrapper: starts game process
- Game wrapper → Training game: uses game rules
- Training entry → Training manager: starts training
- Training manager → Training environment: runs episodes
- Training manager → AI agents: trains models
- Web browser → HTTP and sockets: HTTP and sockets
- HTTP and sockets → Replay routes: serves replay routes
- Replay routes → Replay utilities: resolves replay paths
- Replay routes → Replay files: lists and serves
- Players → Game UI: plays game
- Game UI → HTTP and sockets: game actions
- HTTP and sockets → Game UI: game updates
- Players → Replay UI: opens replay
- Replay UI → HTTP and sockets: requests replay