Concordance is a distributed configuration service for the iGentAI platform. It provides strongly consistent key-value storage with real-time pub/sub notifications, built on embedded Raft consensus and SQLite. In musical terms, concordance means a state of agreement — this service ensures every node in the cluster agrees on the same configuration state. Single Bun binary. Zero npm dependencies. One port for HTTP, WebSocket, and Raft peer traffic.

​
What It Stores

CategoryNamespace PatternExample
User preferencestenant:{id}/user:{uid}/preferencesTheme, editor settings, notification prefs
Tenant settingstenant:{id}/settingsOrg-wide defaults, feature flags
Session metadatatenant:{id}/sessions/{sid}Active session state, context
Project definitionstenant:{id}/projects/{pid}Project config, agent assignments
Device registriestenant:{id}/user:{uid}/devices/{did}Push tokens, device capabilities
Encrypted credentialstenant:{id}/credentialsOAuth tokens, API keys (encrypted at rest)
Automation definitionstenant:{id}/automationsWorkflow blueprints, trigger rules
Skill configstenant:{id}/skillsSkill parameters, enabled/disabled state
Integration configstenant:{id}/integrationsSlack, GitHub, Linear connection settings
Audit logstenant:{id}/auditConfiguration change history

​
Key Properties

PropertyDetail
ConsistencyLinearizable writes via Raft consensus (reads from local FSM state)
DurabilitySQLite with PRAGMA synchronous=FULL for the Raft log
Real-timeWebSocket pub/sub pushes changes to subscribers within milliseconds
Multi-tenancyAll namespaces are tenant-scoped (tenant:{id}/...)
CAS supportCompare-and-swap writes prevent lost updates
TTL supportOptional expiresAt per entry for automatic expiration
VersioningMonotonically increasing version per key for conflict detection
SnapshotsFull-state snapshots via bun:sqlite serialize/deserialize

​
Architecture at a Glance

                        ┌─────────────────────────────────────────┐
                        │            Concordance Node              │
                        │                                         │
  Diminuendo ──HTTP────►│  Bun.serve()  (:4100)                   │
  (gateway)    PUT/GET  │  ┌────────────────────────────────────┐ │
               DELETE   │  │  HTTP Router                       │ │
                        │  │  /api/v1/kv, /batch, /changes      │ │
  Diminuendo ──WS──────►│  │  /api/v1/cluster/*                 │ │
  (gateway)    JSON-RPC │  ├────────────────────────────────────┤ │
                        │  │  WebSocket Handler (/stream)       │ │
  Podium ──────HTTP────►│  │  kv/get, kv/set, watch/subscribe   │ │
  (agents)     GET only │  ├────────────────────────────────────┤ │
                        │  │  Raft Peer Transport (/raft)       │ │
               ◄───WS──│──│  RequestVote, AppendEntries         │ │
  Other nodes           │  └─────────────┬──────────────────────┘ │
                        │                │                        │
                        │         ┌──────▼───────┐                │
                        │         │  RaftNode     │                │
                        │         │  (consensus)  │                │
                        │         └──────┬───────┘                │
                        │                │ onApply                 │
                        │         ┌──────▼───────┐                │
                        │         │  FSM          │                │
                        │         │  (state       │                │
                        │         │   machine)    │──► pub/sub     │
                        │         └──────┬───────┘    broadcast   │
                        │                │                        │
                        │     ┌──────────┴──────────┐             │
                        │     │                     │             │
                        │  ┌──▼───┐            ┌────▼──┐          │
                        │  │state │            │raft   │          │
                        │  │ .db  │            │ .db   │          │
                        │  │(KV)  │            │(log)  │          │
                        │  └──────┘            └───────┘          │
                        └─────────────────────────────────────────┘

​
Who Uses It

Diminuendo gateway connects over both HTTP REST (writes) and WebSocket (reads + subscriptions). It authenticates with CONCORDANCE_API_KEY and has full read/write access. Diminuendo resolves client-facing ACP config/* scopes (like “user” or “tenant”) into full Concordance namespaces using the authenticated user’s identity. Podium agents connect over HTTP REST with CONCORDANCE_AGENT_API_KEY for read-only access to configuration values they need at runtime (skill configs, integration settings, credentials). Clients never talk to Concordance directly. They send ACP config/* JSON-RPC methods to Diminuendo, which resolves scopes to namespaces and proxies the request.

​
Data Flow

Client (ACP)                 Diminuendo                    Concordance
    │                            │                              │
    │  config/set                │                              │
    │  {scope:"user",           │                              │
    │   key:"theme",            │                              │
    │   value:"dark"}           │                              │
    ├───────────────────────────►│                              │
    │                            │  PUT /api/v1/kv/             │
    │                            │  tenant:acme/user:u1/        │
    │                            │  preferences/theme           │
    │                            ├─────────────────────────────►│
    │                            │                              │──► Raft propose
    │                            │                              │──► quorum commit
    │                            │                              │──► FSM apply
    │                            │          200 OK              │──► pub/sub
    │                            │◄─────────────────────────────┤
    │  config/update             │                              │
    │  {scope:"user",           │  watch/change (WebSocket)    │
    │   key:"theme",            │◄─────────────────────────────┤
    │   value:"dark",           │                              │
    │   version:2}              │                              │
    │◄───────────────────────────┤                              │

​
Repository Structure

diminuendo/concordance/
├── service/              # Concordance server process
│   ├── main.ts           # Entry point, CLI args, wiring
│   ├── server.ts         # Bun.serve() — HTTP + WebSocket + Raft on one port
│   ├── ws.ts             # WebSocket JSON-RPC handler for clients
│   ├── fsm.ts            # Finite State Machine — applies Raft entries to KV
│   ├── peers.ts          # WebSocket peer connection manager
│   ├── config.ts         # Configuration types and defaults
│   └── raft/
│       ├── node.ts       # Core Raft consensus algorithm
│       ├── log.ts        # SQLite-backed Raft log + stable store
│       ├── snapshot.ts   # Snapshot creation and installation
│       └── types.ts      # Raft message types and configuration
├── shared/               # Shared between Concordance service and Diminuendo
│   ├── types.ts          # KvEntry, ChangeEvent, scope resolution
│   ├── protocol.ts       # JSON-RPC types, WS/ACP method definitions
│   ├── schema.ts         # SQLite DDL for state.db and raft.db
│   ├── store.ts          # KvStore — SQLite-backed KV operations
│   └── index.ts          # Barrel export
└── test/                 # Test suite