diff --git a/README.md b/README.md index d30c946..b8b107e 100644 --- a/README.md +++ b/README.md @@ -1,98 +1,30 @@ -

- Nest Logo -

+# Real-time Leaderboard -[circleci-image]: https://img.shields.io/circleci/build/github/nestjs/nest/master?token=abc123def456 -[circleci-url]: https://circleci.com/gh/nestjs/nest +A full-stack system that provides real-time leaderboard tracking for users across multiple games or activities. The project demonstrates real-time data management, ranking logic, and scalable architecture using modern web technologies. -

A progressive Node.js framework for building efficient and scalable server-side applications.

-

-NPM Version -Package License -NPM Downloads -CircleCI -Discord -Backers on Open Collective -Sponsors on Open Collective - Donate us - Support us - Follow us on Twitter -

- +## Table of Contents -## Description +- [Overview](#overview) +- [Features](#features) -[Nest](https://github.com/nestjs/nest) framework TypeScript starter repository. +## Overview -## Project setup +The **Real-time Leaderboard** project provides a platform where users can: -```bash -$ pnpm install -``` +- Register and authenticate securely. +- Submit scores for various games or activities. +- View a global leaderboard that updates dynamically. +- Track their own ranking in real time. +- Generate reports of top players for a specific time period. -## Compile and run the project +The system leverages Redis sorted sets for efficient real-time leaderboard management, making it scalable and performant. -```bash -# development -$ pnpm run start +## Features -# watch mode -$ pnpm run start:dev - -# production mode -$ pnpm run start:prod -``` - -## Run tests - -```bash -# unit tests -$ pnpm run test - -# e2e tests -$ pnpm run test:e2e - -# test coverage -$ pnpm run test:cov -``` - -## Deployment - -When you're ready to deploy your NestJS application to production, there are some key steps you can take to ensure it runs as efficiently as possible. Check out the [deployment documentation](https://docs.nestjs.com/deployment) for more information. - -If you are looking for a cloud-based platform to deploy your NestJS application, check out [Mau](https://mau.nestjs.com), our official platform for deploying NestJS applications on AWS. Mau makes deployment straightforward and fast, requiring just a few simple steps: - -```bash -$ pnpm install -g @nestjs/mau -$ mau deploy -``` - -With Mau, you can deploy your application in just a few clicks, allowing you to focus on building features rather than managing infrastructure. - -## Resources - -Check out a few resources that may come in handy when working with NestJS: - -- Visit the [NestJS Documentation](https://docs.nestjs.com) to learn more about the framework. -- For questions and support, please visit our [Discord channel](https://discord.gg/G7Qnnhy). -- To dive deeper and get more hands-on experience, check out our official video [courses](https://courses.nestjs.com/). -- Deploy your application to AWS with the help of [NestJS Mau](https://mau.nestjs.com) in just a few clicks. -- Visualize your application graph and interact with the NestJS application in real-time using [NestJS Devtools](https://devtools.nestjs.com). -- Need help with your project (part-time to full-time)? Check out our official [enterprise support](https://enterprise.nestjs.com). -- To stay in the loop and get updates, follow us on [X](https://x.com/nestframework) and [LinkedIn](https://linkedin.com/company/nestjs). -- Looking for a job, or have a job to offer? Check out our official [Jobs board](https://jobs.nestjs.com). - -## Support - -Nest is an MIT-licensed open source project. It can grow thanks to the sponsors and support by the amazing backers. If you'd like to join them, please [read more here](https://docs.nestjs.com/support). - -## Stay in touch - -- Author - [Kamil Myśliwiec](https://twitter.com/kammysliwiec) -- Website - [https://nestjs.com](https://nestjs.com/) -- Twitter - [@nestframework](https://twitter.com/nestframework) - -## License - -Nest is [MIT licensed](https://github.com/nestjs/nest/blob/master/LICENSE). +- **User Authentication:** Secure user registration and login with session or JWT-based auth. +- **Score Submission:** API endpoints to submit and update user scores. +- **Leaderboard Storage:** Uses Redis sorted sets for storing and ranking scores. +- **Real-Time Updates:** Automatic leaderboard refresh on score changes. +- **User Rankings:** Query user rank and score efficiently. +- **Top Players Report:** Generate reports for top players within a given date range. +- **Dockerized Environment:** Full stack runs via Docker for consistent setup across environments. diff --git a/docs/PRD-realtime-leaderboard.md b/docs/PRD-realtime-leaderboard.md new file mode 100644 index 0000000..5a0b473 --- /dev/null +++ b/docs/PRD-realtime-leaderboard.md @@ -0,0 +1,46 @@ +# PRD: Real-Time Leaderboard + +## 1. Project Overview + +The goal is to build a real-time leaderboard platform where users can register, submit scores for different games or activities, and view leaderboards that update in real time. Redis will power the leaderboard ranking logic for performance and scalability, while PostgreSQL will store persistent user and score history data. + +## 2. Core Features + +### 1. User Authentication + +- Users can register and log in using email and password. +- JWT-based authentication (access + refresh tokens). +- Auth endpoints (register, login, logout, refresh). +- Tech: NestJS (Auth module), PostgreSQL (Users table). + +### 2. Score Submission + +- Users submit scores for specific games or activities. +- Each submission updates Redis leaderboard and persists in PostgreSQL for history. +- API validation (score must be numeric, positive, and higher than previous if applicable). +- Tech: NestJS (Scores module), Redis (Sorted Sets), PostgreSQL (ScoreHistory table). + +### 3. Leaderboard Display + +- Global leaderboard showing top N players across all games. +- Individual game leaderboard view (e.g., “Top 10 in Chess”). +- Paginated or infinite scroll leaderboard (Redis rank queries). + +### 4. Real-Time Updates + +- When a user submits a new score, others viewing the leaderboard see live updates. +- Implemented via WebSocket (Socket.IO). +- Tech: Socket.IO integration between NestJS and React. + +### 5. User Rankings + +- Users can view their personal rank and score among all players. +- Endpoint: /leaderboard/:game/my-rank. +- Tech: Redis rank query (ZREVRANK + ZSCORE). + +### 6. Top Players Report + +- Generate reports of top players within a date range. +- Admin or system-generated (JSON or CSV). +- Example: “Top players in Game X between Oct 1–7.” +- Tech: Query PostgreSQL (ScoreHistory) for aggregated data. diff --git a/docs/resources.md b/docs/resources.md new file mode 100644 index 0000000..85c07ed --- /dev/null +++ b/docs/resources.md @@ -0,0 +1,43 @@ +# List of helpful resources to help us during the project + +- [Git](#git) +- [Nest](#nestjs) +- [React](#react) +- [Docker](#docker) +- [Redis](#redis) +- [Testing](#testing) +- [SOLID](#solid) + +## Git + +- [Intermediate Git](https://www.theodinproject.com/paths/full-stack-javascript/courses/javascript#intermediate-git) +- [Github flow](https://docs.github.com/en/get-started/using-github/github-flow) +- [Github Actions -Arabic-](https://youtu.be/7gJFHjXscr8) +- [Github Actions](https://youtu.be/R8_veQiYBjI) + +## NestJS + +- [API with NestJS](https://wanago.io/courses/api-with-nestjs/) + +## React + +- [The Odin Project - React](https://www.theodinproject.com/paths/full-stack-javascript/courses/react) +- [React docs](https://react.dev/) + +## Docker + +- [Docker-Diary](https://github.com/SalmaAlassal/Docker-Diary/tree/main) +- [Get-To-Docker](https://github.com/Open-Source-Community/Get-To-Docker-24) + +## Redis + +- [Redis 101](https://mrinalxdev.github.io/mrinalxblogs/blogs/redis.html) +- [Redis - Arabic](https://www.youtube.com/watch?v=uFwNNqhmhMQ&list=WL&index=4&t=700s) + +## Testing + +- [Jest](https://jestjs.io/docs/getting-started) + +## Solid + +- [SOLID Arabic ](https://youtube.com/playlist?list=PLwWuxCLlF_uevri_OpofVLXkRRFnZ7TSV)