Skip to content
Ironflow Docs

Config Management

Ironflow provides environment-scoped configuration management built on NATS JetStream KV. It stores JSON documents representing application settings, feature flags, or system parameters — with atomic updates and real-time change notifications.

How It Works

Section titled “How It Works”

Config Management uses its own system-level NATS JetStream KV buckets (prefixed with SYS_config_), separate from the user-facing KV Store. While the KV Store provides raw key-value operations with APP_-prefixed buckets, Config Management adds:

  • Document semantics: Values are JSON objects, not arbitrary bytes.
  • Shallow merge: patch operations merge fields into an existing document rather than replacing it entirely.
  • CAS retries: Patches automatically retry on revision conflicts, preventing lost updates in concurrent environments.
  • Real-time watch: Browser clients can subscribe to config changes and react instantly.
  • Lazy initialization: Config buckets are created automatically on first use — no eager startup initialization required.
  • Self-healing: If a config bucket is accidentally deleted, it is recreated transparently on the next API call.
┌────────────────────────────┐
│     Config Management      │  ← JSON documents, patch/merge (SYS_config_*)
├────────────────────────────┤
│        KV Store            │  ← Raw key-value, CAS, TTL (APP_*)
├────────────────────────────┤
│    NATS JetStream KV       │  ← Durable stream storage
└────────────────────────────┘

When to Use Config vs. KV vs. Secrets

Section titled “When to Use Config vs. KV vs. Secrets”
FeatureUse ForAccess
Config ManagementApp settings, feature flags, environment togglesRead/write from SDK and CLI
KV StoreSession data, caching, high-frequency countersRead/write from SDK
SecretsAPI keys, DB passwords, certificatesWrite-only API; runtime injection only

Environment Scoping

Section titled “Environment Scoping”

Each environment has its own configuration namespace. A config document named app-settings in the production environment is completely isolated from app-settings in staging. This allows safe promotion of config changes across environments.

Event-Driven Updates

Section titled “Event-Driven Updates”

Every config change emits a system event on the internal NATS bus. This enables:

  • Dashboard real-time sync: The React dashboard reflects config changes instantly via WebSocket.
  • Workflow triggers: Config changes can trigger workflows (e.g., invalidate caches when feature flags change).
  • Audit trail: Config mutations are observable as NATS messages.

Subject and payload

Section titled “Subject and payload”

After a successful POST /api/v1/config/{name} or PATCH /api/v1/config/{name}, the server publishes on the pubsub bridge topic:

system.config.{name}.updated

The bridge maps this to the NATS subject public.{project}.{env}.system.config.{name}.updated. The payload is JSON:

{
  "name": "theme",
  "revision": 5,
  "data": { "presetId": "vintage-paper" },
  "updatedAt": "2026-04-23T17:31:46.000Z"
}

revision is the NATS KV revision assigned to the write. Subscribers that see out-of-order deliveries (rare but possible under retries) should drop events where revision is lower than the last value observed for that config key. The browser SDK’s configManager().watch() subscribes to this subject and invokes onUpdate on each event.

Publish is best-effort: the KV write is authoritative and the HTTP response returns 200 OK even if the subsequent publish fails. Subscribers that miss an event can always re-read via GET /api/v1/config/{name}.

In This Section

Section titled “In This Section”