The Challenge

Build a matchmaking platform where users can discover and connect with others based on:

• Mutual friends and connections
• Shared interests and activities
• Geographic proximity
• Interaction history and preferences

MongoDB Schema Design

User Document

// models/User.ts
interface User {
  _id: ObjectId;
  username: string;
  email: string;
  profile: {
    name: string;
    bio: string;
    avatar: string;
    location: {
      type: 'Point';
      coordinates: [number, number]; // [longitude, latitude]
    };
  };
  interests: string[]; // ["music", "hiking", "tech"]
  demographics: {
    ageRange: string; // "25-30"
    gender: string;
    lookingFor: string[];
  };
  preferences: {
    distanceRange: number; // kilometers
    ageRange: [number, number];
    interests: string[];
  };
  stats: {
    totalMatches: number;
    activeMatches: number;
    lastActive: Date;
  };
  createdAt: Date;
  updatedAt: Date;
}

Connection Document

// models/Connection.ts
interface Connection {
  _id: ObjectId;
  fromUser: ObjectId;
  toUser: ObjectId;
  type: 'friend' | 'match' | 'block' | 'pending';
  strength: number; // 0-100 (based on interactions)
  metadata: {
    mutualFriends: number;
    sharedInterests: string[];
    interactions: number;
  };
  status: 'active' | 'inactive' | 'archived';
  createdAt: Date;
  updatedAt: Date;
}

Interaction Document

// models/Interaction.ts
interface Interaction {
  _id: ObjectId;
  userId: ObjectId;
  targetId: ObjectId;
  type: 'view' | 'like' | 'pass' | 'message' | 'unmatch';
  context: {
    source: 'discover' | 'search' | 'mutual' | 'notification';
    position: number; // Position in feed
  };
  timestamp: Date;
}

Indexes for Performance

// database/indexes.ts
import { User, Connection, Interaction } from './models';

// User indexes
await User.createIndex({ 'profile.location': '2dsphere' }); // Geospatial
await User.createIndex({ interests: 1 }); // Array index
await User.createIndex({ 'stats.lastActive': -1 }); // Sort by activity
await User.createIndex(
  { username: 'text', 'profile.name': 'text', 'profile.bio': 'text' },
  { weights: { username: 10, 'profile.name': 5, 'profile.bio': 1 } }
); // Text search

// Connection indexes
await Connection.createIndex({ fromUser: 1, toUser: 1 }, { unique: true });
await Connection.createIndex({ fromUser: 1, type: 1 });
await Connection.createIndex({ toUser: 1, type: 1 });
await Connection.createIndex({ type: 1, status: 1, strength: -1 });

// Interaction indexes
await Interaction.createIndex({ userId: 1, timestamp: -1 });
await Interaction.createIndex({ targetId: 1, type: 1 });
await Interaction.createIndex({ userId: 1, type: 1, timestamp: -1 });

Core Graph Queries

Find Mutual Friends

// services/socialGraph.ts
export async function getMutualFriends(
  userId: ObjectId,
  targetId: ObjectId
): Promise<User[]> {
  // Get user's friends
  const userFriends = await Connection.find({
    fromUser: userId,
    type: 'friend',
    status: 'active',
  }).distinct('toUser');

  // Get target's friends
  const targetFriends = await Connection.find({
    fromUser: targetId,
    type: 'friend',
    status: 'active',
  }).distinct('toUser');

  // Find intersection
  const mutualFriendIds = userFriends.filter((id) =>
    targetFriends.some((tid) => tid.equals(id))
  );

  // Return user details
  return User.find({ _id: { $in: mutualFriendIds } }).select(
    'username profile.name profile.avatar'
  );
}

Calculate Connection Strength

