Skip to content

shiftwavedev/ft_transcendence

BranchesTags

Repository files navigation

This project has been created as part of the 42 curriculum by shiftwavedev, Yassop9, Bedelo, yavpar, elz42.

ft_transcendence

License TypeScript React Fastify Prisma

Description

ft_transcendence is a web application built as a full-stack monorepo with a frontend, a backend, and a relational database. It supports multiple authenticated users at the same time and combines real-time gameplay, social interaction, user management, accessibility work, and a maintainable TypeScript architecture.

The application currently includes:

  • secure user registration and login flows with session management
  • public profiles, avatars, friends, and online presence
  • real-time chat and real-time game rooms using WebSockets
  • live Tic-Tac-Toe matches in both 1v1 and 1v1v1
  • a 3x3 board for 1v1 and a 4x4 board for 1v1v1
  • a best-of-3 match flow with round transitions
  • player statistics, match history, achievements, and leaderboard views
  • an admin dashboard with user management and activity indicators
  • responsive, accessible, and multilingual user interfaces
  • Privacy Policy, Terms of Service, and GDPR data export features

42 Score Summary

The claimed module set below reaches 25 points.

This total reflects the modules implemented by the team. As specified by the subject, only the points above the mandatory minimum may be considered as bonus, with a maximum bonus of 5 additional points during evaluation.

Category Module Type Points
Web Use a framework for both the frontend and backend Major 2
Web Implement real-time features using WebSockets or similar technology Major 2
Web Allow users to interact with other users Major 2
Web Use an ORM for the database Minor 1
Web Custom-made design system with reusable components, including a proper color palette, typography, and icons Minor 1
Accessibility and Internationalization Complete accessibility compliance (WCAG 2.1 AA) with screen reader support, keyboard navigation, and assistive technologies Major 2
Accessibility and Internationalization Support for multiple languages (at least 3 languages) Minor 1
Accessibility and Internationalization Support for additional browsers Minor 1
User Management Standard user management and authentication Major 2
User Management Advanced permissions system Major 2
User Management Game statistics and match history Minor 1
User Management User activity analytics and insights dashboard Minor 1
Gaming and User Experience Implement a complete web-based game Major 2
Gaming and User Experience Remote players Major 2
Gaming and User Experience Multiplayer game (more than two players) Major 2
Data and Analytics GDPR compliance features Minor 1
Total 25

Additional work present in the repository but not counted in the 25-point total:

  • a rate-limited REST API surface with many authenticated endpoints
  • CSRF protection
  • encrypted chat message storage
  • session management and multi-session revocation

Team Information

Login Assigned Role(s) Responsibilities
shiftwavedev Technical Lead / Architect, Developer Defined the overall architecture, structured the monorepo, led backend design decisions, integrated the admin dashboard and analytics stack, and reviewed critical code paths.
Yassop9 Product Owner, Developer Drove product scope and priorities, validated user-facing flows, helped shape gameplay and profile features, and contributed to internationalization and integration work.
Bedelo Project Manager / Scrum Master, Developer Coordinated milestones and team synchronization, tracked blockers, and contributed to gameplay, chat, legal pages, and UI refinements.
yavpar Developer Contributed to multiplayer integration, profile and social flows, bug fixing, validation, and end-to-end feature polishing.
elz42 Developer Contributed to implementation, testing, reviews, and module documentation across the project.

Team size: 5 members. All members contributed to the mandatory part and participated in review, testing, and integration.

Project Management

  • The team first implemented the mandatory web application core, then layered modules on top of that base.
  • Work was split into small feature slices: authentication, social features, real-time game logic, profile management, analytics, and accessibility.
  • Pull requests and commit history were used to keep work traceable and reviewable.
  • Regular sync points were used to unblock integration and align feature priorities.
  • Critical backend and shared-type changes were reviewed before merge to keep contracts stable between frontend and backend.
  • The team used an iterative workflow inspired by Scrum, with short feedback loops and progressive integration into dev before release.
  • Responsibilities were distributed so that each member contributed to the mandatory application core as well as to claimed modules.

Workflow

  • Monorepo with separated frontend, backend, shared-types, and shared config packages
  • GitHub Issues and project boards for task tracking and backlog organization
  • Feature-oriented branches and pull requests
  • Conventional commit style enforced with Commitlint
  • GitHub issue templates and PR templates for task tracking and review discipline
  • Automated quality checks through GitHub Actions
  • Discord used as the main day-to-day communication channel

