scaling.mdx

title	Scaling Applications
description	Learn how to scale your Multisynq applications for high performance and large user bases

Scaling Multisynq Applications

Multisynq is built to scale from prototype to production, supporting applications with thousands of concurrent users. This guide covers scaling strategies, performance optimization, and architectural patterns for large-scale applications.

Understanding Multisynq's Scaling Architecture

Session-Based Scaling

Multisynq scales horizontally through sessions:

• Session Isolation: Each session runs independently
• Automatic Load Distribution: Sessions are distributed across reflectors
• Elastic Scaling: New reflector instances spin up as needed

Performance Characteristics

• Per Session: Up to 100+ concurrent users (depends on application complexity)
• Per Reflector: Hundreds of active sessions
• Global Scale: Unlimited sessions across multiple reflectors

Scaling Strategies

1. Session Sharding

Split your application across multiple sessions based on logical boundaries:

class GameLobbyModel extends Multisynq.Model {
  init(options) {
    super.init(options);
    this.maxPlayersPerRoom = 50;
    this.rooms = new Map();
    this.subscribe(this.sessionId, "joinRoom", this.handleJoinRoom);
  }

  handleJoinRoom(data) {
    const { userId, preferredRoom } = data;
    
    // Find or create a room with space
    const room = this.findAvailableRoom(preferredRoom);
    
    if (room.playerCount >= this.maxPlayersPerRoom) {
      // Create new session for overflow
      const newSessionId = this.createNewGameSession();
      this.publish(userId, "redirectToSession", { sessionId: newSessionId });
    } else {
      this.addPlayerToRoom(room, userId);
    }
  }

  createNewGameSession() {
    // Logic to spawn new session
    return Multisynq.App.autoSession();
  }
}

2. Geographic Distribution

Use regional reflectors for global applications:

// Detect user location and choose nearest reflector
async function joinOptimalSession(appConfig) {
  const userRegion = await detectUserRegion();
  
  const reflectorConfig = {
    'us-east': 'https://reflector-us-east.multisynq.io',
    'eu-west': 'https://reflector-eu-west.multisynq.io',
    'asia-pacific': 'https://reflector-asia.multisynq.io'
  };

  return Multisynq.Session.join({
    ...appConfig,
    reflector: reflectorConfig[userRegion] || reflectorConfig['us-east']
  });
}

3. Hierarchical Sessions

Create parent-child session relationships:

class MasterSessionModel extends Multisynq.Model {
  init(options) {
    super.init(options);
    this.childSessions = new Map();
    this.subscribe(this.sessionId, "createChildSession", this.createChild);
  }

  createChild(data) {
    const childSessionId = Multisynq.App.autoSession();
    
    // Store reference to child session
    this.childSessions.set(childSessionId, {
      purpose: data.purpose,
      parentId: this.sessionId,
      createdAt: this.now()
    });

    // Broadcast child session info
    this.publish(this.sessionId, "childSessionCreated", {
      childId: childSessionId,
      purpose: data.purpose
    });
  }
}

Performance Optimization

1. Efficient Event Publishing

Minimize event frequency and payload size:

class OptimizedModel extends Multisynq.Model {
  init(options) {
    super.init(options);
    this.batchedUpdates = [];
    this.batchTimeout = null;
    this.subscribe(this.sessionId, "userAction", this.handleAction);
  }

  handleAction(data) {
    // Batch similar updates
    this.batchedUpdates.push(data);
    
    if (!this.batchTimeout) {
      this.batchTimeout = this.future(50).batchUpdates(); // 50ms batch window
    }
  }

  batchUpdates() {
    if (this.batchedUpdates.length > 0) {
      // Send all updates in one event
      this.publish(this.sessionId, "batchedUpdates", {
        updates: this.batchedUpdates,
        count: this.batchedUpdates.length
      });
      
      this.batchedUpdates = [];
    }
    this.batchTimeout = null;
  }
}

2. Smart Data Structures

Use efficient data structures for large datasets:

class ScalableDataModel extends Multisynq.Model {
  init(options) {
    super.init(options);
    
    // Use Maps for O(1) lookups
    this.users = new Map();
    this.spatialIndex = new Map(); // Grid-based spatial indexing
    
    // Track only essential data in main model
    this.userSummaries = new Map(); // Lightweight user data
  }

