Building a Real-Time Matchmaking System with NestJS and MongoDB 🎮

[MyrinNew]

How I Built a Competitive Gaming Matchmaking API Like Valorant and CS:GO

Have you ever wondered how games like Valorant, CS:GO, or League of Legends instantly find you opponents at your skill level? In this article, I'll walk you through building a production-ready matchmaking system from scratch using NestJS, MongoDB, and intelligent algorithms.





🎯 What We're Building

A backend matchmaking system that:

• ✅ Automatically pairs players based on skill level (ELO rating)
• ✅ Groups players by geographic region to minimize lag
• ✅ Implements a fair queueing system (FIFO - First In, First Out)
• ✅ Uses smart algorithms to balance wait times vs match quality
• ✅ Updates player ratings after matches using the ELO system
• ✅ Handles edge cases like odd numbers of players and long wait times

This isn't just CRUD - it's a real-world system design challenge that requires algorithm thinking, database optimization, and state management.





🏗️ System Architecture

Core Components





┌─────────────┐ ┌──────────────┐ ┌─────────────┐
│ Players │ ───▶ │ Queue API │ ───▶ │ Queue DB │
└─────────────┘ └──────────────┘ └─────────────┘
│
▼
┌─────────────────┐
│ Matchmaking │ ◀──── Runs every 10s
│ Service │
└─────────────────┘
│
▼
┌─────────────────┐
│ Match API │
└─────────────────┘
│
▼
┌─────────────────┐
│ Match DB │
└─────────────────┘










📊 Database Schema Design

User Schema

Stores player profiles and their current state:






{
_id: ObjectId,
username: string,
rating: number, // ELO rating (starts at 1200)
region: string, // Encrypted: "NA", "EU", "ASIA"
status: string, // Encrypted: "idle", "searching", "in_match"
matchHistory: ObjectId[],
createdAt: Date
}







Why encrypt region and status? Security best practice for sensitive player data.


Queue Schema

The "waiting room" for players looking for matches:






{
_id: ObjectId,
userId: ObjectId, // Reference to User
username: string, // Denormalized for faster queries
rating: number, // Denormalized to avoid joins
region: string,
mode: string, // "1v1", "2v2", "5v5"
status: "searching",
joinedAt: Date
}







Denormalization Trade-off: We duplicate username and rating here for query performance. In matchmaking, speed matters more than storage.


Match Schema

Records of created matches:






{
_id: ObjectId,
status: string, // "pending", "active", "finished"
mode: string,
players: [{
userId: ObjectId,
username: string,
rating: number,
team?: string // For team-based modes
}],
winner: ObjectId,
result: {
winnerRating: number,
loserRating: number,
ratingChange: number
},
createdAt: Date
}










🧠 The Matchmaking Algorithm

This is the heart of the system. Here's how it works:


Step 1: Automatic Scheduling





@Cron(CronExpression.EVERY_10_SECONDS)
async runMatchmaking() {
this.logger.log('🔍 Starting matchmaking scan...');
await this.find1v1Matches();
}







Using NestJS's @Cron decorator, the matchmaking service runs automatically every 10 seconds in the background.


Step 2: Fetch and Group Players





const queuedPlayers = await this.queueModel.aggregate([
{ $match: { mode: '1v1' } },
{ $sort: { joinedAt: 1 } }, // FIFO ordering
{
$group: {
_id: '$region', // Group by region
players: { $push: '$$ROOT' }
}
}
]);







Why MongoDB Aggregation? It's incredibly efficient for complex queries. We get region-grouped, time-sorted data in a single database call.


Step 3: Compatibility Check





arePlayersCompatible(player1: any, player2: any): boolean {
// Rule 1: Same region
if (player1.region !== player2.region) return false;

// Rule 2: Rating tolerance
const ratingDiff = Math.abs(player1.rating - player2.rating);
const RATING_TOLERANCE = 100;

if (ratingDiff > RATING_TOLERANCE) return false;

// Rule 3: Wait time flexibility
const avgWaitTime = (player1WaitTime + player2WaitTime) / 2;
if (avgWaitTime > 30000) {
// After 30s, allow ±200 rating difference
return ratingDiff 200;
}

return true;
}







Smart Trade-offs:

• First 30 seconds: Strict ±100 rating for fair matches
• After 30 seconds: Lenient ±200 rating to prevent long waits

Step 4: Match Creation with Transactions