Technical Stack

Frontend

  • React 19 + Vite Chosen for a fast development loop, component-based UI, and a modern TypeScript workflow.
  • React Router Used for protected routes, public profile pages, game room navigation, and admin access control.
  • Tailwind CSS v4 + custom CSS tokens Used to build a reusable design system with shared colors, typography, and visual rules.
  • TanStack Query Used for API state synchronization, caching, retries, and dashboard/profile data loading.
  • Zod Used for client-side form validation and shared schema-driven contracts.

Backend

  • Fastify Chosen for performance, plugin-based organization, and a clean TypeScript experience.
  • Fastify WebSocket Used for live chat and synchronized game rooms.
  • JWT + cookie-based sessions Used for authentication, refresh sessions, and protected routes.
  • bcrypt Used for password hashing.
  • Prisma ORM Used to model the relational data layer and keep backend data access explicit and typed.
  • Sharp Used for avatar normalization and server-side image processing.
  • Node.js Crypto Used for CSRF token generation, hashing helpers, and AES-256-GCM message encryption support.

Database

  • SQLite + Prisma Chosen for simple local setup, deterministic development, and a clear relational schema suited to the project scope.

Shared Packages and Tooling

  • pnpm workspaces Keeps the monorepo organized and avoids duplicated dependencies.
  • Shared Zod schemas Ensures the frontend and backend use the same request and response contracts.
  • Vitest Used for backend unit and route testing.
  • ESLint + Prettier + Husky + Commitlint Enforces consistency and review quality.

Architecture Overview

ft_transcendence/
├── apps/
│   ├── backend/      Fastify API, WebSockets, Prisma, auth, game logic
│   └── frontend/     React SPA, routing, forms, dashboard, design system
├── packages/
│   ├── shared-types/ Shared Zod schemas and TypeScript types
│   └── config/       Shared ESLint and TypeScript configuration
└── .github/          CI workflows, issue templates, PR templates

Database Schema

The application uses a relational schema centered on users, live sessions, social links, games, and progression data.