  addUser(userData) {
    const { id, x, y } = userData;
    
    // Store full data
    this.users.set(id, userData);
    
    // Store lightweight summary
    this.userSummaries.set(id, { id, x, y, lastUpdate: this.now() });
    
    // Update spatial index
    this.updateSpatialIndex(id, x, y);
    
    // Only publish summary to reduce bandwidth
    this.publish(this.sessionId, "userAdded", this.userSummaries.get(id));
  }

  updateSpatialIndex(userId, x, y) {
    const gridX = Math.floor(x / 100); // 100-unit grid
    const gridY = Math.floor(y / 100);
    const gridKey = `${gridX},${gridY}`;
    
    if (!this.spatialIndex.has(gridKey)) {
      this.spatialIndex.set(gridKey, new Set());
    }
    this.spatialIndex.get(gridKey).add(userId);
  }

  getUsersInRegion(x, y, radius) {
    const nearbyUsers = [];
    const gridRadius = Math.ceil(radius / 100);
    
    for (let dx = -gridRadius; dx <= gridRadius; dx++) {
      for (let dy = -gridRadius; dy <= gridRadius; dy++) {
        const gridKey = `${Math.floor(x/100) + dx},${Math.floor(y/100) + dy}`;
        const gridUsers = this.spatialIndex.get(gridKey);
        
        if (gridUsers) {
          gridUsers.forEach(userId => {
            const user = this.userSummaries.get(userId);
            if (user && this.distance(x, y, user.x, user.y) <= radius) {
              nearbyUsers.push(user);
            }
          });
        }
      }
    }
    
    return nearbyUsers;
  }
}

3. View-Side Optimization

Implement efficient rendering on the view side:

class ScalableView extends Multisynq.View {
  constructor(model) {
    super(model);
    this.visibleUsers = new Map();
    this.renderQueue = [];
    this.lastRender = 0;
    
    this.subscribe(this.sessionId, "userAdded", this.queueUserRender);
    this.subscribe(this.sessionId, "batchedUpdates", this.processBatch);
  }

  queueUserRender(userData) {
    this.renderQueue.push({ type: 'add', data: userData });
    this.scheduleRender();
  }

  processBatch(batchData) {
    // Process multiple updates efficiently
    batchData.updates.forEach(update => {
      this.renderQueue.push({ type: 'update', data: update });
    });
    this.scheduleRender();
  }

  scheduleRender() {
    const now = this.now();
    if (now - this.lastRender < 16) { // Limit to 60 FPS
      return;
    }

    requestAnimationFrame(() => {
      this.processRenderQueue();
      this.lastRender = this.now();
    });
  }

  processRenderQueue() {
    // Process all queued renders in one batch
    while (this.renderQueue.length > 0) {
      const renderItem = this.renderQueue.shift();
      this.processRenderItem(renderItem);
    }
  }
}

Memory Management

1. Cleanup Strategies

Implement proper cleanup for long-running sessions:

class MemoryEfficientModel extends Multisynq.Model {
  init(options) {
    super.init(options);
    this.users = new Map();
    this.inactiveTimeout = 300000; // 5 minutes
    
    // Regular cleanup
    this.future(60000).cleanupInactiveUsers(); // Every minute
  }

  cleanupInactiveUsers() {
    const now = this.now();
    const toRemove = [];
    
    for (const [userId, user] of this.users) {
      if (now - user.lastActivity > this.inactiveTimeout) {
        toRemove.push(userId);
      }
    }
    
    toRemove.forEach(userId => {
      this.users.delete(userId);
      this.publish(this.sessionId, "userRemoved", { userId });
    });
    
    // Schedule next cleanup
    this.future(60000).cleanupInactiveUsers();
  }
}

2. Data Pagination

Handle large datasets with pagination:

class PaginatedDataModel extends Multisynq.Model {
  init(options) {
    super.init(options);
    this.allData = new Map();
    this.pageSize = 50;
    this.subscribe(this.sessionId, "requestPage", this.sendPage);
  }

