🎯 LoyaltySphere (Inspired by Loynova)

Enterprise Multi-Tenant Loyalty & Rewards Platform

A production-ready, microservices-based loyalty management system built with Clean Architecture, Domain-Driven Design (DDD), and SOLID principles.

This project perfectly maps real-world financial enterprise needs (similar to Loynova), specifically:

National Bank of Egypt: Instant POS discounts and dynamic Points calculations per rule.
Suez Canal Bank: Instant real-time cashback upon transactional Webhooks.
Shell Egypt & Kellogg's: Time-bound Campaigns, Multipliers, and seamless multi-tenant isolation.

🎭 The Cinematic Red Dashboard

The Angular 18 frontend is engineered using a Cinematic Red Engine (powered by Tailwind v4).

Aesthetic: Deep Crimson (#9f1239) combined with Obsidian Black backgrounds, offset by Loyalty Gold accents.
Interactions: Glassmorphism cards, seamless scaleIn and fade-in micro-transitions, cinematic glow boxShadow effects.
Real-Time magic: A central dashboard that explodes with a gold rewardPop animation emitting sparkly keyframes the instant RabbitMQ/SignalR broadcasts a POS transaction approval. It feels less like standard B2B software and more like a high-end fintech experience.

🎙️ Interview Talking Points (Why hire me?)

Multi-Tenancy at the DB Layer (PostgreSQL RLS): Explain how you bypassed standard EF Core Global Filters by using Postgres Row-Level Security. "Even if a junior dev writes a rogue raw query, the DB rejects cross-tenant data leaks."
SOLID & Clean Architecture: Talk about separating EF Core configurations via IEntityTypeConfiguration and orchestrating robust Domain Services (e.g., RewardRuleSelector) that strictly uphold the Single Responsibility and Open/Closed Principles.
Resilience & Outbox: Mention how direct API calls fail. "I implemented the Outbox Pattern via DbContext interceptors paired with MassTransit RabbitMQ to guarantee at-least-once delivery for reward disbursements."
Cinematic UI Engineering: Emphasize how you built a custom Tailwind design system centralized in CSS (no inline bloat) mapped to Angular 18 signals and @if control flow for maximum rendering speeds and luxury UX.
Observability: Discuss logging via Serilog and OpenTelemetry to trace a transaction from the initial POST to the SignalR websocket broadcast.

🚀 Quick Start

One-Command Setup (Local)

# Clone repository
git clone https://github.com/msaid356/loyalty-sphere.git
cd loyalty-sphere

# Start all services
docker compose up -d

# Access application
# Frontend: http://localhost:4200
# API: http://localhost:5001

Deploy to Netlify (Frontend)

Connect GitHub repository.
Base Directory: src/Web/loyalty-sphere-ui
Build Command: npm run build
Publish Directory: dist/loyalty-sphere-ui/browser
Environment Variables: Ensure NODE_VERSION is set to 18 or higher.

Live Demo (Frontend): https://loyaltysphere.netlify.app
Live API (Backend): http://loyaltysphere.runasp.net/swagger

Deploy to Render.com (Production)

# One-command deployment
./deploy-to-render.sh

# Or via Render Dashboard
# 1. Connect GitHub repository
# 2. Create Blueprint from render.yaml
# 3. Deploy automatically

Using Pre-built Images (Docker Hub)

# Pull and start from Docker Hub
docker compose -f docker-compose.prod.yml up -d

📦 Docker Hub Images

Repository: msaid356/loyalty-sphere

# Pull images
docker pull msaid356/loyalty-sphere:reward-service-latest
docker pull msaid356/loyalty-sphere:frontend-latest

# Or use docker-compose
docker compose -f docker-compose.prod.yml pull

Build & Push Your Own Images

# Method 1: Shell Script
./build-and-push.sh v1.0.0

# Method 2: Makefile
make push VERSION=v1.0.0

# Method 3: Manual
docker build -t msaid356/loyalty-sphere:reward-service-v1.0.0 \
  -f src/Services/RewardService/Dockerfile .
docker push msaid356/loyalty-sphere:reward-service-v1.0.0

📖 Full Docker Guide: DOCKER_QUICK_START.md | docs/DOCKER_GUIDE.md

✨ Features

Core Capabilities

✅ Multi-Tenant Architecture - Shared database with Row-Level Security (RLS)
✅ Reward Calculation Engine - Points, cashback, multipliers, tiered rewards
✅ Campaign Management - Time-bound promotions with eligibility rules
✅ Customer Tiers - Bronze, Silver, Gold, Platinum with automatic upgrades
✅ Points Redemption - Flexible redemption with transaction history
✅ Real-time Analytics - Dashboard with KPIs and insights
✅ Admin Portal - Complete management interface

Technical Highlights

🏗️ Clean Architecture - Domain, Application, Infrastructure, API layers
🎯 Domain-Driven Design - Rich domain models, value objects, aggregates
📐 SOLID Principles - 86% reduction in violations (37 → 5)
🔄 CQRS Pattern - Command/Query separation with MediatR
🗄️ Repository Pattern - Abstracted data access with Unit of Work
🎨 Strategy Pattern - Extensible campaign types
🔒 Multi-Tenancy - Tenant isolation at database level
📊 Observability - OpenTelemetry, Jaeger, Prometheus, Grafana
🐳 Containerized - Docker Compose for one-command deployment
☸️ Kubernetes Ready - Production-ready K8s manifests

🏗️ Architecture

System Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Angular Frontend                        │
│                    (Port 4200 / Nginx)                       │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                    API Gateway (Ocelot)                      │
│                        (Port 5000)                           │
└────────────┬────────────────────────────┬────────────────────┘
             │                            │
             ▼                            ▼
┌────────────────────────┐   ┌────────────────────────┐
│   Reward Service       │   │ Transaction Service    │
│   (Port 5001)          │   │   (Port 5002)          │
│   - Customers          │   │   - Transactions       │
│   - Campaigns          │   │   - Audit Logs         │
│   - Reward Rules       │   │   - Event Sourcing     │
│   - Points Calculation │   │                        │
└────────────┬───────────┘   └────────────┬───────────┘
             │                            │
             └────────────┬───────────────┘
                          │
        ┌─────────────────┼─────────────────┐
        │                 │                 │
        ▼                 ▼                 ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│  PostgreSQL  │  │   RabbitMQ   │  │    Redis     │
│  (Port 5432) │  │  (Port 5672) │  │  (Port 6379) │
│  + RLS       │  │  + Mgmt UI   │  │  + Cache     │
└──────────────┘  └──────────────┘  └──────────────┘

Clean Architecture Layers

┌─────────────────────────────────────────────────────────────┐
│                         API Layer                            │
│  Controllers, Middleware, Request/Response Contracts         │
└────────────────────────┬────────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────────┐
│                    Application Layer                         │
│  Commands, Queries, Handlers, DTOs, Mappers, Services       │
└────────────────────────┬────────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────────┐
│                      Domain Layer                            │
│  Entities, Value Objects, Enums, Domain Services,           │
│  Repository Interfaces, Business Rules                       │
└────────────────────────┬────────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────────┐
│                  Infrastructure Layer                        │
│  Repository Implementations, DbContext, Migrations,          │
│  External Services, Message Brokers                          │
└─────────────────────────────────────────────────────────────┘

🛠️ Technology Stack

Backend

.NET 8 - Latest LTS version
ASP.NET Core - Web API framework
Entity Framework Core - ORM with migrations
MediatR - CQRS implementation
FluentValidation - Request validation
Serilog - Structured logging
OpenTelemetry - Distributed tracing

Frontend

Angular 18 - Latest version with signals
TypeScript - Type-safe development
RxJS - Reactive programming
Angular Material - UI components
Chart.js - Data visualization
Nginx - Production web server

Infrastructure

PostgreSQL 16 - Primary database with RLS
RabbitMQ 3.13 - Message broker
Redis 7 - Caching layer
Docker - Containerization
Kubernetes - Orchestration (optional)
Jaeger - Distributed tracing
Prometheus - Metrics collection
Grafana - Monitoring dashboards

📁 Project Structure

LoyaltySphere/
├── src/
│   ├── BuildingBlocks/           # Shared libraries
│   │   ├── MultiTenancy/         # Tenant context & middleware
│   │   ├── EventBus/             # RabbitMQ integration
│   │   └── Observability/        # OpenTelemetry setup
│   │
│   ├── Services/
│   │   └── RewardService/        # Main microservice
│   │       ├── Domain/           # Business logic
│   │       │   ├── Entities/     # Domain entities
│   │       │   ├── ValueObjects/ # Value objects
│   │       │   ├── Enums/        # Domain enums
│   │       │   ├── Services/     # Domain services
│   │       │   ├── Strategies/   # Campaign strategies
│   │       │   └── Repositories/ # Repository interfaces
│   │       │
│   │       ├── Application/      # Use cases
│   │       │   ├── Commands/     # Write operations
│   │       │   ├── Queries/      # Read operations
│   │       │   ├── DTOs/         # Data transfer objects
│   │       │   ├── Mappers/      # Entity-DTO mapping
│   │       │   └── Services/     # Application services
│   │       │
│   │       ├── Infrastructure/   # External concerns
│   │       │   ├── Data/         # DbContext & migrations
│   │       │   ├── Repositories/ # Repository implementations
│   │       │   └── Extensions/   # DI configuration
│   │       │
│   │       └── Api/              # HTTP API
│   │           ├── Controllers/  # API endpoints
│   │           ├── Contracts/    # Request/Response models
│   │           └── Middleware/   # HTTP middleware
│   │
│   └── Web/
│       └── loyalty-sphere-ui/    # Angular frontend
│           ├── src/app/
│           │   ├── core/         # Singletons (auth, http)
│           │   ├── shared/       # Reusable components
│           │   └── features/     # Feature modules
│           └── nginx.conf        # Production config
│
├── deployment/
│   ├── k8s/                      # Kubernetes manifests
│   ├── scripts/                  # Database scripts
│   └── prometheus/               # Monitoring config
│
├── docs/                         # Documentation
│   ├── DOCKER_GUIDE.md          # Docker reference
│   ├── DEPLOYMENT_GUIDE.md      # Deployment instructions
│   ├── QUICK_START.md           # Getting started
│   └── SOLID_REFACTORING_COMPLETE.md
│
├── docker-compose.yml            # Development setup
├── docker-compose.prod.yml       # Production setup
├── build-and-push.sh            # Docker build script
├── Makefile                      # Convenience commands
└── README.md                     # This file

🎯 Use Cases

Customer Management

// Enroll new customer
POST /api/customers/enroll
{
  "tenantId": "tenant-123",
  "email": "customer@example.com",
  "name": "John Doe",
  "tier": "Bronze"
}

// Get customer balance
GET /api/customers/{customerId}/balance

Reward Calculation

// Calculate reward points
POST /api/rewards/calculate
{
  "customerId": "cust-123",
  "transactionAmount": 100.00,
  "transactionType": "Purchase"
}

// Redeem points
POST /api/rewards/redeem
{
  "customerId": "cust-123",
  "pointsToRedeem": 500
}

Campaign Management

// Create campaign
POST /api/campaigns
{
  "name": "Summer Sale 2x Points",
  "type": "Multiplier",
  "multiplier": 2.0,
  "startDate": "2026-06-01",
  "endDate": "2026-08-31"
}

// Get active campaigns
GET /api/campaigns/active

Analytics

// Get dashboard analytics
GET /api/analytics/dashboard

// Response:
{
  "totalCustomers": 1250,
  "activeCustomers": 890,
  "totalPointsIssued": 125000,
  "totalPointsRedeemed": 45000,
  "averageTransactionValue": 75.50,
  "topCampaigns": [...]
}

🚀 Development

Prerequisites

.NET 8 SDK - https://dotnet.microsoft.com/download
Node.js 20+ - https://nodejs.org/
Docker Desktop - https://www.docker.com/products/docker-desktop
Git - https://git-scm.com/

Local Development Setup

# 1. Clone repository
git clone https://github.com/msaid356/loyalty-sphere.git
cd loyalty-sphere

# 2. Start infrastructure (PostgreSQL, RabbitMQ, Redis)
docker compose up -d postgres rabbitmq redis

# 3. Run backend
cd src/Services/RewardService
dotnet run

# 4. Run frontend (in new terminal)
cd src/Web/loyalty-sphere-ui
npm install
npm start

# Access:
# - Frontend: http://localhost:4200
# - Backend: http://localhost:5001
# - Swagger: http://localhost:5001/swagger

Running Tests

# Run all tests
dotnet test

# Run with coverage
dotnet test /p:CollectCoverage=true

# Run specific test project
dotnet test src/Services/RewardService/Tests/

Database Migrations

# Add migration
dotnet ef migrations add MigrationName

# Update database
dotnet ef database update

# Rollback migration
dotnet ef database update PreviousMigrationName

📊 Monitoring & Observability

Access Monitoring Tools

Tool	URL	Purpose
Jaeger	http://localhost:16686	Distributed tracing
Prometheus	http://localhost:9090	Metrics collection
Grafana	http://localhost:3000	Dashboards (admin/admin)
RabbitMQ	http://localhost:15672	Message broker (guest/guest)

Key Metrics

Request latency (P50, P95, P99)
Error rates by endpoint
Database query performance
Cache hit/miss ratio
Message queue depth
Active tenant count

🔒 Security

Multi-Tenancy

Row-Level Security (RLS) - PostgreSQL policies enforce tenant isolation
Tenant Context - Middleware extracts tenant from JWT/header
Data Isolation - All queries automatically filtered by tenant_id

Authentication & Authorization

JWT Tokens - Stateless authentication
Role-Based Access - Admin, Manager, Customer roles
API Key Support - For service-to-service communication

Best Practices

✅ Non-root Docker containers
✅ Secrets management via environment variables
✅ HTTPS/TLS in production
✅ Input validation with FluentValidation
✅ SQL injection prevention (parameterized queries)
✅ CORS configuration
✅ Rate limiting
✅ Health checks

📈 Performance

Optimizations

Caching - Redis for frequently accessed data
Database Indexing - Optimized queries with proper indexes
Connection Pooling - Efficient database connections
Async/Await - Non-blocking I/O operations
Pagination - Large result sets handled efficiently
Lazy Loading - Load data only when needed

Benchmarks

Operation	Response Time	Throughput
Calculate Reward	< 50ms	2000 req/s
Get Customer Balance	< 20ms	5000 req/s
Create Campaign	< 100ms	1000 req/s
Dashboard Analytics	< 200ms	500 req/s

🚢 Deployment

Render.com (Recommended for Production)

# One-command deployment
./deploy-to-render.sh

# Or manually via Dashboard
# 1. Connect GitHub: https://dashboard.render.com
# 2. New → Blueprint
# 3. Select render.yaml
# 4. Deploy

Instance: loyalty-sphere (capybara)
Region: AWS AP-NorthEast-1 (Tokyo)
Live URL: https://loyalty-sphere-ui.onrender.com

📖 Render Guide: docs/RENDER_DEPLOYMENT.md

Docker Compose (Development)

# Start all services
docker compose up -d

# View logs
docker compose logs -f

# Stop services
docker compose down

Kubernetes (Enterprise)

# Apply manifests
kubectl apply -f deployment/k8s/namespace.yaml
kubectl apply -f deployment/k8s/

# Check status
kubectl get pods -n loyalty-sphere

# View logs
kubectl logs -f deployment/reward-service -n loyalty-sphere

Cloud Platforms

Render.com ✅ - One-click deployment (Recommended)
AWS - ECS/EKS with RDS PostgreSQL
Azure - AKS with Azure Database for PostgreSQL
GCP - GKE with Cloud SQL
Heroku - Container deployment
Railway - Git-based deployment

📖 Full Deployment Guide: docs/DEPLOYMENT_GUIDE.md

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Code Standards

Follow Clean Architecture principles
Write unit tests for new features
Update documentation
Follow C# and TypeScript style guides
Ensure all tests pass before submitting PR

📝 Documentation

Quick Start Guide - Get started in 5 minutes
Docker Guide - Complete Docker reference
Deployment Guide - Production deployment
SOLID Refactoring - Architecture decisions
API Documentation - Interactive API docs

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

👨‍💻 Author

msaid356

Docker Hub: @msaid356
GitHub: @msaid356

🙏 Acknowledgments

Clean Architecture by Robert C. Martin
Domain-Driven Design by Eric Evans
SOLID Principles
.NET Community
Angular Community

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: docs/

🗺️ Roadmap

Version 1.1 (Q2 2026)

GraphQL API
Real-time notifications (SignalR)
Mobile app (React Native)
Advanced analytics dashboard

Version 1.2 (Q3 2026)

Machine learning recommendations
A/B testing framework
Multi-currency support
Blockchain integration

Version 2.0 (Q4 2026)

Microservices expansion
Event sourcing
CQRS with separate read/write databases
Advanced multi-tenancy features

⭐ Star this repository if you find it helpful!

🐳 Pull from Docker Hub: docker pull msaid356/loyalty-sphere:latest

Last Updated: April 16, 2026

Name		Name	Last commit message	Last commit date
Latest commit History 31 Commits
.github		.github
deployment		deployment
docs		docs
src		src
tests/LoyaltySphere.RewardService.Tests		tests/LoyaltySphere.RewardService.Tests
.env.example		.env.example
.gitignore		.gitignore
LoyaltySphere.sln		LoyaltySphere.sln
Makefile		Makefile
README.md		README.md
docker-compose.prod.yml		docker-compose.prod.yml
docker-compose.yml		docker-compose.yml
render.yaml		render.yaml

Folders and files

Latest commit

History

Repository files navigation