# amdouyah/ft_transcendence architecture

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

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

## Overview

##### Project type and purpose
- This is a full-stack, Docker-based web application (“ft_transcendence”) that allows users to register/login, chat, invite friends, enable 2FA, and play a real-time ping-pong game.
- It uses NGINX as a frontend server and reverse proxy, a Django/Django REST Framework backend (with Django Channels for WebSockets), and PostgreSQL for persistent storage.

##### File structure
- Top-level:
- frontend/ – Static assets (HTML, CSS, vanilla JS components) and NGINX config.
- backend/ – Dockerfile, a “project” directory that houses a Django project with modular apps:
– authentication (JWT, 2FA, profile, friend/block logic)
– chat (WebSocket consumers, REST endpoints)
– game (core ping-pong game logic)
– remote (real-time game rooms via Channels)
– tournament (tournament logic over WebSockets)
- docker-compose.yaml – Orchestrates three containers (NGINX, Django backend, PostgreSQL).
- .env.test, Makefile – Environment and helper scripts.

##### README for additional insights
- Confirms a three-container architecture (NGINX, Django REST + Channels, PostgreSQL).
- Frontend is vanilla JS served by NGINX on port 81 (HTTPS).
- Backend provides REST API endpoints secured by JWT and Channels endpoints for real-time messaging.
- Database stores users, game history, chat transcripts, friend requests, tournament data, etc.
- External integrations: 42-intra OAuth registration, TOTP 2FA.

a. Main components
- Client (Browser UI)
- NGINX container
- Django Backend container (REST + Channels) with subcomponents:
– Authentication Service (JWT, 2FA, user profiles, friend/block logic)
– REST API Layer (Django REST Framework)
– WebSocket Layer (Django Channels consumers: chat, game, remote, tournament)
– Static/media file handling (user avatars, game assets)
- PostgreSQL container
- (Optional) External OAuth Provider (42-intra)

