This project has been created as part of the 42 curriculum by gkarina, rmander, hmeriann, dsewlia

ft_transcendence

Description

ft_transcendence is an MPA Web application built as the final project of the 42 Core curriculum. The goal of this project is to design and implement a multiplayer web-based ping pong game with the ability to host friendly matches as well as tournaments, add each other into friends and just to have fun.

The application allows users to:

• Play a 2-player Pong game locally on the same keyboard
• Participate in tournament brackets inspired by Grand Slam tennis formats
• Track performance through statistics and leaderboards
• Add another users into friends
• Securely logging in without and with 42 OAuth

Key Features

• Local multiplayer Pong game
• User authentication (including OAuth2 via 42 and 2FA)
• Role-based access control (Admin, Organizer, User)
• Tournament system (random seeded knockout tournaments)
• Leaderboard and match history
• Monitoring with Prometheus and Grafana

Instructions

Prerequisites

Make sure you have the following installed:

• Node.js >= 22
• npm >= 11.7
• Docker >= 29.1

Environment Setup

Create a .env file in the root directory. You can find the example (.env.sample) at the root folder of the project repository.

Installation

Clone the repository

git clone https://github.com/mikhdm/ft_transcendence.git project_name
cd project_name/ft_transcendence/

Running the Project

Build project and start containers

make all

Stop and remove containers

make down

stop and delete all containers, images, networks and build cache

make clean

Clean database and remove all docker volumes

make clean.volume

Full reset

make re

Access the app

https://localhost:8443

OAUTH2 (42 Login) and 2FA

For more safety and security, every user can turn on 2 Factor Authentication in their personal account. Go to your account, press the EDIT button — there will be a slider at the end of the EDIT PROFILE window. You have to pre-download Google Authenticator for iOS or Google Authenticator for Android beforehand. After turning on 2FA you will see a QR Code — scan it and add it to Google Authenticator. Then enter the code and your account is secured.

To turn off 2FA, go to your personal account, press the EDIT button, scroll to the end and toggle 2FA off, then enter the code from Google Authenticator to confirm.

Please note: we currently do not support account recovery if you accidentally delete the Google Authenticator app or remove the entry for this account from it. We sincerely apologize for this limitation and hope to address it in the future.

Team Information

Svetlana Mikhailenko

42 Login: gkarina

Role(s): Team Lead, Developer

Responsibilities:

• Lead and manage a team of developers
• Oversee code reviews and implement unit tests
• Backend architecture, initial server setup, user authentication, error handling and routing strategies
• Implementing - Prometheus and grafana for monitoring

Dmitrii Mikhailenko

42 Login: rmander

Role(s): Project Manager, Developer

Responsibilities:

• Frontend architecture and implementation of UI.
• Defining and implementing deployment strategies.
• Maintaining team coordination via kanban and addressing timelines.
• Oversee code reviews

Zuleykha Pavlichenkova

42 Login: hmeriann

Role(s): Product Owner, Full-stack Developer

Responsibilities:

• Designing and implementing the Pong game logic
• Integrating OAuth2 authentication via the 42 API
• Defining and implementing leadboard and statistics

Dev Sewlia

42 Login: dsewlia

Role(s): Architect and Developer

Responsibilities:

• Backend architecture, building APIs and desgining database schemas
• Defining and implementating policies
• Designing and implementing the backend for matches and tournaments
• Preparing documentation for the project

Project Management

Overview

• Work was divided into modules and features
• Regular team meetings:
  • Every Tuesday in the second half - online and offline
• Task distribution:
  • Divided as per capabilities across game, frontend, backend, devops
• Code review:
  • Distributed evenly as per availability and capabilities

Tools Used

Task organization

• GitHub projects kanban board
• Miro dashboard

Documentation

• Miro

Communication channel(s)

• Slack

Technical Stack

Frontend

• Vue.js
• Tailwind CSS

Backend

• Node.js
• Fastify Web framework

Database

• SQLite (better-sqlite3)
• Reason for choice:
  • Simple and reliable (ACID compliant)
  • Embedded database, no need for a separate database server
  • Lightweight and fast
  • Ease of setup (no configuration required)
  • Synchronous API (provides predictable, fast execution with call or promise overhead)
  • Good match for this application

Observability

• Prometheus
• Grafana
• Alertmanager with Telegram connection for alerts

Other Technologies

• OAuth2 via 42 Login
• 2FA through Google Authenticator

Technical Choices Justification

• Vue.js: lightweight, component-based architecture
• Fastify: high performance and low overhead
• Tailwind CSS: rapid UI development and consistency
• Prometheus & Grafana: robust monitoring and observability

Project Architecture

Database Schema

We maintained a detailed schema using Miro.

Tables

• users
• matches
• tournaments
• friend_requests

Pivot tables

• tournament_player
• friends

Relationships

• users and matches (one(per player field)-to-many)
• users and tournaments (many-to-many via tournament_player)
• users and users (many-to-many via friends)
• tournaments and matches (one-to-many)

Visual Representation

Features List

Game

• Local Pong Game
• 2 players on same keyboard

Authentication

• Standard Authentication System
• OAuth2 (42 Login)
• 2FA

Policy System

• Role-based access (Admin, Organizer, User/Common)

Friends System

• Send/cancel friend request
• Reject/accept friend request
• Remove from friends
• View online status

Tournament System

• Grand Slam-style brackets
• Random seeding

Game Statistics & Leaderboard

