# mani-navi/titipool architecture

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

- Interactive diagram: https://gitdiagram.com/mani-navi/titipool
- Repository: https://github.com/mani-navi/titipool

## Overview

Titipool is a Persian-focused virtual tabletop for D&D and other tabletop role-playing games. Players authenticate, enter or create a room, and use its tactical canvas and room tools; real-time room events synchronize shared play, while voice and physical dice provide separate live-play capabilities. The graph combines documented product behavior with sampled frontend/backend references. Many room features are present in the tree but their individual controllers and services were not sampled, so they are represented at subsystem level rather than with speculative call chains.

Main entry points: [`Frontend/src/pages/room/RoomPage.jsx`](https://github.com/mani-navi/titipool/blob/main/Frontend/src/pages/room/RoomPage.jsx) (Room workspace), [`Frontend/src/App.jsx`](https://github.com/mani-navi/titipool/blob/main/Frontend/src/App.jsx) (App and routes), [`Backend/V.1.0/src/main/java/com/VTT/V10/user/UserService.java`](https://github.com/mani-navi/titipool/blob/main/Backend/V.1.0/src/main/java/com/VTT/V10/user/UserService.java) (User profiles), [`Backend/V.1.0/src/main/java/com/VTT/V10/room`](https://github.com/mani-navi/titipool/tree/main/Backend/V.1.0/src/main/java/com/VTT/V10/room) (Scenes and game state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Frontend experience"]
  node_app["App and routes<br/>[App.jsx]"]
  node_authui["Sign-in UI<br/>[LoginForm.jsx]"]
  node_dashboard["Room dashboard<br/>[DashboardPage.jsx]"]
  node_roomui["Room workspace<br/>[RoomPage.jsx]"]
  node_canvas["Tactical canvas<br/>[GameCanvas.jsx]"]
  node_dice["3D dice engine<br/>[diceDefinitions.js]"]
  node_voiceui["Voice controls<br/>[useVoice.js]"]
end

subgraph group_identity["Identity and media"]
  node_auth["Authentication service<br/>[AuthService.java]"]
  node_jwt["JWT service<br/>[JwtService.java]"]
  node_users["User profiles<br/>[UserService.java]"]
  node_email["Email verification<br/>[EmailService.java]"]
  node_assets["Asset management<br/>[AssetService.java]"]
  node_storage["File storage"]
end

subgraph group_table["Room and gameplay"]
  node_rooms["Room management<br/>[RoomService.java]"]
  node_gameplay["Scenes and game state<br/>[room]"]
end

subgraph group_realtime["Live collaboration"]
  node_voice["Voice token service<br/>[VoiceService.java]"]
  node_wsclient["STOMP client"]
  node_wsbackend["Room WebSocket"]
  node_sessions["Session manager"]
end

node_player(("Player"))
node_livekit["LiveKit SFU"]
node_database[("PostgreSQL")]

node_player -->|"uses"| node_app
node_app -->|"routes to"| node_authui
node_player -->|"manages rooms"| node_dashboard
node_player -->|"plays in"| node_roomui
node_roomui -.->|"renders"| node_canvas
node_player -->|"rolls dice"| node_dice
node_authui -.->|"authenticates via"| node_auth
node_auth -->|"issues tokens"| node_jwt
node_app -->|"refreshes profile"| node_users
node_users -->|"sends verification"| node_email
node_player -->|"uploads assets"| node_assets
node_assets -->|"stores files"| node_storage
node_dashboard -.->|"manages rooms"| node_rooms
node_roomui -.->|"uses game state"| node_gameplay
node_voiceui -->|"requests token"| node_voice
node_voice -->|"signs voice access"| node_livekit
node_roomui -.->|"connects live"| node_wsclient
node_wsclient -->|"sends STOMP events"| node_wsbackend
node_wsbackend -.->|"tracks sessions"| node_sessions
node_sessions -->|"broadcasts presence"| node_wsclient
node_rooms -.->|"manages room state"| node_gameplay
node_gameplay -->|"persists state"| node_database
node_users -.->|"persists profiles"| node_database

click node_app "https://github.com/mani-navi/titipool/blob/main/Frontend/src/App.jsx"
click node_authui "https://github.com/mani-navi/titipool/blob/main/Frontend/src/components/auth/LoginForm.jsx"
click node_dashboard "https://github.com/mani-navi/titipool/blob/main/Frontend/src/pages/dashboard/DashboardPage.jsx"
click node_roomui "https://github.com/mani-navi/titipool/blob/main/Frontend/src/pages/room/RoomPage.jsx"
click node_canvas "https://github.com/mani-navi/titipool/blob/main/Frontend/src/components/canvas/GameCanvas.jsx"
click node_dice "https://github.com/mani-navi/titipool/blob/main/Frontend/src/features/dice/engine/diceDefinitions.js"
click node_auth "https://github.com/mani-navi/titipool/blob/main/Backend/V.1.0/src/main/java/com/VTT/V10/auth/AuthService.java"
click node_jwt "https://github.com/mani-navi/titipool/blob/main/Backend/V.1.0/src/main/java/com/VTT/V10/auth/JwtService.java"
click node_users "https://github.com/mani-navi/titipool/blob/main/Backend/V.1.0/src/main/java/com/VTT/V10/user/UserService.java"
click node_email "https://github.com/mani-navi/titipool/blob/main/Backend/V.1.0/src/main/java/com/VTT/V10/mail/EmailService.java"
click node_assets "https://github.com/mani-navi/titipool/blob/main/Backend/V.1.0/src/main/java/com/VTT/V10/asset/AssetService.java"
click node_storage "https://github.com/mani-navi/titipool/blob/main/Backend/V.1.0/src/main/java/com/VTT/V10/asset/storage/LocalStorageService.java"
click node_rooms "https://github.com/mani-navi/titipool/blob/main/Backend/V.1.0/src/main/java/com/VTT/V10/room/RoomService.java"
click node_gameplay "https://github.com/mani-navi/titipool/tree/main/Backend/V.1.0/src/main/java/com/VTT/V10/room"
click node_voiceui "https://github.com/mani-navi/titipool/blob/main/Frontend/src/hooks/useVoice.js"
click node_voice "https://github.com/mani-navi/titipool/blob/main/Backend/V.1.0/src/main/java/com/VTT/V10/voice/VoiceService.java"
click node_wsclient "https://github.com/mani-navi/titipool/blob/main/Frontend/src/services/websocket.service.js"
click node_wsbackend "https://github.com/mani-navi/titipool/blob/main/Backend/V.1.0/src/main/java/com/VTT/V10/websocket/RoomWebSocketController.java"
click node_sessions "https://github.com/mani-navi/titipool/blob/main/Backend/V.1.0/src/main/java/com/VTT/V10/websocket/RoomSessionManager.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_app,node_authui,node_dashboard,node_roomui,node_canvas,node_dice,node_voiceui toneBlue
class node_auth,node_jwt,node_users,node_email,node_assets,node_storage,node_database toneAmber
class node_rooms,node_gameplay toneMint
class node_voice,node_wsclient,node_wsbackend,node_sessions toneRose
class node_player,node_livekit toneIndigo
```

## Components

### Frontend experience

- [App and routes](https://github.com/mani-navi/titipool/blob/main/Frontend/src/App.jsx): `Frontend/src/App.jsx`
- [Sign-in UI](https://github.com/mani-navi/titipool/blob/main/Frontend/src/components/auth/LoginForm.jsx): `Frontend/src/components/auth/LoginForm.jsx`
- [Room dashboard](https://github.com/mani-navi/titipool/blob/main/Frontend/src/pages/dashboard/DashboardPage.jsx): `Frontend/src/pages/dashboard/DashboardPage.jsx`
- [Room workspace](https://github.com/mani-navi/titipool/blob/main/Frontend/src/pages/room/RoomPage.jsx): `Frontend/src/pages/room/RoomPage.jsx`
- [Tactical canvas](https://github.com/mani-navi/titipool/blob/main/Frontend/src/components/canvas/GameCanvas.jsx): `Frontend/src/components/canvas/GameCanvas.jsx`
- [3D dice engine](https://github.com/mani-navi/titipool/blob/main/Frontend/src/features/dice/engine/diceDefinitions.js): `Frontend/src/features/dice/engine/diceDefinitions.js`
- [Voice controls](https://github.com/mani-navi/titipool/blob/main/Frontend/src/hooks/useVoice.js): `Frontend/src/hooks/useVoice.js`

### Identity and media

- [Authentication service](https://github.com/mani-navi/titipool/blob/main/Backend/V.1.0/src/main/java/com/VTT/V10/auth/AuthService.java): `Backend/V.1.0/src/main/java/com/VTT/V10/auth/AuthService.java`
- [JWT service](https://github.com/mani-navi/titipool/blob/main/Backend/V.1.0/src/main/java/com/VTT/V10/auth/JwtService.java): `Backend/V.1.0/src/main/java/com/VTT/V10/auth/JwtService.java`
- [User profiles](https://github.com/mani-navi/titipool/blob/main/Backend/V.1.0/src/main/java/com/VTT/V10/user/UserService.java): `Backend/V.1.0/src/main/java/com/VTT/V10/user/UserService.java`
- [Email verification](https://github.com/mani-navi/titipool/blob/main/Backend/V.1.0/src/main/java/com/VTT/V10/mail/EmailService.java): `Backend/V.1.0/src/main/java/com/VTT/V10/mail/EmailService.java`
- [Asset management](https://github.com/mani-navi/titipool/blob/main/Backend/V.1.0/src/main/java/com/VTT/V10/asset/AssetService.java): `Backend/V.1.0/src/main/java/com/VTT/V10/asset/AssetService.java`
- [File storage](https://github.com/mani-navi/titipool/blob/main/Backend/V.1.0/src/main/java/com/VTT/V10/asset/storage/LocalStorageService.java): `Backend/V.1.0/src/main/java/com/VTT/V10/asset/storage/LocalStorageService.java`

### Room and gameplay

- [Room management](https://github.com/mani-navi/titipool/blob/main/Backend/V.1.0/src/main/java/com/VTT/V10/room/RoomService.java): `Backend/V.1.0/src/main/java/com/VTT/V10/room/RoomService.java`
- [Scenes and game state](https://github.com/mani-navi/titipool/tree/main/Backend/V.1.0/src/main/java/com/VTT/V10/room): `Backend/V.1.0/src/main/java/com/VTT/V10/room`

### Live collaboration

- [Voice token service](https://github.com/mani-navi/titipool/blob/main/Backend/V.1.0/src/main/java/com/VTT/V10/voice/VoiceService.java): `Backend/V.1.0/src/main/java/com/VTT/V10/voice/VoiceService.java`
- [STOMP client](https://github.com/mani-navi/titipool/blob/main/Frontend/src/services/websocket.service.js): `Frontend/src/services/websocket.service.js`
- [Room WebSocket](https://github.com/mani-navi/titipool/blob/main/Backend/V.1.0/src/main/java/com/VTT/V10/websocket/RoomWebSocketController.java): `Backend/V.1.0/src/main/java/com/VTT/V10/websocket/RoomWebSocketController.java`
- [Session manager](https://github.com/mani-navi/titipool/blob/main/Backend/V.1.0/src/main/java/com/VTT/V10/websocket/RoomSessionManager.java): `Backend/V.1.0/src/main/java/com/VTT/V10/websocket/RoomSessionManager.java`

### Other components

- **Player**
- **LiveKit SFU**
- **PostgreSQL**

## Connections

- Player → App and routes: uses
- App and routes → Sign-in UI: routes to (evidence: `Frontend/src/App.jsx`)
- Player → Room dashboard: manages rooms
- Player → Room workspace: plays in
- Room workspace → Tactical canvas: renders
- Player → 3D dice engine: rolls dice
- Sign-in UI → Authentication service: authenticates via
- Authentication service → JWT service: issues tokens (evidence: `Backend/V.1.0/src/main/java/com/VTT/V10/auth/AuthService.java`)
- App and routes → User profiles: refreshes profile (evidence: `Frontend/src/App.jsx`)
- User profiles → Email verification: sends verification (evidence: `Backend/V.1.0/src/main/java/com/VTT/V10/user/UserService.java`)
- Player → Asset management: uploads assets
- Asset management → File storage: stores files (evidence: `Backend/V.1.0/src/main/java/com/VTT/V10/asset/AssetService.java`)
- Room dashboard → Room management: manages rooms
- Room workspace → Scenes and game state: uses game state
- Voice controls → Voice token service: requests token (evidence: `Frontend/src/hooks/useVoice.js`)
- Voice token service → LiveKit SFU: signs voice access
- Room workspace → STOMP client: connects live
- STOMP client → Room WebSocket: sends STOMP events
- Room WebSocket → Session manager: tracks sessions
- Session manager → STOMP client: broadcasts presence
- Room management → Scenes and game state: manages room state (evidence: `Backend/V.1.0/src/main/java/com/VTT/V10/room/RoomService.java`)
- Scenes and game state → PostgreSQL: persists state
- User profiles → PostgreSQL: persists profiles