# shiftwavedev/ft_transcendence architecture

> Architecture diagram of the GitHub repository shiftwavedev/ft_transcendence, 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/shiftwavedev/ft_transcendence
- Repository: https://github.com/shiftwavedev/ft_transcendence

## Overview

ft_transcendence is a multiplayer game and social web application: users authenticate, find or create live Tic-Tac-Toe rooms, play over WebSockets, and review profiles, statistics, and achievements. The React client also supports chat, friends, avatars, and GDPR account tools; administrators manage users and inspect activity. Fastify routes coordinate API and real-time features, with game-room management and game engines as an internal domain layer, and Prisma-backed relational state. README capabilities guide unsampled branches; sampled excerpts chiefly confirm server registration, game-room management, and client socket behavior.

Main entry points: [`apps/backend/src/main.ts`](https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/backend/src/main.ts) (Fastify server), [`apps/backend/src/db/prisma.ts`](https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/backend/src/db/prisma.ts) (Relational database), [`apps/frontend/src/main.tsx`](https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/frontend/src/main.tsx) (React application), [`apps/frontend/src/router.tsx`](https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/frontend/src/router.tsx) (Page routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_spa["React application<br/>[main.tsx]"]
  node_router["Page routing<br/>[router.tsx]"]
  node_lobby["Game lobby<br/>[GameLobbyPage.tsx]"]
  node_gameui["Game screen<br/>[GamePage.tsx]"]
  node_gamehook["Game socket client<br/>[useGameRoom.ts]"]
  node_chathook["Chat socket client<br/>[useChat.ts]"]
  node_api["HTTP client<br/>[api.ts]"]
end

subgraph group_server["API and identity"]
  node_server["Fastify server<br/>[main.ts]"]
  node_authroutes["Auth routes<br/>[auth.ts]"]
  node_db[("Relational database<br/>[prisma.ts]")]
end

subgraph group_play["Live play and social"]
  node_gameroutes["Game routes<br/>[game.ts]"]
  node_chatroutes["Chat routes<br/>[chat.ts]"]
  node_manager["Room manager<br/>[GameManager.ts]"]
  node_room["Game room<br/>[GameRoom.ts]"]
  node_engine["Game engines<br/>[GameEngine.ts]"]
  node_social["Friends and presence<br/>[friends.ts]"]
end

subgraph group_account["Profiles and admin"]
  node_profile["Profile and avatars<br/>[profile.ts]"]
  node_stats["Stats and achievements<br/>[stats.ts]"]
  node_achievement["Achievement service<br/>[achievements.ts]"]
  node_adminroutes["Admin routes<br/>[index.ts]"]
  node_gdpr["GDPR routes<br/>[gdpr.ts]"]
end

subgraph group_contracts["Data contracts"]
  node_schemas["Shared schemas<br/>[index.ts]"]
end

node_user(("Player"))
node_admin(("Administrator"))

node_user -->|"uses"| node_spa
node_admin -->|"manages"| node_spa
node_spa -->|"renders"| node_router
node_router -->|"routes"| node_lobby
node_router -->|"routes"| node_gameui
node_lobby -->|"requests rooms"| node_api
node_gameui -->|"connects"| node_gamehook
node_gamehook -->|"sends moves"| node_gameroutes
node_gameroutes -->|"dispatches"| node_manager
node_manager -->|"manages"| node_room
node_room -->|"applies moves"| node_engine
node_chathook -->|"exchanges messages"| node_chatroutes
node_api -->|"sends HTTP"| node_server
node_server -->|"registers"| node_authroutes
node_server -->|"registers"| node_gameroutes
node_server -->|"registers"| node_chatroutes
node_server -->|"registers"| node_social
node_server -->|"registers"| node_profile
node_server -->|"registers"| node_stats
node_server -->|"registers"| node_adminroutes
node_server -->|"registers"| node_gdpr
node_manager -->|"persists games"| node_db
node_authroutes -->|"stores sessions"| node_db
node_profile -->|"reads and writes"| node_db
node_social -->|"stores links"| node_db
node_stats -->|"uses"| node_achievement
node_stats -->|"reads results"| node_db
node_adminroutes -->|"manages records"| node_db
node_gdpr -->|"exports data"| node_db
node_spa -.->|"shares contracts"| node_schemas
node_server -.->|"validates contracts"| node_schemas

click node_spa "https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/frontend/src/main.tsx"
click node_router "https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/frontend/src/router.tsx"
click node_lobby "https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/frontend/src/pages/GameLobbyPage.tsx"
click node_gameui "https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/frontend/src/pages/GamePage.tsx"
click node_gamehook "https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/frontend/src/hooks/useGameRoom.ts"
click node_chathook "https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/frontend/src/hooks/useChat.ts"
click node_api "https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/frontend/src/lib/api.ts"
click node_server "https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/backend/src/main.ts"
click node_authroutes "https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/backend/src/routes/auth.ts"
click node_gameroutes "https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/backend/src/routes/game.ts"
click node_chatroutes "https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/backend/src/routes/chat.ts"
click node_manager "https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/backend/src/services/game/GameManager.ts"
click node_room "https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/backend/src/services/game/GameRoom.ts"
click node_engine "https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/backend/src/services/game/GameEngine.ts"
click node_social "https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/backend/src/routes/friends.ts"
click node_profile "https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/backend/src/routes/profile.ts"
click node_stats "https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/backend/src/routes/stats.ts"
click node_achievement "https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/backend/src/services/achievements.ts"
click node_adminroutes "https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/backend/src/routes/admin/index.ts"
click node_gdpr "https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/backend/src/routes/gdpr.ts"
click node_db "https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/backend/src/db/prisma.ts"
click node_schemas "https://github.com/shiftwavedev/ft_transcendence/blob/main/packages/shared-types/src/index.ts"

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_spa,node_router,node_lobby,node_gameui,node_gamehook,node_chathook,node_api toneBlue
class node_server,node_authroutes,node_db toneAmber
class node_gameroutes,node_chatroutes,node_manager,node_room,node_engine,node_social toneMint
class node_profile,node_stats,node_achievement,node_adminroutes,node_gdpr toneRose
class node_schemas,node_user,node_admin toneIndigo
```

## Components

### Web client

- [React application](https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/frontend/src/main.tsx): `apps/frontend/src/main.tsx`
- [Page routing](https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/frontend/src/router.tsx): `apps/frontend/src/router.tsx`
- [Game lobby](https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/frontend/src/pages/GameLobbyPage.tsx): `apps/frontend/src/pages/GameLobbyPage.tsx`
- [Game screen](https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/frontend/src/pages/GamePage.tsx): `apps/frontend/src/pages/GamePage.tsx`
- [Game socket client](https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/frontend/src/hooks/useGameRoom.ts): `apps/frontend/src/hooks/useGameRoom.ts`
- [Chat socket client](https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/frontend/src/hooks/useChat.ts): `apps/frontend/src/hooks/useChat.ts`
- [HTTP client](https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/frontend/src/lib/api.ts): `apps/frontend/src/lib/api.ts`

### API and identity

- [Fastify server](https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/backend/src/main.ts): `apps/backend/src/main.ts`
- [Auth routes](https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/backend/src/routes/auth.ts): `apps/backend/src/routes/auth.ts`
- [Relational database](https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/backend/src/db/prisma.ts): `apps/backend/src/db/prisma.ts`

### Live play and social

- [Game routes](https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/backend/src/routes/game.ts): `apps/backend/src/routes/game.ts`
- [Chat routes](https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/backend/src/routes/chat.ts): `apps/backend/src/routes/chat.ts`
- [Room manager](https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/backend/src/services/game/GameManager.ts): `apps/backend/src/services/game/GameManager.ts`
- [Game room](https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/backend/src/services/game/GameRoom.ts): `apps/backend/src/services/game/GameRoom.ts`
- [Game engines](https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/backend/src/services/game/GameEngine.ts): `apps/backend/src/services/game/GameEngine.ts`
- [Friends and presence](https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/backend/src/routes/friends.ts): `apps/backend/src/routes/friends.ts`

### Profiles and admin

- [Profile and avatars](https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/backend/src/routes/profile.ts): `apps/backend/src/routes/profile.ts`
- [Stats and achievements](https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/backend/src/routes/stats.ts): `apps/backend/src/routes/stats.ts`
- [Achievement service](https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/backend/src/services/achievements.ts): `apps/backend/src/services/achievements.ts`
- [Admin routes](https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/backend/src/routes/admin/index.ts): `apps/backend/src/routes/admin/index.ts`
- [GDPR routes](https://github.com/shiftwavedev/ft_transcendence/blob/main/apps/backend/src/routes/gdpr.ts): `apps/backend/src/routes/gdpr.ts`

### Data contracts

- [Shared schemas](https://github.com/shiftwavedev/ft_transcendence/blob/main/packages/shared-types/src/index.ts): `packages/shared-types/src/index.ts`

### Other components

- **Player**
- **Administrator**

## Connections

- Player → React application: uses
- Administrator → React application: manages
- React application → Page routing: renders
- Page routing → Game lobby: routes
- Page routing → Game screen: routes
- Game lobby → HTTP client: requests rooms
- Game screen → Game socket client: connects
- Game socket client → Game routes: sends moves
- Game routes → Room manager: dispatches
- Room manager → Game room: manages
- Game room → Game engines: applies moves
- Chat socket client → Chat routes: exchanges messages
- HTTP client → Fastify server: sends HTTP
- Fastify server → Auth routes: registers
- Fastify server → Game routes: registers
- Fastify server → Chat routes: registers
- Fastify server → Friends and presence: registers
- Fastify server → Profile and avatars: registers
- Fastify server → Stats and achievements: registers
- Fastify server → Admin routes: registers
- Fastify server → GDPR routes: registers
- Room manager → Relational database: persists games
- Auth routes → Relational database: stores sessions
- Profile and avatars → Relational database: reads and writes
- Friends and presence → Relational database: stores links
- Stats and achievements → Achievement service: uses
- Stats and achievements → Relational database: reads results
- Admin routes → Relational database: manages records
- GDPR routes → Relational database: exports data
- React application → Shared schemas: shares contracts
- Fastify server → Shared schemas: validates contracts