# yannchav/dungeongame architecture

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

- Interactive diagram: https://gitdiagram.com/yannchav/dungeongame
- Repository: https://github.com/yannchav/dungeongame

## Overview

DungeonGame is a browser-based dungeon game organized as microservices. The user-facing journey runs from account signup/sign-in to selecting or creating a hero, entering and traversing a dungeon, and resolving fights; wins award gold, while combat updates hero health. The README documents the service roles, databases, and four RabbitMQ update queues. The graph includes those documented flows and sampled internal calls; frontend-to-service request details and some dungeon/monster internals were not shown, so those links are marked unverified.

Main entry points: [`users-service/src/main/java/com/dungeongame/users/controller/AuthenticationController.java`](https://github.com/yannchav/dungeongame/blob/main/users-service/src/main/java/com/dungeongame/users/controller/AuthenticationController.java) (User service), [`fights-service/src/main/java/com/dungeongame/fights/controller/FightController.java`](https://github.com/yannchav/dungeongame/blob/main/fights-service/src/main/java/com/dungeongame/fights/controller/FightController.java) (Fight service), [`frontend-service/app/src/App.jsx`](https://github.com/yannchav/dungeongame/blob/main/frontend-service/app/src/App.jsx) (React frontend), [`heroes-service/src/main/java/com/dungeongame/heroes/controller/HeroController.java`](https://github.com/yannchav/dungeongame/blob/main/heroes-service/src/main/java/com/dungeongame/heroes/controller/HeroController.java) (Hero service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser client"]
  node_frontend["React frontend<br/>[App.jsx]"]
  node_authpages["Account pages<br/>[LoginPage.jsx]"]
  node_heropages["Hero pages"]
  node_dungeonpage["Dungeon page<br/>[DungeonPage.jsx]"]
  node_realtime["WebSocket context"]
end

subgraph group_gateway["Gateway and messaging"]
  node_backend["Backend gateway<br/>[server.js]"]
  node_rabbit["RabbitMQ"]
  node_qfh["Fight-to-hero health<br/>[README.md]"]
  node_qfu["Fight-to-user gold<br/>[README.md]"]
  node_qhf["Hero-to-frontend health<br/>[README.md]"]
  node_quf["User-to-frontend gold<br/>[README.md]"]
end

subgraph group_identity["Identity and heroes"]
  node_users["User service"]
  node_auth["Authentication"]
  node_jwt["JWT service<br/>[JwtService.java]"]
  node_userdb[("Users database")]
  node_heroes["Hero service"]
  node_herologic["Hero creation and health<br/>[HeroService.java]"]
  node_herodb[("Heroes database")]
end

subgraph group_gameplay["Dungeon and combat"]
  node_dungeons["Dungeon service<br/>[dungeon.js]"]
  node_monsters["Monster service"]
  node_fights["Fight service"]
  node_fightlogic["Fight resolution<br/>[FightService.java]"]
end

node_player(("Player"))

node_player -->|"plays through"| node_frontend
node_frontend -->|"routes to"| node_authpages
node_frontend -->|"routes to"| node_heropages
node_frontend -->|"routes to"| node_dungeonpage
node_authpages -.->|"requests account"| node_users
node_heropages -.->|"requests heroes"| node_heroes
node_dungeonpage -.->|"requests dungeon"| node_dungeons
node_dungeonpage -.->|"requests monsters"| node_monsters
node_dungeonpage -.->|"submits fight"| node_fights
node_backend -->|"uses queues"| node_rabbit
node_users -->|"delegates auth"| node_auth
node_auth -->|"reads and saves"| node_userdb
node_users -->|"creates token"| node_jwt
node_users -->|"stores users"| node_userdb
node_heroes -->|"delegates hero work"| node_herologic
node_herologic -->|"reads and saves"| node_herodb
node_herologic -->|"publishes health"| node_rabbit
node_fights -->|"resolves fight"| node_fightlogic
node_fights -->|"publishes outcomes"| node_rabbit
node_fights -->|"sends health update"| node_qfh
node_qfh -->|"updates health"| node_heroes
node_fights -->|"sends gold award"| node_qfu
node_qfu -->|"updates gold"| node_users
node_heroes -->|"sends health update"| node_qhf
node_qhf -->|"delivers update"| node_backend
node_backend -->|"forwards by WebSocket"| node_realtime
node_users -->|"sends gold update"| node_quf
node_quf -->|"delivers update"| node_backend
node_realtime -.->|"updates display"| node_frontend
node_heroes -->|"persists heroes"| node_herodb

click node_frontend "https://github.com/yannchav/dungeongame/blob/main/frontend-service/app/src/App.jsx"
click node_authpages "https://github.com/yannchav/dungeongame/blob/main/frontend-service/app/src/pages/LoginPage/LoginPage.jsx"
click node_heropages "https://github.com/yannchav/dungeongame/blob/main/frontend-service/app/src/pages/HeroPage/HeroSelectionPage.jsx"
click node_dungeonpage "https://github.com/yannchav/dungeongame/blob/main/frontend-service/app/src/pages/DungeonPage/DungeonPage.jsx"
click node_realtime "https://github.com/yannchav/dungeongame/blob/main/frontend-service/app/src/contexts/WebSocketContext.jsx"
click node_backend "https://github.com/yannchav/dungeongame/blob/main/backend-service/server.js"
click node_qfh "https://github.com/yannchav/dungeongame/blob/main/README.md"
click node_qfu "https://github.com/yannchav/dungeongame/blob/main/README.md"
click node_qhf "https://github.com/yannchav/dungeongame/blob/main/README.md"
click node_quf "https://github.com/yannchav/dungeongame/blob/main/README.md"
click node_users "https://github.com/yannchav/dungeongame/blob/main/users-service/src/main/java/com/dungeongame/users/controller/AuthenticationController.java"
click node_auth "https://github.com/yannchav/dungeongame/blob/main/users-service/src/main/java/com/dungeongame/users/service/AuthenticationService.java"
click node_jwt "https://github.com/yannchav/dungeongame/blob/main/users-service/src/main/java/com/dungeongame/users/service/JwtService.java"
click node_heroes "https://github.com/yannchav/dungeongame/blob/main/heroes-service/src/main/java/com/dungeongame/heroes/controller/HeroController.java"
click node_herologic "https://github.com/yannchav/dungeongame/blob/main/heroes-service/src/main/java/com/dungeongame/heroes/service/HeroService.java"
click node_dungeons "https://github.com/yannchav/dungeongame/blob/main/dungeons-service/routes/dungeon.js"
click node_monsters "https://github.com/yannchav/dungeongame/blob/main/monsters-service/src/main/java/com/dungeongame/monsters/services/MonsterService.java"
click node_fights "https://github.com/yannchav/dungeongame/blob/main/fights-service/src/main/java/com/dungeongame/fights/controller/FightController.java"
click node_fightlogic "https://github.com/yannchav/dungeongame/blob/main/fights-service/src/main/java/com/dungeongame/fights/service/FightService.java"

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_frontend,node_authpages,node_heropages,node_dungeonpage,node_realtime toneBlue
class node_backend,node_rabbit,node_qfh,node_qfu,node_qhf,node_quf toneAmber
class node_users,node_auth,node_jwt,node_userdb,node_heroes,node_herologic,node_herodb toneMint
class node_dungeons,node_monsters,node_fights,node_fightlogic toneRose
class node_player toneIndigo
```

## Components

### Browser client

- [React frontend](https://github.com/yannchav/dungeongame/blob/main/frontend-service/app/src/App.jsx): `frontend-service/app/src/App.jsx`
- [Account pages](https://github.com/yannchav/dungeongame/blob/main/frontend-service/app/src/pages/LoginPage/LoginPage.jsx): `frontend-service/app/src/pages/LoginPage/LoginPage.jsx`
- [Hero pages](https://github.com/yannchav/dungeongame/blob/main/frontend-service/app/src/pages/HeroPage/HeroSelectionPage.jsx): `frontend-service/app/src/pages/HeroPage/HeroSelectionPage.jsx`
- [Dungeon page](https://github.com/yannchav/dungeongame/blob/main/frontend-service/app/src/pages/DungeonPage/DungeonPage.jsx): `frontend-service/app/src/pages/DungeonPage/DungeonPage.jsx`
- [WebSocket context](https://github.com/yannchav/dungeongame/blob/main/frontend-service/app/src/contexts/WebSocketContext.jsx): `frontend-service/app/src/contexts/WebSocketContext.jsx`

### Gateway and messaging

- [Backend gateway](https://github.com/yannchav/dungeongame/blob/main/backend-service/server.js): `backend-service/server.js`
- **RabbitMQ**
- [Fight-to-hero health](https://github.com/yannchav/dungeongame/blob/main/README.md): `README.md`
- [Fight-to-user gold](https://github.com/yannchav/dungeongame/blob/main/README.md): `README.md`
- [Hero-to-frontend health](https://github.com/yannchav/dungeongame/blob/main/README.md): `README.md`
- [User-to-frontend gold](https://github.com/yannchav/dungeongame/blob/main/README.md): `README.md`

### Identity and heroes

- [User service](https://github.com/yannchav/dungeongame/blob/main/users-service/src/main/java/com/dungeongame/users/controller/AuthenticationController.java): `users-service/src/main/java/com/dungeongame/users/controller/AuthenticationController.java`
- [Authentication](https://github.com/yannchav/dungeongame/blob/main/users-service/src/main/java/com/dungeongame/users/service/AuthenticationService.java): `users-service/src/main/java/com/dungeongame/users/service/AuthenticationService.java`
- [JWT service](https://github.com/yannchav/dungeongame/blob/main/users-service/src/main/java/com/dungeongame/users/service/JwtService.java): `users-service/src/main/java/com/dungeongame/users/service/JwtService.java`
- **Users database**
- [Hero service](https://github.com/yannchav/dungeongame/blob/main/heroes-service/src/main/java/com/dungeongame/heroes/controller/HeroController.java): `heroes-service/src/main/java/com/dungeongame/heroes/controller/HeroController.java`
- [Hero creation and health](https://github.com/yannchav/dungeongame/blob/main/heroes-service/src/main/java/com/dungeongame/heroes/service/HeroService.java): `heroes-service/src/main/java/com/dungeongame/heroes/service/HeroService.java`
- **Heroes database**

### Dungeon and combat

- [Dungeon service](https://github.com/yannchav/dungeongame/blob/main/dungeons-service/routes/dungeon.js): `dungeons-service/routes/dungeon.js`
- [Monster service](https://github.com/yannchav/dungeongame/blob/main/monsters-service/src/main/java/com/dungeongame/monsters/services/MonsterService.java): `monsters-service/src/main/java/com/dungeongame/monsters/services/MonsterService.java`
- [Fight service](https://github.com/yannchav/dungeongame/blob/main/fights-service/src/main/java/com/dungeongame/fights/controller/FightController.java): `fights-service/src/main/java/com/dungeongame/fights/controller/FightController.java`
- [Fight resolution](https://github.com/yannchav/dungeongame/blob/main/fights-service/src/main/java/com/dungeongame/fights/service/FightService.java): `fights-service/src/main/java/com/dungeongame/fights/service/FightService.java`

### Other components

- **Player**

## Connections

- Player → React frontend: plays through (evidence: `README.md`)
- React frontend → Account pages: routes to (evidence: `frontend-service/app/src/App.jsx`)
- React frontend → Hero pages: routes to (evidence: `frontend-service/app/src/App.jsx`)
- React frontend → Dungeon page: routes to (evidence: `frontend-service/app/src/App.jsx`)
- Account pages → User service: requests account
- Hero pages → Hero service: requests heroes
- Dungeon page → Dungeon service: requests dungeon
- Dungeon page → Monster service: requests monsters
- Dungeon page → Fight service: submits fight
- Backend gateway → RabbitMQ: uses queues (evidence: `README.md`)
- User service → Authentication: delegates auth (evidence: `users-service/src/main/java/com/dungeongame/users/controller/AuthenticationController.java`)
- Authentication → Users database: reads and saves (evidence: `users-service/src/main/java/com/dungeongame/users/service/AuthenticationService.java`)
- User service → JWT service: creates token (evidence: `users-service/src/main/java/com/dungeongame/users/controller/AuthenticationController.java`)
- User service → Users database: stores users (evidence: `README.md`)
- Hero service → Hero creation and health: delegates hero work (evidence: `heroes-service/src/main/java/com/dungeongame/heroes/controller/HeroController.java`)
- Hero creation and health → Heroes database: reads and saves (evidence: `heroes-service/src/main/java/com/dungeongame/heroes/service/HeroService.java`)
- Hero creation and health → RabbitMQ: publishes health (evidence: `heroes-service/src/main/java/com/dungeongame/heroes/service/HeroService.java`)
- Fight service → Fight resolution: resolves fight (evidence: `fights-service/src/main/java/com/dungeongame/fights/controller/FightController.java`)
- Fight service → RabbitMQ: publishes outcomes (evidence: `fights-service/src/main/java/com/dungeongame/fights/controller/FightController.java`)
- Fight service → Fight-to-hero health: sends health update (evidence: `README.md`)
- Fight-to-hero health → Hero service: updates health (evidence: `README.md`)
- Fight service → Fight-to-user gold: sends gold award (evidence: `README.md`)
- Fight-to-user gold → User service: updates gold (evidence: `README.md`)
- Hero service → Hero-to-frontend health: sends health update (evidence: `README.md`)
- Hero-to-frontend health → Backend gateway: delivers update (evidence: `README.md`)
- Backend gateway → WebSocket context: forwards by WebSocket (evidence: `README.md`)
- User service → User-to-frontend gold: sends gold update (evidence: `README.md`)
- User-to-frontend gold → Backend gateway: delivers update (evidence: `README.md`)
- WebSocket context → React frontend: updates display (evidence: `frontend-service/app/src/App.jsx`)
- Hero service → Heroes database: persists heroes (evidence: `README.md`)
