This project is a full-stack feature for an e-commerce loyalty program where customers unlock achievements and earn badges based on their purchase history. It was built as part of a Mid-Level Full-Stack Engineer assessment.
The loyalty program tracks user purchases and automatically unlocks relevant achievements and badges. When a user reaches specific milestones, events are fired to trigger rewards, such as cashback payments.
- Achievement tracking based on total number of sales.
- Achievement tracking based on total revenue generated.
- Badge progression system tied to the number of unlocked achievements.
- Automated event-driven rewards (Cashback system).
- RESTful API for fetching user loyalty progress and history.
- Core: PHP 8.3 / Laravel 13
- Database: SQLite
- Authentication: Laravel Sanctum
- Testing: Pest PHP
- Architecture: Action-DTO Pattern, Event-Driven Design
To maintain thin controllers and reusable logic, the project utilizes the Action pattern. Business logic is encapsulated within dedicated Action classes (e.g., UnlockAchievements, UnlockBadges), while Data Transfer Objects (DTOs) ensure a consistent and type-safe API response structure.
The system is decoupled using Laravel's event system:
- ItemPurchased: Fired when a purchase is recorded.
- AchievementUnlocked: Fired when a user meets an achievement threshold.
- BadgeUnlocked: Fired when a user earns a new badge, triggering the cashback listener.
Listeners responsible for achievement and badge checks implement ShouldQueue, ensuring that the purchase flow remains fast and responsive while heavy calculations happen in the background.
This project is fully dockerized for easy setup and development.
- Docker
- Docker Compose
-
Clone the repository:
git clone https://github.com/horlerdipo/loyalty-reward cd loyalty-program -
Environment configuration:
cp .env.example .env # Open .env and set your preferred APP_PORT (default is 8000) -
Build and start the containers:
docker-compose up -d --build
-
The application handles migrations and seeding automatically upon startup. You can access the API at
http://localhost:8000(or your configuredAPP_PORT).
docker exec -it loyalty_backend php artisan test- PHP 8.2 or higher
- Composer
- SQLite
-
Clone and install dependencies:
git clone https://github.com/horlerdipo/loyalty-reward cd loyalty-program composer install -
Environment configuration:
cp .env.example .env php artisan key:generate
-
Database Setup:
touch database/database.sqlite php artisan migrate php artisan db:seed --class=AchievementSeeder php artisan db:seed --class=BadgeSeeder
-
Start the application:
php artisan serve
The project includes a Postman collection (Loyalty Program.postman_collection.json) for detailed endpoint testing.
Most endpoints require a Bearer Token obtained via the login or register endpoints.
- POST /api/auth/register: Create a new user account.
- POST /api/auth/login: Authenticate and receive an API token.
- GET /api/users/{user}/achievements: Returns the user's unlocked achievements, next available milestones, current badge, and progress toward the next badge.
- POST /api/purchase: Simulate a purchase to trigger the loyalty logic.
Achievements are split into two tracks:
- Sales Track: Unlocked based on the total count of items purchased.
- Revenue Track: Unlocked based on the total amount spent (thresholds: 1k, 5k, 10k, etc.).
Badges are awarded based on the total number of achievements unlocked:
- Starter: 1 Achievement
- Bronze: 3 Achievements
- Silver: 6 Achievements
- Gold: 9 Achievements
- Platinum: 12 Achievements
- Sapphire: 15 Achievements
- Ruby: 18 Achievements
- Emerald: 21 Achievements
- Diamond: 24 Achievements
- Legend: 27 Achievements
Every time a BadgeUnlocked event is fired, a cashback of 300 Naira is automatically logged for the user and marked as paid in the database.
The project uses Pest for feature and unit testing.
To run the test suite:
php artisan testKey test areas include:
- Achievement unlocking logic.
- Badge progression accuracy.
- API response structure and authentication.
- Event dispatching verification.
This project is open-sourced software licensed under the MIT license.