async createMatch(players: any[], mode: string) {
const session = await this.queueModel.db.startSession();
session.startTransaction();

try {
// 1. Create match document
const match = new this.matchModel({ /* ... */ });
await match.save({ session });

// 2. Remove players from queue
await this.queueModel.deleteMany({
userId: { $in: userIds }
}, { session });

// 3. Update user statuses to "in_match"
await this.userModel.updateMany({
_id: { $in: userIds }
}, {
status: encrypt('in_match')
}, { session });

// 4. Add to match history
await this.userModel.updateMany({
_id: { $in: userIds }
}, {
$push: { matchHistory: match._id }
}, { session });

await session.commitTransaction();
return match;
} catch (error) {
await session.abortTransaction();
throw error;
} finally {
session.endSession();
}
}







Why Transactions? Ensures atomicity. Either all operations succeed, or none do. This prevents bugs like:

• Player in two matches simultaneously
• Match created but players still in queue
• Inconsistent state between collections

🎲 ELO Rating System

After a match finishes, we update ratings using the classic ELO algorithm:






calculateELO(winnerRating: number, loserRating: number) {
const K = 32; // K-factor (rating change magnitude)

// Expected win probability
const expectedWinner = 1 / (1 + Math.pow(10, (loserRating - winnerRating) / 400));
const expectedLoser = 1 / (1 + Math.pow(10, (winnerRating - loserRating) / 400));

// Calculate changes
const winnerChange = Math.round(K * (1 - expectedWinner));
const loserChange = Math.round(K * (0 - expectedLoser));

return {
newWinnerRating: winnerRating + winnerChange,
newLoserRating: loserRating + loserChange,
ratingChange: winnerChange,
};
}







Example:

• Player A (1200) beats Player B (1250)
• Player A: 1200 → 1225 (+25 points)
• Player B: 1250 → 1235 (-15 points)

The upset victory gives A more points since B was favored.





🔐 Security & Performance Features

1. Data Encryption

Sensitive fields like region and status are encrypted at rest:






import { encrypt, decrypt } from 'src/middlewares/encryption/encrypt';

// When saving
const encryptedRegion = encrypt(region);
const encryptedStatus = encrypt(status);

// When reading
const decryptedRegion = decrypt(user.region);







2. Region Validation

We validate region codes to prevent bad data:






if (!isValidCountryCode(region)) {
throw new BadRequestException('Invalid region code');
}







3. Caching Layer

Frequently accessed user data is cached to reduce database load:






await this.cacheManager.set(
`user:${username}`,
{ id, username, region },
3600 // 1 hour TTL
);







4. Input Validation

Every API endpoint validates inputs:






// Can't join queue if already in a match
if (decryptedStatus === "in_match") {
throw new BadRequestException("User is currently in a match");
}

// Can't join queue twice
const alreadyInQueue = await this.queueModel.findOne({ userId });
if (alreadyInQueue) {
throw new BadRequestException("User already in queue");
}










🛣️ API Endpoints

User Management





POST /users/register # Create new player
GET /users/:id # Get player profile







Queue Management





POST /queue/join # Join matchmaking queue
POST /queue/leave # Leave queue
GET /queue/status/:userId # Check queue position







Matchmaking





POST /matchmaking/trigger # Manual trigger (testing)
GET /matchmaking/queue-stats # Queue statistics







Match Management





GET /matches # List all matches (paginated)
GET /matches/:id # Get match details
GET /matches/active/all # Get active matches
GET /matches/history/:userId # User's match history
POST /matches/:id/start # Start a match
POST /matches/:id/finish # Finish match & update ratings
POST /matches/:id/cancel # Cancel match (admin)










🧪 Testing the System

Test Scenario: Create a Match





# 1. Create two players
curl -X POST http://localhost:3000/users/register \
-H "Content-Type: application/json" \
-d '{"username":"Alice","region":"NA","status":"idle" }'

curl -X POST http://localhost:3000/users/register \
-H "Content-Type: application/json" \
-d '{"username":"Bob","region":"NA","status":"idle" }'

# 2. Both join queue
curl -X POST http://localhost:3000/queue/join \
-H "Content-Type: application/json" \
-d '{"userId":"ALICE_ID","mode":"1v1"}'

curl -X POST http://localhost:3000/queue/join \
-H "Content-Type: application/json" \
-d '{"userId":"BOB_ID","mode":"1v1"}'

# 3. Wait 10 seconds (automatic matching)
# Check server logs:
# 🔍 Starting matchmaking scan...
# ✅ MATCH FOUND: Alice (1200) vs Bob (1200)
# 🎮 Match created: 65a1b2c3d4e5f6789

# 4. Verify match was created
curl http://localhost:3000/matches

# 5. Start the match
curl -X POST http://localhost:3000/matches/MATCH_ID/start

# 6. Finish match (Alice wins)
curl -X POST http://localhost:3000/matches/MATCH_ID/finish \
-H "Content-Type: application/json" \
-d '{"winnerId":"ALICE_ID","loserId":"BOB_ID"}'

# 7. Check updated ratings
curl http://localhost:3000/users/ALICE_ID # Rating: 1225
curl http://localhost:3000/users/BOB_ID # Rating: 1185










