Multi-region deployment

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:

Backend servers - Handle agent logic, conversation processing, and business rules
Proxy servers - Manage WebRTC/SIP connections and media streaming
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

Define region parameters

Choose a country code and region name that clearly identifies the geographic location.

var countryCode = "US";
var regionName = "WEST";

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

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);

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.

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:

Enable/disable servers

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);

Maintenance mode

Put servers in maintenance mode without fully disabling them:

await regionManager.EnableRegionServerMaintenance(
    "US-WEST",
    serverId,
    publicReason: "System update in progress",
    privateReason: "Applying security patches"
);

Safe deletion

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

Measure user distribution

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

Start with critical regions

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

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

Deploy redundant servers in each region (minimum 2 Backend, 2 Proxy)
Use health checks to detect failing nodes
Configure automatic traffic rerouting when servers enter maintenance mode
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:

Disable all servers

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

Disable the region

Put the region itself in disabled state:

await regionManager.DisableRegion(
    "US-WEST",
    "Region decommissioned",
    "Infrastructure migration complete"
);

Verify no active nodes

Ensure no servers are reporting status before deletion.

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.

FlowApp System

API Reference

Advanced

Multi-region deployment

Overview

Architecture

Region components

Regional isolation

Creating a region

Server management

Adding servers

Server lifecycle

Region status management

Maintenance mode

Disabling regions

Best practices

Geographic distribution

Capacity planning

Failover strategy

Security

Monitoring regions

Deleting regions

Next steps

Monitoring

Scaling

​Overview

​Architecture

​Region components

​Regional isolation

​Creating a region

​Server management

​Adding servers

​Server lifecycle

​Region status management

​Maintenance mode

​Disabling regions

​Best practices

​Geographic distribution

​Capacity planning

​Failover strategy

​Security

​Monitoring regions

​Deleting regions

​Next steps

Monitoring

Scaling

Overview

Architecture

Region components

Regional isolation

Creating a region

Server management

Adding servers

Server lifecycle

Region status management

Maintenance mode

Disabling regions

Best practices

Geographic distribution

Capacity planning

Failover strategy

Security

Monitoring regions

Deleting regions

Next steps