• Matches played, wins, losses
• Recent form (e.g., WWLWL)
• Ranking system

Search System

• Filters, sorting, pagination

Monitoring

• Prometheus via fastify-metrics & Grafana
• Standard Node.js and per-route HTTP metrics (1-4 panels)
• Custom metrics: active WebSocket connections gauge, match counter by type and outcome, match duration histogram, and active tournaments gauge by status (5-8 panels)

Modules

Major Modules (2 points each)

Web-Based Game

• A real time multiplayer 2D ping pong game playable on the same system.
• Ability to play live matches and participate in knockout tournaments

Standard User Management & Authentication

• Standard user management wherein users can update profile
• Acess to their own profle pages.
• Can add other users as friends and see online status

Policy System (Advanced CRUD)

• Defined 3 roles across users - admin, organizers and common.
• Admin can grant any user either organizer or admin privilages.
• Admin can view, delete any user, can view and manager any tournament
• Organizer can create and manage their respective tournaments

Monitoring (Prometheus & Grafana)

• System monitoring and metrics done via Prometheus and grafana

Minor Modules (1 point each)

Frontend Framework

• Vue.js

Backend Framework

• Fastify

Custom-made design system with reusable components

• Over 10 reusable components such as avator, button, dropdown, footer, navbar, etc

Support for additional browsers

• Consistant ui across multiple browers such as Chrome, Chromium, Firefox and Brave

Game statistics and history

• Leaderboard that tracks users with most win in least amount of games played
• Users can view their individual game history - matches played, matches won
• Users can view their form (results form the last 5 matchs eg: "WWLWL")

OAuth2

• Available login/registering via the 42 OAuth

2FA implementation

• 2FA available via Google Authenticator

Tournament system

• A grand slam style knockout tournament with a maximum of 64 players.
• Seeds are randomly allocated and bye matches are implemented uniformly as per the seeds

Advanced search

• Advanced serach implemented in user search done via query parameters.

Custom Minor Modules (1 point each)

User interaction

• Partial implementation of the defined major module user interaction
• Users can view other users, make friends, follow and view profiles

Total Points : 18

• Major: 8 points
• Minor: 9 points
• Custom Minor: 1 point
• Total: 18 points (minimum required: 14)

Individual Contributions

gkarina

• Designed and implemented the users and friends database schema, built standard user authentication (login/logout/session) and 2FA, and wrote backend tests

Challenges:

• Structuring the users and friends tables correctly, implementing secure authentication with 2FA support, and covering the backend with tests

Solutions:

• Researched each topic independently and implemented solutions step by step

rmander

• Bootstrapped the frontend (TypeScript, Tailwind, Vue.js), architected the UI and the reusable design system components, and implemented the tournaments pages with brackets and modals.
• Set up the deployment topology: nginx reverse proxy gateway, frontend/backend Dockerfiles, docker-compose for app + ops — and aligned the Prometheus + Alertmanager + Grafana stack with custom metrics for matches, tournaments, and WebSocket connections, with ability to send alerts to Telegram dedicated group.

Challenges:

• Keeping the frontend from duplicating backend authorization rules, scaling the modal layer across many forms, and wiring frontend, backend, gateway, and the ops stack behind a single reverse proxy

Solutions:

• Enforced a layered API pattern (client → api/<resource> → use<Resource> composable), made modals presentation only with parents owning side effects, and split docker-compose into clearly separated app and ops blocks with nginx as the only public entrypoint.

hmeriann

• Designed and implemented the 2D ping pong game, integrated OAuth2 via 42 and leaderboard module

Challenges:

• Building the game loop and rendering logic so that the Pong game felt responsive and worked correctly in the browser
• Integrating OAuth2 login with backend sessions and user creation
• Designing leaderboard ranking so users with the same results could receive the same rank while keeping output predictable

Solutions:

• Built the game logic step by step around reusable game classes and canvas rendering
• Connected the 42 OAuth2 callback flow with backend user lookup/creation and session handling
• Implemented dense ranking, limit and offset, privacy-friendly response fields, and tests for edge cases

dsewlia

• Architect and maintainer of the backend code base
• Defined and implemented policies
• Designed and implemented the backend for matches and tournament

Challenges:

• Aligning with frontend developers for API communication

Solutions:

• Everything went on miro - schemas, database relation, API endpoints, request + response schema, logical flows, future updates

Resources

Documentation & References

• Vue.js Documentation
• Fastify Documentation
• Tailwind CSS Documentation
• 42 OAuth2 Documentation
• Prometheus & Grafana Documentation
• Game Free course lectures

AI Usage

AI tools were used for:

• README structuring and formatting
• Debugging assistance
• Code suggestions for:
  • Best practices of fastify - stateless validation via schemas, policy called via handlers
  • Game
  • Leaderboard API
  • OAuth 2.0
• Learning unfamiliar concepts
• Test generations

All generated content was reviewed, tested, and adapted by the team.

Additional Information

Known Limitations

• No remote multiplayer support
• Tournament seeding is random
• Chat system is to be implemented

Future Improvements

• Online multiplayer support
• Improved matchmaking & ranking system
• Support seeding via match results and manually via creation page
• Multi-tenancy support (to add different organization)
• Chat support (database design already in miro)

License

MIT License

Copyright (c) [2026] [Dmitrii Mikhailenko, Svetlana Mikhailenko, Zuleykha Pavlichenkova, Dev Sewlia]

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.