export async function calculateConnectionStrength(
  userId: ObjectId,
  targetId: ObjectId
): Promise<number> {
  const factors = {
    mutualFriends: 0,
    sharedInterests: 0,
    interactions: 0,
    proximity: 0,
  };

  // 1. Mutual friends (max 30 points)
  const mutualFriends = await getMutualFriends(userId, targetId);
  factors.mutualFriends = Math.min(mutualFriends.length * 5, 30);

  // 2. Shared interests (max 25 points)
  const [user, target] = await Promise.all([
    User.findById(userId).select('interests'),
    User.findById(targetId).select('interests'),
  ]);

  const sharedInterests = user!.interests.filter((interest) =>
    target!.interests.includes(interest)
  );
  factors.sharedInterests = Math.min(sharedInterests.length * 5, 25);

  // 3. Interaction history (max 25 points)
  const interactions = await Interaction.countDocuments({
    userId,
    targetId,
    type: { $in: ['view', 'like', 'message'] },
  });
  factors.interactions = Math.min(interactions * 2, 25);

  // 4. Geographic proximity (max 20 points)
  if (user!.profile.location && target!.profile.location) {
    const distance = calculateDistance(
      user!.profile.location.coordinates,
      target!.profile.location.coordinates
    );

    // Closer = higher score
    if (distance < 5) factors.proximity= 20;
    else if (distance < 10) factors.proximity= 15;
    else if (distance < 25) factors.proximity= 10;
    else if (distance < 50) factors.proximity= 5;
  }

  return Object.values(factors).reduce((sum, val)=> sum + val, 0);
}

Recommendation Algorithm

Discovery Feed Algorithm

export async function getDiscoveryFeed(
  userId: ObjectId,
  limit: number = 20
): Promise<ScoredUser[]> {
  const user = await User.findById(userId);
  if (!user) throw new Error('User not found');

  // Get users already seen/matched/blocked
  const excludedIds = await getExcludedUsers(userId);

  // Build match query
  const matchQuery: any = {
    _id: { $nin: [...excludedIds, userId] },
    'stats.lastActive': { $gte: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000) }, // Active in last 30 days
  };

  // Filter by preferences
  if (user.preferences.distanceRange && user.profile.location) {
    matchQuery['profile.location'] = {
      $near: {
        $geometry: user.profile.location,
        $maxDistance: user.preferences.distanceRange * 1000, // Convert km to meters
      },
    };
  }

  if (user.preferences.interests.length > 0) {
    matchQuery.interests = { $in: user.preferences.interests };
  }

  // Get candidate users
  const candidates = await User.find(matchQuery).limit(limit * 3); // Over-fetch for scoring

  // Score each candidate
  const scoredCandidates = await Promise.all(
    candidates.map(async (candidate) => {
      const score = await scoreCandidate(user, candidate);
      return { user: candidate, score };
    })
  );

  // Sort by score and return top results
  return scoredCandidates
    .sort((a, b) => b.score - a.score)
    .slice(0, limit)
    .map((item) => item.user);
}

async function scoreCandidate(user: User, candidate: User): Promise<number> {
  let score = 0;

  // 1. Shared interests (max 30 points)
  const sharedInterests = user.interests.filter((interest) =>
    candidate.interests.includes(interest)
  );
  score += Math.min(sharedInterests.length * 6, 30);

  // 2. Mutual friends (max 25 points)
  const mutualFriends = await getMutualFriends(user._id, candidate._id);
  score += Math.min(mutualFriends.length * 5, 25);

  // 3. Activity level (max 20 points)
  const daysSinceActive =
    (Date.now() - candidate.stats.lastActive.getTime()) / (1000 * 60 * 60 * 24);
  if (daysSinceActive < 1) score = 20;
  else if (daysSinceActive < 3) score = 15;
  else if (daysSinceActive < 7) score = 10;
  else if (daysSinceActive < 14) score = 5;

  // 4. Profile completeness (max 15 points)
  let completeness= 0;
  if (candidate.profile.bio) completeness = 5;
  if (candidate.profile.avatar) completeness = 5;
  if (candidate.interests.length >= 3) completeness += 5;
  score += completeness;

  // 5. Proximity (max 10 points)
  if (user.profile.location && candidate.profile.location) {
    const distance = calculateDistance(
      user.profile.location.coordinates,
      candidate.profile.location.coordinates
    );
    if (distance < 5) score = 10;
    else if (distance < 10) score = 7;
    else if (distance < 25) score = 4;
  }

  return score;
}