  sendPage(request) {
    const { userId, page, filters } = request;
    const filteredData = this.filterData(filters);
    const startIndex = page * this.pageSize;
    const pageData = Array.from(filteredData.values())
      .slice(startIndex, startIndex + this.pageSize);
    
    this.publish(userId, "pageData", {
      page,
      data: pageData,
      hasMore: startIndex + this.pageSize < filteredData.size
    });
  }
}

Monitoring and Metrics

1. Performance Monitoring

Track key metrics in your application:

class MonitoredModel extends Multisynq.Model {
  init(options) {
    super.init(options);
    this.metrics = {
      userCount: 0,
      eventCount: 0,
      memoryUsage: 0,
      lastSnapshot: this.now()
    };
    
    // Report metrics periodically
    this.future(30000).reportMetrics();
  }

  reportMetrics() {
    this.metrics.memoryUsage = this.estimateMemoryUsage();
    
    // Send metrics to monitoring service
    this.publish("monitoring", "metrics", {
      sessionId: this.sessionId,
      timestamp: this.now(),
      ...this.metrics
    });
    
    // Schedule next report
    this.future(30000).reportMetrics();
  }

  estimateMemoryUsage() {
    // Rough estimation of memory usage
    return JSON.stringify(this).length;
  }
}

2. Auto-scaling Triggers

Implement auto-scaling based on metrics:

class AutoScalingModel extends Multisynq.Model {
  init(options) {
    super.init(options);
    this.userLimit = 80; // Scale at 80% capacity
    this.subscribe(this.sessionId, "view-join", this.checkScaling);
  }

  checkScaling() {
    if (this.viewCount >= this.userLimit) {
      // Trigger creation of new session
      this.publish("scaling", "createNewSession", {
        reason: "user_limit",
        currentUsers: this.viewCount,
        sessionId: this.sessionId
      });
      
      // Redirect new users to the new session
      this.redirectNewUsers = true;
    }
  }
}

Deployment Strategies

1. Blue-Green Deployment

Deploy new versions without downtime:

// Version management in your application
class VersionedModel extends Multisynq.Model {
  init(options) {
    super.init(options);
    this.version = options.version || "1.0.0";
    this.compatibleVersions = ["1.0.0", "1.0.1"]; // Backward compatibility
  }

  handleVersionCheck(data) {
    const { clientVersion } = data;
    
    if (!this.compatibleVersions.includes(clientVersion)) {
      this.publish(data.userId, "versionMismatch", {
        requiredVersion: this.version,
        downloadUrl: "https://myapp.com/update"
      });
    }
  }
}

2. Feature Flags

Control feature rollout:

class FeatureFlagModel extends Multisynq.Model {
  init(options) {
    super.init(options);
    this.features = options.features || {
      newUI: false,
      advancedFeatures: true,
      betaMode: false
    };
  }

  isFeatureEnabled(featureName, userId) {
    // Implement feature flag logic (gradual rollout, A/B testing, etc.)
    return this.features[featureName] || false;
  }
}

Best Practices for Scale

1. Design Principles

• Keep sessions focused - Each session should have a clear purpose
• Minimize cross-session communication - Use external services for global state
• Plan for failure - Design graceful degradation when sessions become unavailable
• Monitor proactively - Track metrics before problems occur

2. Code Patterns

// Good: Efficient data access
class EfficientModel extends Multisynq.Model {
  findUser(userId) {
    return this.users.get(userId); // O(1) lookup
  }
}

// Avoid: Linear searches in large datasets
class IneffientModel extends Multisynq.Model {
  findUser(userId) {
    return this.userArray.find(u => u.id === userId); // O(n) lookup
  }
}

3. Resource Management

• Cleanup inactive data regularly
• Use appropriate data structures for your access patterns
• Batch operations when possible
• Implement proper error handling for resource exhaustion

Summary

Scaling Multisynq applications requires:

1. Session-based architecture - Design your application around session boundaries
2. Performance optimization - Use efficient data structures and event patterns
3. Memory management - Implement cleanup and avoid memory leaks
4. Monitoring - Track metrics and implement auto-scaling
5. Deployment strategies - Plan for zero-downtime updates

By following these patterns, you can build Multisynq applications that scale from small prototypes to large-scale production systems serving thousands of concurrent users.