b. Relationships & interactions
1. Browser → HTTPS → NGINX
– Serves static frontend files (HTML/CSS/JS).
– Proxies API calls (/api/*) to Django REST.
– Proxies WebSocket endpoints (/ws/chat/, /ws/remote/, /ws/tournament/) to Django Channels.
2. Django REST endpoints ↔ PostgreSQL
– CRUD on users, profiles, friend requests, tournaments.
3. Django Channels ↔ PostgreSQL
– Persist chat messages, game invitations, real-time state updates.
4. Django Authentication ↔ External OAuth (42-intra)
– User registration/login handshake.
5. Browser ↔ WebSockets
– Real-time chat and game data flows.

c. Architectural patterns & design principles
- Layered architecture: presentation (frontend), application/API (REST), real-time (WebSocket), data (PostgreSQL).
- Modular monolith backend: separate Django apps for authentication, chat, game, remote, tournament.
- Security best practices: JWT for stateless auth, 2FA TOTP, HTTPS.
- Containerization: each major component in its own Docker container.

d. Key technologies & libraries
- NGINX (static serving + reverse proxy)
- Django, Django REST Framework
- Django Channels (WebSocket routing and consumers)
- PostgreSQL
- Docker, Docker Compose
- Vanilla JavaScript frontend
- JWT (djangorestframework-simplejwt)
- TOTP 2FA libraries (e.g., PyOTP)

## Diagram (Mermaid)

```mermaid
flowchart TD
    classDef frontend fill:#CCF,stroke:#333,color:#000
    classDef backend fill:#CFC,stroke:#333,color:#000
    classDef db fill:#FC9,stroke:#333,color:#000
    classDef external fill:#DDD,stroke:#333,stroke-dasharray:5 5,color:#000
    classDef tooling fill:#FDD,stroke:#333,color:#000

    Client["Browser UI"]:::frontend
    NGINX["NGINX"]:::frontend
    Client -->|"HTTPS: static assets"| NGINX
    Client -->|"WSS: WebSocket"| NGINX

    NGINX -->|"Proxy /api/*"| RESTAPI
    NGINX -->|"Proxy /ws/*"| WSLayer

    subgraph "Django Backend" 
        direction TB
        RESTAPI["REST API Layer\n(DRF)"]:::backend
        WSLayer["WebSocket Layer\n(Channels)"]:::backend

        subgraph "Authentication Service" 
            direction TB
            AuthModels["models.py"] 
            AuthSerializers["serializers.py"]
            AuthViews["views.py"]
            AuthUtils["utils.py"]
            AuthUrls["urls.py"]
        end

        subgraph "Chat Service"
            direction TB
            ChatConsumers["consumers.py"]
            ChatViews["views.py"]
            ChatRouting["routing.py"]
            ChatUrls["urls.py"]
        end

        subgraph "Game Core Logic"
            direction TB
            GameModels["models.py"]
            GameViews["views.py"]
        end

        subgraph "Remote Game Rooms"
            direction TB
            RemoteConsumers["consumers.py"]
            RemoteViews["views.py"]
            RemoteRouting["routing.py"]
            RemoteUrls["urls.py"]
        end

        subgraph "Tournament Service"
            direction TB
            TourConsumers["consumers.py"]
            TourViews["views.py"]
            TourRouting["routing.py"]
            TourUrls["urls.py"]
        end

        subgraph "Project Configuration"
            direction TB
            ASGI["asgi.py"]
            WSGI["wsgi.py"]
            Settings["settings.py"]
            ProjectUrls["urls.py"]
        end

        subgraph "Static/Media Handling"
            MediaFiles["media"]
        end

        RESTAPI --> AuthUrls
        RESTAPI --> ChatViews
        RESTAPI --> GameViews
        RESTAPI --> RemoteViews
        RESTAPI --> TourViews

        WSLayer --> ChatConsumers
        WSLayer --> RemoteConsumers
        WSLayer --> TourConsumers

        AuthModels --> PostgreSQL
        ChatConsumers --> PostgreSQL
        GameModels --> PostgreSQL
        RemoteConsumers --> PostgreSQL
        TourConsumers --> PostgreSQL
        AuthViews --> PostgreSQL

        AuthUrls --> AuthModels
        ChatUrls --> ChatConsumers
        RemoteUrls --> RemoteConsumers
        TourUrls --> TourConsumers
    end

    PostgreSQL["PostgreSQL\n(container)"]:::db

    AuthenticationService["Authentication Service"]:::backend
    OAuth["42-intra OAuth"]:::external
    AuthenticationService -.->|OAuth handshake| OAuth

    RESTAPI --> PostgreSQL
    WSLayer --> PostgreSQL

    DockerCompose["docker-compose.yaml"]:::tooling
    BackendDockerfile["Dockerfile"]:::tooling
    Deps["dependencies.txt"]:::tooling
    Scripts["script.sh"]:::tooling
    EnvTest[".env.test"]:::tooling
    MakefileNode["Makefile"]:::tooling
    StaticAssets["Frontend Assets\n(frontend/front/)"]:::frontend

    DockerCompose --> NGINX
    DockerCompose --> BackendDockerfile
    DockerCompose --> PostgreSQL

    StaticAssets --> NGINX

    click StaticAssets "https://github.com/amdouyah/ft_transcendence/tree/main/frontend/front/"
    click NGINX "https://github.com/amdouyah/ft_transcendence/blob/main/frontend/conf/nginx.conf"
    click DockerCompose "https://github.com/amdouyah/ft_transcendence/blob/main/docker-compose.yaml"
    click BackendDockerfile "https://github.com/amdouyah/ft_transcendence/tree/main/backend/Dockerfile"
    click AuthModels "https://github.com/amdouyah/ft_transcendence/blob/main/backend/project/authentication/models.py"
    click AuthSerializers "https://github.com/amdouyah/ft_transcendence/blob/main/backend/project/authentication/serializers.py"
    click AuthViews "https://github.com/amdouyah/ft_transcendence/blob/main/backend/project/authentication/views.py"
    click AuthUtils "https://github.com/amdouyah/ft_transcendence/blob/main/backend/project/authentication/utils.py"
    click AuthUrls "https://github.com/amdouyah/ft_transcendence/blob/main/backend/project/authentication/urls.py"
    click ChatConsumers "https://github.com/amdouyah/ft_transcendence/blob/main/backend/project/chat/consumers.py"
    click ChatViews "https://github.com/amdouyah/ft_transcendence/blob/main/backend/project/chat/views.py"
    click ChatRouting "https://github.com/amdouyah/ft_transcendence/blob/main/backend/project/chat/routing.py"
    click ChatUrls "https://github.com/amdouyah/ft_transcendence/blob/main/backend/project/chat/urls.py"
    click GameModels "https://github.com/amdouyah/ft_transcendence/blob/main/backend/project/game/models.py"
    click GameViews "https://github.com/amdouyah/ft_transcendence/blob/main/backend/project/game/views.py"
    click RemoteConsumers "https://github.com/amdouyah/ft_transcendence/blob/main/backend/project/remote/consumers.py"
    click RemoteViews "https://github.com/amdouyah/ft_transcendence/blob/main/backend/project/remote/views.py"
    click RemoteRouting "https://github.com/amdouyah/ft_transcendence/blob/main/backend/project/remote/routing.py"
    click RemoteUrls "https://github.com/amdouyah/ft_transcendence/blob/main/backend/project/remote/urls.py"
    click TourConsumers "https://github.com/amdouyah/ft_transcendence/blob/main/backend/project/tournament/consumers.py"
    click TourViews "https://github.com/amdouyah/ft_transcendence/blob/main/backend/project/tournament/views.py"
    click TourRouting "https://github.com/amdouyah/ft_transcendence/blob/main/backend/project/tournament/routing.py"
    click TourUrls "https://github.com/amdouyah/ft_transcendence/blob/main/backend/project/tournament/urls.py"
    click ASGI "https://github.com/amdouyah/ft_transcendence/blob/main/backend/project/setup/asgi.py"
    click WSGI "https://github.com/amdouyah/ft_transcendence/blob/main/backend/project/setup/wsgi.py"
    click Settings "https://github.com/amdouyah/ft_transcendence/blob/main/backend/project/setup/settings.py"
    click ProjectUrls "https://github.com/amdouyah/ft_transcendence/blob/main/backend/project/setup/urls.py"
    click MediaFiles "https://github.com/amdouyah/ft_transcendence/tree/main/backend/project/media/media"
    click Deps "https://github.com/amdouyah/ft_transcendence/blob/main/backend/tools/dependencies.txt"
    click Scripts "https://github.com/amdouyah/ft_transcendence/blob/main/backend/tools/script.sh"
    click EnvTest "https://github.com/amdouyah/ft_transcendence/blob/main/.env.test"
    click MakefileNode "https://github.com/amdouyah/ft_transcendence/tree/main/Makefile"
```