async function getExcludedUsers(userId: ObjectId): Promise<ObjectId[]> {
  const [matched, blocked, passed] = await Promise.all([
    // Already matched
    Connection.find({
      fromUser: userId,
      type: { $in: ['match', 'friend'] },
    }).distinct('toUser'),

    // Blocked
    Connection.find({
      fromUser: userId,
      type: 'block',
    }).distinct('toUser'),

    // Recently passed
    Interaction.find({
      userId,
      type: 'pass',
      timestamp: { $gte: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000) }, // Last 7 days
    }).distinct('targetId'),
  ]);

  return [...matched, ...blocked, ...passed];
}

Graph Traversal Queries

Friend-of-Friend Recommendations

export async function getFriendOfFriendRecommendations(
  userId: ObjectId,
  limit: number = 10
): Promise<User[]> {
  // Aggregation pipeline for friend-of-friend
  const recommendations = await Connection.aggregate([
    // Start with user's friends
    {
      $match: {
        fromUser: userId,
        type: 'friend',
        status: 'active',
      },
    },

    // Lookup their friends
    {
      $lookup: {
        from: 'connections',
        let: { friendId: '$toUser' },
        pipeline: [
          {
            $match: {
              $expr: {
                $and: [
                  { $eq: ['$fromUser', '$$friendId'] },
                  { $eq: ['$type', 'friend'] },
                  { $eq: ['$status', 'active'] },
                ],
              },
            },
          },
        ],
        as: 'friendsOfFriends',
      },
    },

    // Unwind to get individual recommendations
    { $unwind: '$friendsOfFriends' },

    // Exclude already connected users
    {
      $lookup: {
        from: 'connections',
        let: { recommendedId: '$friendsOfFriends.toUser' },
        pipeline: [
          {
            $match: {
              $expr: {
                $and: [
                  { $eq: ['$fromUser', userId] },
                  { $eq: ['$toUser', '$$recommendedId'] },
                ],
              },
            },
          },
        ],
        as: 'existingConnection',
      },
    },
    {
      $match: {
        existingConnection: { $size: 0 },
        'friendsOfFriends.toUser': { $ne: userId },
      },
    },

    // Group by recommended user and count mutual friends
    {
      $group: {
        _id: '$friendsOfFriends.toUser',
        mutualFriends: { $sum: 1 },
      },
    },

    // Sort by mutual friends count
    { $sort: { mutualFriends: -1 } },
    { $limit: limit },

    // Lookup user details
    {
      $lookup: {
        from: 'users',
        localField: '_id',
        foreignField: '_id',
        as: 'user',
      },
    },
    { $unwind: '$user' },

    // Project final shape
    {
      $project: {
        _id: '$user._id',
        username: '$user.username',
        profile: '$user.profile',
        interests: '$user.interests',
        mutualFriends: 1,
      },
    },
  ]);

  return recommendations;
}

Shortest Path Between Users

export async function findShortestPath(
  fromUserId: ObjectId,
  toUserId: ObjectId,
  maxDepth: number = 6 // Six degrees of separation
): Promise<User[] | null> {
  // BFS implementation
  const queue: Array<{ userId: ObjectId; path: ObjectId[] }> = [
    { userId: fromUserId, path: [fromUserId] },
  ];
  const visited = new Set<string>([fromUserId.toString()]);

  while (queue.length > 0) {
    const { userId, path } = queue.shift()!;

    if (path.length > maxDepth) continue;

    // Get friends of current user
    const friends = await Connection.find({
      fromUser: userId,
      type: 'friend',
      status: 'active',
    }).select('toUser');

    for (const friend of friends) {
      const friendId = friend.toUser;

      // Found the target!
      if (friendId.equals(toUserId)) {
        const fullPath = [...path, friendId];
        return User.find({ _id: { $in: fullPath } }).sort({
          _id: { $in: fullPath },
        });
      }

      // Add to queue if not visited
      if (!visited.has(friendId.toString())) {
        visited.add(friendId.toString());
        queue.push({
          userId: friendId,
          path: [...path, friendId],
        });
      }
    }
  }

  return null; // No path found
}