🚀 Key Technical Decisions

Why MongoDB over PostgreSQL?

1. Flexible Schema: Match results can vary by game mode
2. Aggregation Pipeline: Perfect for complex matchmaking queries
3. Denormalization: Trade storage for query speed
4. Horizontal Scaling: Better for high-concurrency gaming systems

Why NestJS?

1. Built-in Scheduling: @Cron decorator for background jobs
2. Dependency Injection: Clean, testable architecture
3. TypeScript: Type safety for complex algorithms
4. Mongoose Integration: Seamless MongoDB ODM

Why Transactions?

Gaming systems require strong consistency. A player can't be in two states simultaneously. Transactions ensure atomic operations across multiple collections.





📈 Performance Optimizations

1. Denormalization





// Queue stores username and rating directly
// Avoids JOIN operations during matchmaking
{
userId: ObjectId,
username: "Player1", // ← Denormalized
rating: 1200 // ← Denormalized
}







2. Indexing Strategy





// Queue collection indexes
queueSchema.index({ region: 1, mode: 1, joinedAt: 1 });
queueSchema.index({ userId: 1 });

// User collection indexes
userSchema.index({ username: 1 }, { unique: true });
userSchema.index({ region: 1, rating: 1 });







3. Aggregation Pipeline

Single query to get grouped, sorted players:






// Instead of:
// 1. Fetch all players
// 2. Group by region in code
// 3. Sort by join time in code

// We do:
$match → $sort → $group // All in database!










🎓 What I Learned

Algorithm Design

• Balancing fairness (skill matching) vs speed (wait times)
• Implementing gradual tolerance increases
• FIFO queue management

System Design

• State machines (idle → searching → in_match → idle)
• Background job scheduling
• Atomic operations with transactions

Database Optimization

• When to denormalize for performance
• Effective use of aggregation pipelines
• Strategic indexing for query patterns

Real-World Trade-offs

• Perfect matches vs reasonable wait times
• Data consistency vs system complexity
• Storage cost vs query performance

🔮 Future Enhancements

1. WebSocket Integration

Real-time notifications when matches are found:






@WebSocketGateway()
export class MatchmakingGateway {
@WebSocketServer()
server: Server;

notifyMatchFound(match: Match) {
match.players.forEach(player => {
this.server.to(player.userId).emit('match-found', match);
});
}
}







2. Team-Based Matchmaking

Support for 2v2 and 5v5 modes with team balancing:






async find5v5Matches() {
// Find 10 players
// Balance teams so sum(team1.ratings) ≈ sum(team2.ratings)
}







3. Regional Fallback

If no match in primary region after 60s, try nearby regions:






const REGION_FALLBACKS = {
'NA': ['SA'],
'EU': ['ME'],
'ASIA': ['OCE']
};







4. Priority Queue

VIP players or those who've waited longest get priority matching.


5. Anti-Cheat Integration

Track suspicious rating changes, match dodging, etc.





💡 Key Takeaways

1. Matchmaking is NOT CRUD - It's algorithm design, state management, and real-time decision making
2. Transactions are critical in systems where consistency matters
3. Denormalization has a place when query performance is paramount
4. Background jobs enable autonomous system behavior
5. Trade-offs are everywhere - perfect vs fast, consistency vs availability

🛠️ Tech Stack

• Framework: NestJS (Node.js)
• Database: MongoDB with Mongoose ODM
• Scheduling: @nestjs/schedule
• Caching: @nestjs/cache-manager
• Encryption: Custom AES encryption middleware
• Validation: class-validator, class-transformer

📦 Repository & Installation





# Clone repository
git clone https://github.com/Jerry-Khobby/matchmaking-system

# Install dependencies
npm install

# Set up MongoDB
# Update connection string in app.module.ts

# Run in development
npm run start:dev










🎯 Conclusion

Building a matchmaking system taught me that backend development goes far beyond CRUD operations. It requires:

• Algorithmic thinking for pairing logic
• System design for state management
• Database optimization for performance
• Error handling for edge cases

This project demonstrates production-ready backend skills: handling concurrent users, making intelligent automated decisions, and maintaining data consistency in complex scenarios.


If you're looking to level up from tutorial projects to real system design challenges, building a matchmaking system is an excellent way to do it.





📚 Resources

• NestJS Documentation
• MongoDB Aggregation Pipeline
• ELO Rating System Explained
• Transaction Best Practices

Questions or suggestions? Drop a comment below! I'd love to discuss system design trade-offs and algorithm optimizations.


Found this helpful? Share it with other developers building real-world backend systems! 🚀





Tags: #NestJS #MongoDB #SystemDesign #Backend #Gaming #Algorithms #NodeJS #TypeScript




More...