erDiagram
    Users ||--o{ RefreshSessions : owns
    Users ||--o{ UserConsents : records
    Users ||--o{ Messages : sends
    Users ||--o{ Friendships : requests
    Users ||--o{ Friendships : receives
    Users ||--o{ GamePlayers : joins
    Users ||--o{ GameMoves : plays
    Users ||--o| PlayerStats : has
    Users ||--o{ UserAchievements : unlocks
    Users ||--o{ Games : wins

    Games ||--o{ GamePlayers : contains
    Games ||--o{ GameMoves : stores

    Users {
        int id PK
        string firstname
        string lastname
        string username
        string email
        string password
        string role
        string language
        string avatar
        int lastSeenAtMs
    }

    RefreshSessions {
        int id PK
        int userId FK
        string jti
        string tokenHash
        int expiresAtMs
        int createdAtMs
        int revokedAtMs
        string userAgent
    }

    UserConsents {
        int id PK
        int userId FK
        int consentGiven
        int consentDate
    }

    Friendships {
        int id PK
        int requesterId FK
        int addresseeId FK
        string status
        int createdAtMs
        int updatedAtMs
    }

    Messages {
        int id PK
        int senderId FK
        string content
        int createdAtMs
    }

    Games {
        int id PK
        string roomId
        string roomName
        string mode
        string visibility
        string status
        int winnerId FK
        string boardState
        int createdAtMs
        int startedAtMs
        int endedAtMs
    }

    GamePlayers {
        int id PK
        int gameId FK
        int userId FK
        string symbol
        int joinedAtMs
    }

    GameMoves {
        int id PK
        int gameId FK
        int playerId FK
        int moveNumber
        int row
        int col
        int timestamp
    }

    PlayerStats {
        int id PK
        int userId FK
        int gamesPlayed
        int gamesWon
        int gamesLost
        int gamesDraw
        int winStreak
        int bestWinStreak
        int lastPlayedAtMs
    }

    UserAchievements {
        int id PK
        int userId FK
        string achievementKey
        int unlockedAtMs
    }
Loading

Key Relations

  • Users is the central table and links authentication, social features, gameplay, stats, and achievements.
  • RefreshSessions stores revocable refresh tokens for multi-session account management.
  • Friendships stores bidirectional social relationships with a request/accept lifecycle.
  • Games, GamePlayers, and GameMoves model each room, participants, and move history.
  • PlayerStats and UserAchievements store persistent progression data.
  • UserConsents records legal acceptance for privacy-related flows.

Data Conventions

  • All application timestamps are stored as Unix milliseconds (*AtMs) for consistency across the backend and frontend.
  • Authentication sessions are stored in database rather than only in signed cookies, allowing revocation and active session management.
  • Chat messages are encrypted before persistence and decrypted only when served back to authenticated clients.

Features List

Feature Description Team Member(s)
Authentication and sessions Registration, login, logout, refresh token rotation, multi-session revocation, password updates, account deletion shiftwavedev, Yassop9, yavpar
Profiles and avatars Public profiles, editable account settings, avatar upload and deletion, language preferences shiftwavedev, Yassop9, yavpar
Social layer Friends list, pending requests, public user pages, online presence, real-time global chat shiftwavedev, Bedelo, yavpar
Real-time gameplay Create and join rooms, synchronized live matches, reconnect-friendly rooms, 1v1 and 1v1v1 modes shiftwavedev, Bedelo, Yassop9, yavpar
Progression Player stats, match history, achievements, leaderboard widgets, recent activity panels shiftwavedev, Yassop9
Admin dashboard User CRUD, role management, top-player views, activity KPIs, charts, game overview shiftwavedev
Accessibility and i18n Keyboard-aware UI patterns, accessible components, skip link, ARIA support, English/French/Spanish translations shiftwavedev, Yassop9, Bedelo
Compliance Privacy Policy, Terms of Service, consent recording, GDPR data export shiftwavedev, Bedelo, Yassop9
Design system Shared tokens, reusable components, theme support, consistent typography and UI patterns shiftwavedev
Validation Shared frontend/backend validation with Zod schemas, route validation, and guarded form flows shiftwavedev, Yassop9, yavpar
Security hardening Rate limiting, CSRF validation, secure cookies, brute-force mitigation, encrypted chat persistence shiftwavedev
CI and code quality GitHub Actions, linting, type checking, commit rules, test automation shiftwavedev, elz42

Modules

Web

  • Major - Use a framework for both the frontend and backend (2 pts) We chose React for the frontend and Fastify for the backend to keep the project fully TypeScript-based and modular. This decision gave us clear routing, state management patterns, and a consistent developer workflow across the full stack.
    Main contributors: shiftwavedev, Bedelo, Yassop9, yavpar

  • Major - Implement real-time features using WebSockets or similar technology (2 pts) Live communication is implemented through WebSockets for both global chat and game rooms. The game flow handles joins, leaves, heartbeats, disconnects, and reconnection-oriented room logic. The same real-time layer powers both remote play and social interaction.
    Main contributors: shiftwavedev, Bedelo, Yassop9, yavpar

  • Major - User interaction (2 pts) The application includes a basic chat system, public profile pages, and a friends system with pending requests, accepted relationships, removal, and presence information.
    Main contributors: shiftwavedev, Bedelo, yavpar

  • Minor - ORM (1 pt) We use Prisma as the ORM to model our relational schema, keep migrations explicit, and preserve type-safe data access.
    Main contributors: shiftwavedev

  • Minor - Custom-made design system with reusable components, including a proper color palette, typography, and icons (1 pt) We implemented a custom design system based on shared tokens and reusable UI primitives. It includes a defined color palette, typography choices, icons, and more than ten reusable components and patterns across the application, including buttons, cards, inputs, checkboxes, alerts, avatars, theme controls, layout headers, language switchers, navigation primitives, and branded UI assets.
    Main contributors: shiftwavedev

Accessibility and Internationalization

  • Major - Complete accessibility compliance (WCAG 2.1 AA) with screen reader support, keyboard navigation, and assistive technologies (2 pts) Accessibility work targets the requirements expected by the subject: keyboard navigation, semantic controls, ARIA labels and roles, screen-reader-friendly alerts, skip navigation, focus management, and keyboard interaction on gameplay UI.
    Main contributors: shiftwavedev, Yassop9, Bedelo

  • Minor - Support for multiple languages (at least 3 languages) (1 pt) The interface is fully translatable and currently ships with English, French, and Spanish. The language can be selected in the UI and is also stored as a user preference.
    Main contributors: shiftwavedev, Yassop9, Bedelo, yavpar

  • Minor - Support for additional browsers (1 pt) Beyond the required latest stable Chrome version, the project was also validated on Firefox and Safari with the same core flows: authentication, profile management, chat, lobby access, and gameplay.
    No browser-specific limitations were identified on those validated flows at the time of writing.
    Main contributors: team-wide validation

User Management

  • Major - Standard user management and authentication (2 pts) Users can register, log in securely, manage their profile, upload an avatar, update their password, revoke sessions, delete their account, add friends, and view profile pages. Authentication is backed by hashed passwords, refresh sessions in database, account lockout logic, and CSRF protection for state-changing requests.
    Main contributors: shiftwavedev, Yassop9, yavpar

  • Major - Advanced permissions system (2 pts) We implemented an admin-only dashboard with role-aware routes and actions. Admins can list users, edit users, delete users, and manage roles, while regular users are restricted from admin views and actions.
    Main contributors: shiftwavedev

  • Minor - Game statistics and match history (1 pt) Each player has persistent stats, a match history, and friend-aware leaderboard views. Match outcomes update progression automatically at the end of each game.
    Main contributors: shiftwavedev, Yassop9

  • Minor - User activity analytics and insights dashboard (1 pt) The admin dashboard exposes user and platform activity indicators such as registrations over time, active sessions, total messages, game volume, mode distribution, and top-performing users.
    Main contributors: shiftwavedev

Gaming and User Experience

  • Major - Implement a complete web-based game where users can play against each other (2 pts) The project includes a complete multiplayer Tic-Tac-Toe experience with clear rules, score handling, victory conditions, move history, best-of-3 rounds, and a dedicated game room flow.
    Main contributors: shiftwavedev, Bedelo, Yassop9, yavpar

  • Major - Remote players (2 pts) The game is designed for players on separate machines through WebSocket room synchronization, reconnect-oriented room management, and disconnection handling. Separate-machine validation remains part of the final evaluation checklist.
    Main contributors: shiftwavedev, Bedelo, Yassop9, yavpar

  • Major - Multiplayer game with more than two players (2 pts) In addition to the classic 1v1 mode, we implemented a 1v1v1 variant with dedicated game logic, player symbols, round handling, and persistent match storage.
    Main contributors: shiftwavedev, Bedelo, Yassop9, yavpar

Data and Analytics

  • Minor - GDPR compliance features (1 pt) The application records privacy consent, provides a user data export endpoint, exposes the feature directly in the user settings page, and allows full account deletion.
    Main contributors: shiftwavedev, Bedelo, Yassop9

Additional Implemented Work Not Counted in the 25 Points

  • A large authenticated REST API surface with endpoints such as /api/login, /api/register, /api/profile, /api/friends, /api/chat/history, /api/game/create, /api/stats/*, and /api/admin/*
  • Global rate limiting on the backend
  • CSRF protection for state-changing API requests
  • Encrypted storage of chat messages at rest

This work is intentionally not counted as the subject's public API module because the README does not currently claim a secured API key workflow, dedicated public API documentation, or a separate public API posture.

Individual Contributions

shiftwavedev

  • defined the monorepo architecture and shared package structure
  • implemented or integrated major backend systems: auth, sessions, Prisma schema, game manager, admin routes, analytics, GDPR export, and design system foundations
  • led code review on critical modules and stabilized cross-package TypeScript contracts

Yassop9

  • shaped the product scope and acceptance criteria
  • contributed to gameplay integration, profile flows, translations, and final user-facing coherence
  • helped validate the counted modules and the final project direction

Bedelo

  • coordinated project execution and milestone tracking
  • contributed to gameplay flow, chat-related UX, legal pages, and frontend refinements
  • helped align delivery order between mandatory features and module work

yavpar

  • contributed to multiplayer gameplay integration, profile and social flows, and bug fixing
  • participated in feature polishing and validation of end-to-end flows
  • supported integration across frontend and backend user-facing features

elz42

  • contributed to implementation support, review, testing, and technical documentation
  • participated in team validation and integration work during project delivery

Challenges Faced and How They Were Addressed

  • Mid-project change of direction The team had to change project direction during development, which cost time and created additional implementation work. To recover, the scope was refocused on a coherent multiplayer Tic-Tac-Toe platform and the remaining work was reorganized into smaller, high-priority milestones.

  • TypeScript ecosystem and security maintenance The imposed TypeScript-based stack brought frequent dependency, typing, and security-related fixes during development. The team addressed this by relying on stricter shared typing, frequent dependency checks, linting, and repeated validation across frontend and backend contracts.

  • Accessibility compliance across the full application Achieving consistent accessibility behavior everywhere was more difficult than expected, especially across forms, navigation, alerts, and gameplay interactions. The team handled this by iterating on keyboard navigation, focus management, ARIA usage, semantic HTML, and contrast checks until the main user flows were consistent.

  • UI edge cases such as the toggle button behavior Some interface details were unexpectedly time-consuming, especially toggle-related behavior and browser-specific rendering quirks. These issues were resolved through repeated frontend testing, CSS adjustments, and cross-browser checks.

  • Security anticipation Anticipating security issues early enough was challenging because many concerns only became visible during implementation and integration. The team progressively reinforced the project with hashed passwords, CSRF protection, rate limiting, secure cookies, session revocation, and encrypted chat storage.

  • Learning the stack at the start of the project The team had to learn new technologies, tools, and development patterns while building the application. This was addressed through documentation, experimentation, peer discussion, and gradual standardization of conventions inside the monorepo.

Instructions

Prerequisites

  • Node.js 20+
  • pnpm 10+
  • a recent browser, with Chrome latest stable as the main target
  • optional: VS Code + Dev Containers if you want to use the provided development container

Current Local Development Run

0. Clone the Repository

git clone https://github.com/shiftwavedev/ft_transcendence.git
cd ft_transcendence

1. Run the Project

docker compose -f docker-compose.dev.yml up -d

2. Access Content

http://localhost:3000  (frontend)
http://localhost:5555  (prisma)
http://localhost:8000  (backend)

Quality Checks (in container)

pnpm lint
pnpm typecheck
pnpm build
pnpm --filter @ft-transcendence/backend test

Final Containerized Submission Run

The final single-command containerized run required for submission will be inserted here once the team freezes the exact deployment command used for evaluation.

Development Container

A development container is available in .devcontainer/ for a consistent local environment.

Testing and Validation

Main commands used during development:

pnpm lint
pnpm typecheck
pnpm build
pnpm --filter @ft-transcendence/backend test
pnpm --filter @ft-transcendence/backend test:coverage

Validation focus before evaluation:

  • authentication and profile flows
  • multi-user chat
  • room creation and join flow
  • 1v1 and 1v1v1 gameplay
  • remote play on separate machines
  • admin dashboard access and role-based actions
  • GDPR export and account deletion
  • browser compatibility and accessibility checks

Resources

Documentation and References

Books and Print References

  • CSS - Micro Application, collection "Super Poche"
  • Scripts Shell Linux et Unix (2nd edition) - Christophe Blaess, Eyrolles
  • Git par la pratique - David Demaree, Eyrolles
  • Bases de donnees - Les systemes et leurs langages - Georges Gardarin, Eyrolles

How AI Was Used

AI was used to speed up repetitive and low-value tasks, not to replace understanding or peer review.

The main AI tools used during the project were Codex and Claude, depending on the task and stage of development.

It was used for:

  • brainstorming implementation approaches and refactor options
  • reviewing wording for documentation and legal pages
  • generating checklists for validation and testing
  • helping summarize and reorganize technical notes
  • exploring architectural tradeoffs and module strategy
  • scaffolding repetitive handlers, schemas, and test patterns
  • debugging real-time race conditions and security flows
  • helping produce technical documentation and README structure

Every AI-assisted output was manually reviewed, discussed, and either corrected or rewritten by team members before being kept. The team only retained code and documentation it could explain and maintain.

Final Validation Notes

  • The main evaluation target is the latest stable version of Chrome, with Firefox and Safari included in browser validation.
  • Multi-user flows, remote play on separate machines, admin actions, GDPR export, and accessibility checks are part of the final validation checklist before submission.
  • The final containerized submission command will be documented once the deployment setup is frozen by the team.

License

This project is licensed under the AGPL-3.0 license. See LICENSE for details.

About

ft_transcendence is a tic-tac-toe game

ftt.shiftwave.me/

Topics

42 42school transcendence transcendence-v2

Resources

Readme

License

AGPL-3.0 license
Activity

Stars

4 stars

Watchers

0 watching

Forks

2 forks
Report repository

Contributors

Languages