# mkadri66/ft_transcendence architecture

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

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

## Overview

##### Project Type and Purpose
– This is a full-stack, containerized web application built for the 42 curriculum. Its primary feature is a local-multiplayer Pong game wrapped in an SPA, with user authentication (Google Sign-In + MFA), JWT-secured REST APIs, and persistent data storage in SQLite.

##### Top-Level Architecture from the File Tree
a. “frontend” directory
- Vite-based SPA (HTML/CSS/JavaScript/TypeScript + Tailwind).
- Implements router.ts, view components (home, dashboard, game, profile, etc.).
b. “backend” directory
- Fastify server (server.js) exposing REST endpoints (routes/…).
- MVC-style folder layout:
– config (db.js, env.js)
– controllers (authController.js, mfaController.js)
– middlewares (cors, helmet)
– routes (auth, mfa, tournament, profile, etc.)
c. “db” directory
- SQLite file (database.sqlite).
d. Orchestration files
- docker-compose.yml (defines “frontend” and “backend” services + shared volume for uploads/db)
- Dockerfiles in both sub-projects.

– Client (Browser)
- SPA served by the frontend container on port X
- Contains Router, View Layer, Pong Game Canvas
– Frontend Container (Node + Vite)
- Bundles TS/JS/CSS, serves index.html, static assets
– Backend Container (Node + Fastify)
- REST API Layer (routes → controllers → services)
- Auth subsystem (Google OAuth, JWT issuance)
- MFA subsystem (TOTP QR-code generation + validation)
- File upload handler for avatars (uploads/)
– Database (SQLite)
- Persistent store for users, sessions, tournament results
– External Service
- Google OAuth 2.0 endpoints

##### Interactions and Data Flow
- Client ↔ Frontend: HTTP GET/WS (if used) to fetch static assets and run the SPA
- Client ↔ Backend: HTTPS POST/GET for user flows (login, register, JWT validation, game state if server-backed)
- Backend ↔ SQLite: SQL queries via db.js
- Backend ↔ Google OAuth: OAuth2 token exchange
- Orchestration: Docker-Compose network connecting frontend & backend; shared volumes for uploads and DB

##### Architectural Patterns & Design Principles
– Separation of Concerns: clear split between UI (frontend) and business logic (backend)
– MVC-style in backend: route definitions → controller logic → data/config layers
– Containerization: each major component lives in its own Docker container, orchestrated via docker-compose
– Security First: cors.js, helmet.js, JWT, MFA

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client / Browser"
        direction TB
        Index["index.html"]:::frontend
        Router["router.ts"]:::frontend
        Views["views/*"]:::frontend
        Navbar["navbar.ts"]:::frontend
    end

    subgraph "Frontend Container (Vite)"
        direction TB
        FE_Docker["Dockerfile"]:::service
        FE_Vite["vite.config.js"]:::service
        FE_PKG["package.json"]:::service
    end

    subgraph "Backend Container (Fastify/Node.js)"
        direction TB
        BE_Docker["Dockerfile"]:::service
        Entrypoint["entrypoint.sh"]:::service
        BE_PKG["package.json"]:::service
        ServerJS["server.js"]:::service
        RoutesIdx["routes/index.js"]:::service
        ARoutes["*.routes.js"]:::service
        AuthCtrl["authController.js"]:::service
        MFACtrl["mfaController.js"]:::service
        CorsMW["cors.js"]:::service
        HelmetMW["helmet.js"]:::service
        DBConfDB["db.js"]:::service
        DBConfEnv["env.js"]:::service
        Uploads["uploads/"]:::service
    end

    DB[(SQLite DB)]:::db
    Google[(Google OAuth 2.0)]:::external

    Index -->|"HTTP GET / index.html"| FE_Docker
    Router --> FE_Docker
    Views --> FE_Docker
    Navbar --> FE_Docker

    FE_Docker -->|"REST API calls (JWT auth)"| ServerJS
    ServerJS --> RoutesIdx
    RoutesIdx --> ARoutes
    ARoutes --> AuthCtrl
    ARoutes --> MFACtrl
    ServerJS --> CorsMW
    ServerJS --> HelmetMW
    AuthCtrl -->|"OAuth2 token exchange"| Google
    ServerJS --> DBConfDB
    ServerJS --> DBConfEnv
    DBConfDB --> DB
    DBConfEnv --> DB
    ServerJS --> Uploads

    classDef frontend fill:#add8e6,stroke:#333,stroke-width:1px;
    classDef service fill:#90ee90,stroke:#333,stroke-width:1px;
    classDef db fill:#ffffe0,shape:cylinder,stroke:#333,stroke-width:1px;
    classDef external fill:#d3d3d3,stroke:#333,stroke-width:1px;

    click Index "https://github.com/mkadri66/ft_transcendence/blob/main/frontend/src/index.html"
    click Router "https://github.com/mkadri66/ft_transcendence/blob/main/frontend/src/scripts/router.ts"
    click Views "https://github.com/mkadri66/ft_transcendence/tree/main/frontend/src/scripts/views"
    click Navbar "https://github.com/mkadri66/ft_transcendence/blob/main/frontend/src/scripts/components/navbar.ts"
    click FE_Docker "https://github.com/mkadri66/ft_transcendence/tree/main/frontend/Dockerfile"
    click FE_Vite "https://github.com/mkadri66/ft_transcendence/blob/main/frontend/vite.config.js"
    click FE_PKG "https://github.com/mkadri66/ft_transcendence/blob/main/frontend/package.json"
    click ServerJS "https://github.com/mkadri66/ft_transcendence/blob/main/backend/server.js"
    click RoutesIdx "https://github.com/mkadri66/ft_transcendence/blob/main/backend/routes/index.js"
    click ARoutes "https://github.com/mkadri66/ft_transcendence/blob/main/backend/routes/*.routes.js"
    click AuthCtrl "https://github.com/mkadri66/ft_transcendence/blob/main/backend/controllers/authController.js"
    click MFACtrl "https://github.com/mkadri66/ft_transcendence/blob/main/backend/controllers/mfaController.js"
    click CorsMW "https://github.com/mkadri66/ft_transcendence/blob/main/backend/middlewares/cors.js"
    click HelmetMW "https://github.com/mkadri66/ft_transcendence/blob/main/backend/middlewares/helmet.js"
    click DBConfDB "https://github.com/mkadri66/ft_transcendence/blob/main/backend/config/db.js"
    click DBConfEnv "https://github.com/mkadri66/ft_transcendence/blob/main/backend/config/env.js"
    click Uploads "https://github.com/mkadri66/ft_transcendence/tree/main/backend/uploads/"
```
