iGent Concert
/unison/architecture/

Unison Architecture

Resource, stream, REST, and Valkey architecture for Unison

Unison combines a Fabric resource/sync surface with compatibility REST routes and WebSocket change streams. The current implementation is stateless Bun API workers backed by Valkey for persistence, ordering, TTL indexes, and pub/sub fanout.

Component Overview

Unison Bun service
├── Fabric endpoint (/fabric)
├── REST compatibility API (/api/v1/*)
├── WebSocket stream (/stream)
├── Valkey-backed state, indexes, tenant streams, and pub/sub
├── Change publication
└── Explorer support

Consistency Model

Writes are applied by Lua scripts inside Valkey so entry updates, namespace indexes, tenant streams, TTL state, and pub/sub notifications move together atomically. Multiple Unison API processes can serve the same deployment without forming their own process-to-process cluster.

Namespace Model

Resource keys are tenant-scoped. Diminuendo resolves user-facing scopes such as user, tenant, session, project, and device into concrete namespaces before calling Unison.

ScopeExample namespace
Usertenant:{tenantId}/user:{userId}/preferences
Tenanttenant:{tenantId}/settings
Sessiontenant:{tenantId}/sessions/{sessionId}
Projecttenant:{tenantId}/projects/{projectId}
Devicetenant:{tenantId}/user:{userId}/devices/{deviceId}

Change Streams

Subscribers receive live change notifications over /stream or the Fabric sync surface. Durable catch-up uses the tenant changelog streams exposed by /api/v1/changes. Consumers should treat versions and sequence numbers as part of the conflict-detection and reconciliation contract.

Explorer

The Explorer is a separate UI surface in the root PM2 stack. Public fabric.dev.aws.igent.ai/explorer/ and unison.fabric.dev.aws.igent.ai/explorer/ routes proxy to the Explorer when it exists in the checkout.