# a-boudoun/ft_transcendence architecture

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

- Interactive diagram: https://gitdiagram.com/a-boudoun/ft_transcendence
- Repository: https://github.com/a-boudoun/ft_transcendence

## Overview

##### Project Type and Purpose
- This is a full-stack, real-time web application (“ft_transcendence”) that lets users authenticate via OAuth (42 or Google), chat in channels or direct messages, manage friends, and play live multiplayer Pong games or offline AI matches.
- Frontend: Next.js + React + Tailwind + Redux.
- Backend: NestJS (REST + WebSocket gateways) + TypeORM + JWT + 2FA.
- Database: PostgreSQL.
- Deployment: Docker Compose coordinates three containers (frontend, backend, database).

##### High-Level Architecture Components
a. Frontend Application
- UI Layer (Next.js pages/app router, React components)
- Client-side State (Redux store + React hooks)
- HTTP Client Module (Axios)
- WebSocket Client (chatSocket.ts / gameSocket)
b. Backend Application
- Auth Module (OAuth strategies, JWT guards, 2FA)
- Users Module (profile, settings, friendships)
- Chat Module (channels, channel owner/admin logic)
- Game Module (matchmaking, engine service, simulation)
- Room & UserGateway (real-time presence/status)
- TypeORM Entities (User, Channel, Friendship, GameHistory)
- REST Controllers (HTTP APIs)
- WebSocket Gateways (chat.gateway.ts, game.gateway.ts, room.gateway.ts, user.gateway.ts)
c. Database
- PostgreSQL storing all entities
d. External Services
- 42 OAuth API
- Google OAuth API
e. Infrastructure
- Docker Compose network linking frontend, backend, and Postgres
- Environment variables (.env, .env.local)

##### Relationships and Data Flows
1. User opens browser → Next.js UI components (React)
2. UI dispatches HTTP requests (Axios) → NestJS REST endpoints for:
– Authentication (OAuth handshake → JWT token issuance)
– Profile data, settings, friendship/channel CRUD
3. Upon successful login → Client stores JWT in cookie or local storage
4. Client establishes WebSocket connections (with JWT) to:
– Chat Gateway for channel messages, DMs, moderation events
– Game Gateway for matchmaking events, real-time game state updates
– Room Gateway for room/ownership events
– User Gateway for presence/status updates
5. Backend WebSocket gateways process events via their services, persist updates to Postgres, then broadcast messages back to subscribed clients
6. Backend services use TypeORM to read/write PostgreSQL