Real-Time Updates

Track Interactions

export async function recordInteraction(
  userId: ObjectId,
  targetId: ObjectId,
  type: InteractionType,
  context?: any
) {
  // Create interaction record
  await Interaction.create({
    userId,
    targetId,
    type,
    context,
    timestamp: new Date(),
  });

  // Update connection if exists
  if (type === 'like' || type === 'message') {
    const connection = await Connection.findOne({
      fromUser: userId,
      toUser: targetId,
    });

    if (connection) {
      connection.metadata.interactions += 1;
      connection.strength = await calculateConnectionStrength(userId, targetId);
      await connection.save();
    }
  }

  // Handle matches
  if (type === 'like') {
    const reciprocalLike = await Interaction.findOne({
      userId: targetId,
      targetId: userId,
      type: 'like',
    });

    if (reciprocalLike) {
      await createMatch(userId, targetId);
    }
  }
}

async function createMatch(user1Id: ObjectId, user2Id: ObjectId) {
  // Create bidirectional connections
  await Connection.insertMany([
    {
      fromUser: user1Id,
      toUser: user2Id,
      type: 'match',
      status: 'active',
      strength: await calculateConnectionStrength(user1Id, user2Id),
      metadata: {
        mutualFriends: (await getMutualFriends(user1Id, user2Id)).length,
        sharedInterests: [],
        interactions: 1,
      },
      createdAt: new Date(),
    },
    {
      fromUser: user2Id,
      toUser: user1Id,
      type: 'match',
      status: 'active',
      strength: await calculateConnectionStrength(user2Id, user1Id),
      metadata: {
        mutualFriends: (await getMutualFriends(user2Id, user1Id)).length,
        sharedInterests: [],
        interactions: 1,
      },
      createdAt: new Date(),
    },
  ]);

  // Update user stats
  await User.updateMany(
    { _id: { $in: [user1Id, user2Id] } },
    {
      $inc: { 'stats.totalMatches': 1, 'stats.activeMatches': 1 },
    }
  );
}

Performance Optimization

Caching Strategy

import { Redis } from 'ioredis';

const redis = new Redis(process.env.REDIS_URL);

export async function getCachedDiscoveryFeed(userId: ObjectId): Promise<User[]> {
  const cacheKey = `feed:${userId}`;
  const cached = await redis.get(cacheKey);

  if (cached) {
    return JSON.parse(cached);
  }

  const feed = await getDiscoveryFeed(userId);

  // Cache for 10 minutes
  await redis.setex(cacheKey, 600, JSON.stringify(feed));

  return feed;
}

// Invalidate cache on interactions
export async function invalidateUserCache(userId: ObjectId) {
  await redis.del(`feed:${userId}`);
}

Batch Processing

// Update connection strengths in batch (run nightly)
export async function updateConnectionStrengths() {
  const connections = await Connection.find({
    type: { $in: ['friend', 'match'] },
    status: 'active',
  });

  const batchSize = 100;
  for (let i = 0; i < connections.length; i += batchSize) {
    const batch = connections.slice(i, i + batchSize);

    await Promise.all(
      batch.map(async (conn) => {
        const strength = await calculateConnectionStrength(conn.fromUser, conn.toUser);

        await Connection.updateOne({ _id: conn._id }, { $set: { strength } });
      })
    );
  }
}

Building a custom social graph gives you the flexibility to create unique matching algorithms tailored to your platform's specific needs without external API constraints.