Skip to main content

​
Overview

Iqra AI’s multi-region architecture allows you to deploy geographically distributed infrastructure to minimize latency and improve reliability. The system routes sessions to the nearest compute node based on geographic proximity, enabling you to combat the physical limitations of network speed. This is particularly critical for real-time voice applications where every millisecond counts in the user experience.

​
Architecture

​
Region components

Each region in Iqra AI consists of three core components:
  1. Backend servers - Handle agent logic, conversation processing, and business rules
  2. Proxy servers - Manage WebRTC/SIP connections and media streaming
  3. S3 storage - Store recordings, logs, and media files
Regions are identified by a composite ID format: {CountryCode}-{RegionName} (e.g., US-EAST, EU-CENTRAL).
The region management system is located in IqraInfrastructure/Managers/Region/RegionManager.cs:66.

​
Regional isolation

Each region operates independently with its own:
  • Compute resources (Backend and Proxy nodes)
  • Storage infrastructure (S3-compatible object storage)
  • Maintenance and availability status
  • Configuration and API keys

​
Creating a region

1

Define region parameters

Choose a country code and region name that clearly identifies the geographic location.
var countryCode = "US";
var regionName = "WEST";
2

Create the region

New regions are created in a safe, disabled state by default:
await regionManager.CreateRegion("US", "WEST");
This creates region US-WEST with:
  • Disabled status (prevents accidental traffic routing)
  • Maintenance mode enabled
  • No active servers
3

Configure S3 storage

Each region requires its own S3-compatible storage:
var s3Config = new RegionS3StorageServerData {
    Endpoint = "s3.us-west-1.amazonaws.com",
    AccessKey = "your-access-key",
    SecretKey = "your-secret-key",
    UseSSL = true
};

await regionManager.UpdateRegionS3Config("US-WEST", s3Config);
4

Add compute servers

Deploy Backend and Proxy servers to handle traffic:
var serverConfig = new CreateUpdateServerRequestModel {
    Endpoint = "backend-us-west-1.yourdomain.com",
    Type = ServerTypeEnum.Backend,
    APIKey = "generated-secure-api-key-min-32-chars",
    SIPPort = 5060,
    UseSSL = true,
    IsDevelopmentServer = false
};

await regionManager.AddOrUpdateRegionServer(
    "add", "US-WEST", null, serverConfig
);
API keys must be at least 32 characters long. Generate cryptographically secure keys for production deployments.
5

Enable the region

Once all infrastructure is configured and tested:
// Disable maintenance mode
await regionManager.DisableRegionMaintenance("US-WEST");

// Enable the region
await regionManager.EnableRegion("US-WEST");

​
Server management

​
Adding servers

Each region can contain multiple Backend and Proxy servers for horizontal scaling: 
var proxyConfig = new CreateUpdateServerRequestModel {
    Endpoint = "proxy-us-west-1.yourdomain.com",
    Type = ServerTypeEnum.Proxy,
    APIKey = GenerateSecureKey(64),
    SIPPort = 5060,
    UseSSL = true
};

await regionManager.AddOrUpdateRegionServer(
    "add", "US-WEST", null, proxyConfig
);

​
Server lifecycle

Servers support granular lifecycle management:
Control traffic routing to individual servers:
// Disable a server (stops new sessions, allows existing to complete)
await regionManager.DisableRegionServer(
    "US-WEST",
    serverId,
    publicReason: "Scheduled maintenance",
    privateReason: "Kernel security update"
);

// Re-enable after maintenance
await regionManager.EnableRegionServer("US-WEST", serverId);
Put servers in maintenance mode without fully disabling them:
await regionManager.EnableRegionServerMaintenance(
    "US-WEST",
    serverId,
    publicReason: "System update in progress",
    privateReason: "Applying security patches"
);
Servers can only be deleted when they meet strict safety criteria:
await regionManager.DeleteRegionServerSafe("US-WEST", serverId);
Deletion will fail if:
  • Server is not in disabled state
  • Server is still reporting online status
  • Server has active sessions

​
Region status management

​
Maintenance mode

Use maintenance mode for planned updates without fully disabling the region: 
// Enable maintenance
await regionManager.EnableRegionMaintenance(
    "US-WEST",
    publicReason: "Scheduled maintenance window",
    privateReason: "Infrastructure upgrade"
);

// Disable maintenance
await regionManager.DisableRegionMaintenance("US-WEST");
The publicReason is visible to end users, while privateReason is for internal operations teams. Use public reasons that are customer-friendly.

​
Disabling regions

Temporarily or permanently disable regions: 
// Disable region
await regionManager.DisableRegion(
    "US-WEST",
    publicReason: "Region temporarily unavailable",
    privateReason: "Datacenter power issue"
);

// Re-enable
await regionManager.EnableRegion("US-WEST");

​
Best practices

​
Geographic distribution

1

Measure user distribution

Analyze where your users are located geographically. Deploy regions close to your largest user populations.
2

Start with critical regions

Begin with 1-2 regions in your primary markets before expanding globally.
3

Consider data residency

For enterprise deployments, ensure you have regions in countries with data residency requirements (e.g., GCC nations, EU).

​
Capacity planning

Plan server capacity based on expected concurrent sessions:
  • Backend servers: 50-100 concurrent calls per server (depending on hardware)
  • Proxy servers: 100-200 concurrent WebRTC connections per server
  • Storage: Estimate 1-5 MB per minute of recorded conversation

​
Failover strategy

  1. Deploy redundant servers in each region (minimum 2 Backend, 2 Proxy)
  2. Use health checks to detect failing nodes
  3. Configure automatic traffic rerouting when servers enter maintenance mode
  4. Maintain a secondary region for critical deployments

​
Security

Never reuse API keys across servers or regions. Each server must have a unique, cryptographically secure API key of at least 32 characters.
  • Rotate API keys quarterly
  • Use different S3 credentials for each region
  • Implement network isolation between regions
  • Restrict database access to internal networks only

​
Monitoring regions

Monitor regional health using the metrics system: 
var activeNodes = await serverMetricsManager.GetAllActiveNodesAsync();

// Filter by region
var usWestNodes = activeNodes.Where(n =>
    (n is BackendServerStatusData b && b.RegionId == "US-WEST") ||
    (n is ProxyServerStatusData p && p.RegionId == "US-WEST")
);

foreach (var node in usWestNodes) {
    Console.WriteLine($"{node.NodeId}: {node.RuntimeStatus}");
}
See Monitoring and observability for detailed metrics and alerting.

​
Deleting regions

Region deletion requires strict safety checks:
1

Disable all servers

Disable every server in the region and wait for active sessions to complete.
2

Disable the region

Put the region itself in disabled state:
await regionManager.DisableRegion(
    "US-WEST",
    "Region decommissioned",
    "Infrastructure migration complete"
);
3

Verify no active nodes

Ensure no servers are reporting status before deletion.
4

Delete safely

var result = await regionManager.DeleteRegionSafe("US-WEST");
if (!result.IsSuccess) {
    Console.WriteLine(result.ErrorMessage);
}
The deletion will fail with error DeleteRegion:NODES_ONLINE if any servers are still reporting status. This prevents accidental deletion of active infrastructure.

​
Next steps

Monitoring

Set up observability for your multi-region deployment

Scaling

Learn horizontal scaling strategies for high traffic

Build docs developers (and LLMs) love

Get started for freeTalk to us