A comprehensive gamification engine built with Node.js, React, and PostgreSQL. This platform provides a complete solution for implementing gamification features in e-learning, e-commerce, or any web application.
Runs with a single docker-compose up.
Features: Point system, level progression, badge management, leaderboards, real-time updates, and admin dashboard.
- the app have both user view and admin view
- by default (one the backend starts ) some data is seeded to data base
- those are 2 accounts for testing that you can use
- admin
email: 'user.admin@ejada.com', password: 'root123', - user
email: 'user1@ejada.com', password: 'root123',
- Manual Setup
- Docker Setup
- System Architecture
- Database Design
- Backend API
- Frontend Features
- Task Structure
- Node.js 18+
- PostgreSQL 15+
- Docker (for containerized setup)
# Database Configuration
DATABASE_URL="postgresql://root:root@localhost:5432/gamification"
# Server Configuration
PORT=8000
NODE_ENV=development
# JWT Configuration
JWT_SECRET=your-super-secret-jwt-key-2024
JWT_EXPIRES_IN=7d
# CORS Configuration
CORS_ORIGIN=http://localhost:3000
# Redis Configuration (Optional)
REDIS_URL=redis://localhost:6379
# Logging
LOG_LEVEL=debug
# API Configuration
API_PREFIX=/api
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX_REQUESTS=100
# Security
BCRYPT_ROUNDS=12
SESSION_SECRET=your-session-secret-key
# Development
DEBUG=true
ENABLE_SWAGGER=trueNEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_WS_URL=ws://localhost:8000# Install PostgreSQL
# Download from: https://www.postgresql.org/download/
# Create database
createdb gamification
# Copy environment file
cp backend/env.example backend/.env
# Update database URL in .env file
DATABASE_URL="postgresql://username:password@localhost:5432/gamification"cd backend
npm install
npm start
# API Documentation
# Swagger UI: http://localhost:8000/api-docs
# API Base URL: http://localhost:8000/apicd frontend
npm install
npm run dev
# Frontend Application
# URL: http://localhost:3000| Service | Port | Description |
|---|---|---|
| Frontend | 3000 | Next.js React Application |
| Backend | 8000 | Node.js Express API |
| PostgreSQL | 5432 | Database |
# Start all services
docker-run.bat start
# Stop all services
docker-run.bat stop
# View logs
docker-run.bat logs
# Check status
docker-run.bat status# Start all services
./docker-run.sh start
# Stop all services
./docker-run.sh stop
# View logs
./docker-run.sh logs
# Check status
./docker-run.sh statusThe core of the gamification engine is designed to make user engagement both rewarding and dynamic. A point system lets users earn points for specific actions, such as completing tasks or participating in activities. As points accumulate, users unlock new levels, creating a sense of progression and achievement. Badges are awarded based on defined criteria, celebrating milestones and encouraging continued participation. Leaderboards introduce a competitive element, with rankings that can be updated daily, weekly, or monthly to keep things fresh and motivating.
The typical user engagement flow starts when a user performs an action. This triggers a point award, followed by a check to see if the user qualifies for a new level or badge. If so, the system updates the user’s status and reflects these changes on the leaderboard. For example, after completing a course, a user might earn points, level up, unlock a badge, and see their ranking improve—all in one seamless flow.
Multi-tenancy support ensures that each client, whether it’s a school, business, or community, has its own private data space. This means information stays separate and secure for every tenant. Rules can be customized, so one client might set different point values or badge requirements than another. Branding is also flexible, allowing each tenant to have their own themes and logos for a unique experience.
Scalability is addressed through several strategies. Redis caching can be used for frequently accessed data like leaderboards and user statistics, improving performance and responsiveness. Asynchronous processing with message queues helps handle point calculations and other background tasks efficiently. Database optimization is possible with indexed queries and materialized views, supporting fast and reliable data access even as the platform grows.
To keep the architecture maintainable and extensible, several reusable modules can be introduced. The Badge Service manages badge creation, assignment, and validation. The Point Engine handles all point calculations and level progression logic. The Leaderboard Service generates and maintains competitive rankings, while the Notification Service sends alerts for achievements and milestones. An Analytics Service tracks user engagement and overall system performance, providing valuable insights for continuous improvement.
Swagger UI: http://localhost:8000/api-docs
API Base URL: http://localhost:8000/api
The API uses standard HTTP status codes and returns consistent error responses:
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid input data",
"details": {
"field": "email",
"reason": "Email is required"
}
}
}The frontend provides a comprehensive admin/user dashboard with the following features:
Multi-tenancy support means that every client—whether it’s a school, a business, or a community—gets their own private data space, so information stays separate and secure. For example, a fitness app and an e-learning platform could both use the system, but each would have its own users, points, badges, and rules. It’s easy to set up different point values or badge requirements for each tenant, so one client might reward users for daily logins while another focuses on course completions. Branding is also fully customizable, allowing each tenant to have their own colors, logos, and themes for a unique look and feel. Onboarding new tenants is simple and fast, thanks to automated, API-driven processes that handle everything from account creation to initial setup—making it easy to get started without manual intervention.
A modular approach is used to keep the system maintainable and extensible. The Badge Service manages badge creation, assignment, and validation, while the Point Engine is responsible for point calculations and level progression. The Leaderboard Service generates and maintains competitive rankings, and the Notification Service sends alerts for achievements and milestones. An Analytics Service tracks user engagement and overall system performance, providing valuable insights.
Scalability can be achieved through several architectural choices. Redis caching can be used for frequently accessed data like leaderboards and user statistics, which helps improve performance and responsiveness. Asynchronous processing with message queues is useful for handling point calculations and other background tasks efficiently. Database optimization can be accomplished with indexed queries and materialized views, supporting fast and reliable data access. Horizontal scaling with load balancing is another approach to handle increased traffic
Effective engineering practices and team management are essential for delivering high-quality software. Ensuring consistent code quality starts with adopting TypeScript across both the frontend and backend, providing type safety throughout the codebase. Automated tools like ESLint and Prettier are used for code formatting and linting, helping maintain a clean and uniform style. Code reviews are a standard part of the workflow, with every pull request reviewed by at least one team member to catch issues early and encourage knowledge sharing. A robust testing strategy is in place, combining unit tests for business logic with integration tests for APIs to ensure reliability.
DevOps practices play a crucial role in maintaining a smooth development and deployment process. Docker containerization is used so that all components run in consistent environments, reducing the risk of environment-specific bugs. Automated CI/CD pipelines handle testing and deployment, while environment parity ensures that development, staging, and production environments are identical. Infrastructure as code, such as Docker Compose, makes local development setup straightforward. Continuous monitoring through health checks and performance metrics helps quickly identify and resolve issues.
A collaborative ownership approach is encouraged within the team. Feature-based development assigns ownership of each feature to a specific team member, while cross-functional teams foster collaboration between frontend and backend developers. Regular knowledge sharing sessions, such as weekly tech talks and pair programming, help spread expertise and keep everyone aligned. Comprehensive documentation, including detailed READMEs and API docs, ensures that information is accessible. Code ownership is shared, allowing anyone to contribute to any part of the codebase.
Onboarding new team members is a structured process designed to help them become productive quickly. A starter kit with a ready-to-use Docker setup is provided, and the first week focuses on pair programming with experienced team members. Clear guides are available for common tasks and architectural decisions, and each new member is assigned a mentor for the first month. Responsibility is introduced gradually, starting with small features and building up to more complex
Resilience design involves taking proactive measures to ensure a platform remains robust and user-friendly, even under stress. Circuit breakers are implemented to prevent cascading failures if any services go down, helping to isolate issues and maintain overall system stability. When an API becomes slow or unresponsive, fallback mechanisms can return cached data, ensuring users still receive timely responses. For transient failures, retry logic with exponential backoff gives services a chance to recover without being overwhelmed. In situations where a complete response isn’t possible, graceful degradation is practiced by showing partial data instead of failing entirely. Continuous health checks monitor the status of services, enabling quick detection and resolution of issues.
Comprehensive observability is achieved by tracking performance metrics such as response times, throughput, and error rates to monitor system health. Business metrics like user engagement, badge unlocks, and level progressions provide insight into how users interact with the platform. Infrastructure metrics—including CPU usage, memory consumption, and database connections—are also closely monitored. Logging is structured in JSON format and includes correlation IDs, making it easy to trace requests across services. All collected data feeds into real-time dashboards powered by Grafana, offering instant visibility into both technical and business performance.
Security and data integrity are essential to any platform. JWT authentication secures user sessions with token-based access, and all API inputs are validated using Zod schemas to prevent invalid or malicious data from entering the system. Rate limiting is enforced to protect against abuse, and parameterized queries with Prisma ORM help guard against SQL injection attacks. Data integrity is maintained through strict database constraints and careful transaction management. Communications are encrypted via HTTPS to ensure privacy and security for all users. Regular security audits and automated vulnerability scans are conducted to proactively identify and address potential risks.
The backend is built with Node.js and Express, providing a robust foundation for the platform. REST APIs enable complete CRUD operations for all entities, making it easy to manage users, activities, badges, and more. A point system awards points for specific actions, while the level system ensures users progress automatically as they accumulate points. The badge system unlocks achievements based on defined criteria, and leaderboards offer rankings to encourage competition. API documentation is available through Swagger, making it simple to explore and test endpoints. Comprehensive error handling is implemented globally, with custom codes to help identify and resolve issues quickly.
The frontend is developed using React.js, delivering a modern and responsive user experience. An admin dashboard provides a complete management interface, allowing administrators to oversee users, badges, and activities. The leaderboard view displays real-time rankings, while user profiles showcase individual details and earned badges. Badge management features make it easy to add or edit badges with built-in validations. Zustand is used for efficient global state management, and the interface is designed to be mobile-friendly, ensuring accessibility across devices.
The database design is optimized for gamification features, with an efficient schema that supports all core entities such as users, activities, badges, levels, and achievements. Performance is enhanced through the use of indexes for faster queries, and cascade deletes are configured to maintain proper data integrity when records are removed.
Docker and DevOps practices streamline development and deployment. Separate Dockerfiles are provided for both backend and frontend containers, and Docker Compose orchestrates the entire stack for easy setup. Environment configurations are managed through .env files, and multi-stage builds are used to produce optimized production images, ensuring efficient resource usage and faster deployments.
A scalable SaaS platform often relies on a strong multi-tenancy structure. Tenant isolation can be achieved by using separate databases or schema-based isolation, ensuring that each client’s data remains private and secure. Custom configurations allow each tenant to have their own point values, badge criteria, and gamification rules, so the platform can adapt to a wide range of use cases. Automated provisioning makes onboarding new tenants fast and efficient, with API-driven processes that handle everything from account creation to initial setup. Health monitoring is also important, with tenant-specific metrics and alerts providing visibility into the status and performance of
- Clone the repository
- Choose your setup method:
- Docker (Recommended): Use
docker-run.bat start - Manual: Follow the manual setup instructions
- Docker (Recommended): Use
- Access the application:
- Frontend: http://localhost:3000
- Backend API: http://localhost:8000
- API Docs: http://localhost:8000/api-docs
This project is licensed under the MIT License.