##### Architectural Patterns and Principles
- Layered architecture: UI → Application/API layer → Business logic (services) → Data access (ORM)
- Modular design (NestJS modules per domain) for separation of concerns
- CQRS-style split: REST for resource operations, WebSockets for real-time events
- Authentication via OAuth2 + JWT + optional 2FA
- State management in frontend (Redux) to unify UI, HTTP, and WebSocket data

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Docker Compose Network
    subgraph "Docker Compose\nNetwork" 
        direction TB
        subgraph Frontend
            direction TB
            class FrontendRegion frontend
            UI["Next.js UI Layer"] 
            COMP["React Components"] 
            STATE_STORE["Redux Store (store.ts)"]
            STATE_FEATURE["Redux Feature (globalState.ts)"]
            STATE_PROVIDER["Redux Provider (provider.tsx)"]
            AXIOS["HTTP Client (Axios)"]
            CHATWS["Chat WebSocket Client"]
            SOCKETG["Game WebSocket Client"]
        end

        subgraph Backend
            direction TB
            class BackendRegion backend
            AUTH["Auth Module"]
            USERS["Users Module"]
            CHANNELS["Chat Module"]
            FRIENDSHIP["Friendship Module"]
            GH["Game-History Module"]
            GAME["Game Module"]
            ROOM["Room Module & Gateway"]
            USERGW["User Gateway"]
            ENTITIES["TypeORM Entities"]
            REST["REST Controllers"]
            WSG["WebSocket Gateways"]
        end

        DB["PostgreSQL DB"]:::db
    end

    subgraph External
        direction TB
        class ExternalRegion external
        OAuth42["42 OAuth Provider"]
        OAuthGoogle["Google OAuth Provider"]
    end

    %% User Interaction
    User["User"]:::external -->|"opens browser"| UI

    %% HTTP Flow
    UI -->|"dispatch HTTPS/REST"| AXIOS
    STATE_STORE --> UI
    STATE_FEATURE --> UI
    STATE_PROVIDER --> UI

    AXIOS -->|"HTTPS/REST"| REST
    REST -->|"calls"| AUTH
    REST -->|"calls"| USERS
    REST -->|"calls"| CHANNELS
    REST -->|"calls"| FRIENDSHIP
    REST -->|"calls"| GH

    %% Backend Internal
    AUTH --> ENTITIES
    USERS --> ENTITIES
    CHANNELS --> ENTITIES
    FRIENDSHIP --> ENTITIES
    GH --> ENTITIES
    GAME --> ENTITIES
    ROOM --> ENTITIES
    USERGW --> ENTITIES

    ENTITIES -->|"TypeORM"| DB

    %% WebSocket Flow
    CHATWS -.->|"WSS"| WSG
    SOCKETG -.->|"WSS"| WSG

    WSG -->|"routes events to"| CHANNELS
    WSG -->|"routes events to"| GAME
    WSG -->|"routes events to"| ROOM
    WSG -->|"routes events to"| USERGW

    %% OAuth External
    OAuth42 -->|"OAuth handshake"| AUTH
    OAuthGoogle -->|"OAuth handshake"| AUTH

    %% Click Events Frontend
    click UI "https://github.com/a-boudoun/ft_transcendence/tree/main/frontend/app/"
    click COMP "https://github.com/a-boudoun/ft_transcendence/tree/main/frontend/components/"
    click STATE_STORE "https://github.com/a-boudoun/ft_transcendence/blob/main/frontend/redux/store.ts"
    click STATE_FEATURE "https://github.com/a-boudoun/ft_transcendence/blob/main/frontend/redux/features/globalState.ts"
    click STATE_PROVIDER "https://github.com/a-boudoun/ft_transcendence/blob/main/frontend/redux/provider.tsx"
    click AXIOS "https://github.com/a-boudoun/ft_transcendence/blob/main/frontend/apis/axios.ts"
    click CHATWS "https://github.com/a-boudoun/ft_transcendence/blob/main/frontend/components/chat/chatSocket.ts"
    click SOCKETG "https://github.com/a-boudoun/ft_transcendence/blob/main/frontend/components/socketG.ts"

    %% Click Events Backend
    click AUTH "https://github.com/a-boudoun/ft_transcendence/tree/main/backend/src/auth/"
    click USERS "https://github.com/a-boudoun/ft_transcendence/tree/main/backend/src/users/"
    click CHANNELS "https://github.com/a-boudoun/ft_transcendence/tree/main/backend/src/channels/"
    click FRIENDSHIP "https://github.com/a-boudoun/ft_transcendence/tree/main/backend/src/friendship/"
    click GH "https://github.com/a-boudoun/ft_transcendence/tree/main/backend/src/game-history/"
    click GAME "https://github.com/a-boudoun/ft_transcendence/tree/main/backend/src/game/"
    click ROOM "https://github.com/a-boudoun/ft_transcendence/tree/main/backend/src/room/"
    click USERGW "https://github.com/a-boudoun/ft_transcendence/tree/main/backend/src/usersGateway/"
    click ENTITIES "https://github.com/a-boudoun/ft_transcendence/tree/main/backend/src/entities/"

    %% Click Events Infrastructure
    click DB "https://github.com/a-boudoun/ft_transcendence/blob/main/docker-compose.yml"
    click OAuth42 "https://github.com/a-boudoun/ft_transcendence/blob/main/.env_template"
    click OAuthGoogle "https://github.com/a-boudoun/ft_transcendence/blob/main/backend/.env"

    %% Styles
    classDef frontend fill:#BBDEFB,stroke:#000,stroke-width:1px
    classDef backend fill:#FFCC80,stroke:#000,stroke-width:1px
    classDef db fill:#C8E6C9,stroke:#000,stroke-width:1px
    classDef external fill:#E1BEE7,stroke:#000,stroke-width:1px
    class User,ExternalRegion,Oauth42,OauthGoogle external
    class FrontendRegion frontend
    class BackendRegion backend
```
