SDK Architecture

SignaKit SDKs are built around a single architectural principle: fetch the config once, evaluate every flag locally, track events asynchronously. There are no per-evaluation API calls. decide() is a pure in-memory computation that returns in under a millisecond.

This document explains how that works end-to-end — from createInstance to the event ingest pipeline.

Overview

createInstance({ sdkKey })
  → HTTP GET: SignaKit CDN (full flag config, JSON)
  → stores config in memory
  → onReady() resolves

userCtx.decide(flagKey)
  → hash(userId + flagKey) → bucket number
  → walk targeting rules in memory
  → return decision (sync, ~< 1ms)
  → enqueue $exposure event (async, non-blocking)

event queue
  → batched HTTP POST → Lambda (validates, sends to SQS)
  → consumer Lambda → PostgreSQL + S3

No network call happens during decide(). The CDN fetch is a one-time operation per process lifetime, refreshed on a background interval.

Initialization

When you call createInstance({ sdkKey }), the SDK immediately begins an HTTP GET request to the SignaKit CDN. The response is a single JSON payload containing all flag configs for your project — every flag, its targeting rules, audience definitions, variation assignments, and traffic splits.

import { createInstance } from '@signakit/flags-node'

export const client = createInstance({ sdkKey: process.env.SIGNAKIT_SDK_KEY! })
await client.onReady()

onReady() returns a promise that resolves when the CDN fetch completes and the config is stored in memory. Until onReady() resolves, decide() returns null — unless a cached config from a previous run is available (see Caching below).

Local evaluation

Flag evaluation is a pure in-memory operation. When you call decide(), the SDK:

const userCtx = client.createUserContext('user-123', { plan: 'pro', country: 'US' })
const decision = userCtx.decide('checkout-redesign')
// decision: { enabled: true, variationKey: 'treatment', variables: { ... } }

Exposure and event tracking

The first time decide() is called for a given user and flag combination within a user context, the SDK enqueues an $exposure event. This records that the user was exposed to the flag evaluation — it is the source of truth for experiment participation counts in the dashboard.

Subsequent calls to decide() for the same user context and flag key do not enqueue a second exposure.

First call:  userCtx.decide('checkout-redesign')
             → evaluates locally (sync, in-memory)
             → enqueues $exposure event (async, non-blocking)
             → returns decision

Second call: userCtx.decide('checkout-redesign')
             → evaluates locally (sync, in-memory)
             → no $exposure enqueued (already recorded)
             → returns decision

The event queue is flushed in the background. The SDK batches accumulated events and sends them as a single HTTP POST to the SignaKit event ingest endpoint. This flush happens asynchronously — it does not block decide() or your request path.

The same queue handles trackEvent() calls for custom conversion events. Both exposure events and custom events flow through the same pipeline:

SDK event queue
  → batched HTTP POST
  → Lambda: validates SDK key, forwards to SQS
  → consumer Lambda: writes to PostgreSQL + S3

The ingest path is entirely asynchronous. A slow or unavailable ingest endpoint does not affect flag evaluation — the SDK continues to operate from its in-memory config.

Config refresh

The SDK polls the SignaKit CDN on a background interval to pick up flag changes without restarting the process. The default polling interval varies by SDK:

When a new config is fetched, it replaces the in-memory config atomically. Subsequent decide() calls use the new config. In-flight evaluations that started before the swap complete against the old config — there is no partial state.

Force a refresh

Some SDKs expose a client.refresh() method to trigger an immediate config fetch outside the polling cycle. This is useful after you make a flag change in the dashboard and need to pick it up in a long-running process without waiting for the next poll.

// Force an immediate config fetch
await client.refresh()

What happens mid-request

Because config is swapped atomically, a user that calls decide() twice within the same request will always get the same variation — the config does not change between two calls in the same event loop tick. The swap only takes effect between polling cycles.

Caching (mobile SDKs)

Mobile SDKs — Flutter and React Native — persist the fetched config to local device storage. On startup, if the network is unavailable or the CDN fetch has not yet completed, the SDK loads the cached config and begins evaluating flags immediately from the last known state.

This means:

• onReady() resolves immediately when a cached config is available, even before the network fetch completes.
• If the network fetch succeeds, the in-memory config is updated and the cache is written with the fresh payload.
• If the network fetch fails and no cache exists, decide() returns null until a fetch succeeds.

The cache is keyed by SDK key, so multiple environments on the same device do not share config.

Server vs. browser SDKs

Both server and browser SDKs use the same fetch-once, evaluate-locally model. The differences are operational:

The SDK key is not a secret. It identifies your project but does not grant access to the SignaKit API or dashboard. Exposing it in browser-side code is expected and safe. Admin operations — creating flags, modifying rules, reading raw event data — require an API key, which is separate and must never be exposed client-side.

Server SDKs benefit from one config fetch being amortized across every request the process handles. A Node.js server handling 10,000 requests per second still makes only one CDN fetch per polling interval, not 10,000.

Browser SDKs fetch config once per page load (or app session, for React Native and Flutter). Each browser tab maintains its own copy of the config in memory.

Architecture diagram

┌─────────────────────────────────────────────────────┐
│ Application process (server) or browser tab         │
│                                                     │
│  createInstance({ sdkKey })                         │
│       │                                             │
│       ▼                                             │
│  CDN fetch (once)  ────────────► SignaKit CDN       │
│       │                                             │
│       ▼                                             │
│  In-memory config                                   │
│  (flags + rules + audiences)                        │
│       │                                             │
│       ▼                                             │
│  decide(flagKey)  ◄── createUserContext(id, attrs)  │
│       │                                             │
│       ├── hash(userId + flagKey) → bucket           │
│       ├── walk targeting rules                      │
│       └── return decision  (< 1ms, no network)      │
│                                                     │
│  Event queue                                        │
│       │  (batched, async flush)                     │
│       ▼                                             │
└─────────────────────────────────────────────────────┘
         │
         ▼
  Lambda (validate key, send to SQS)
         │
         ▼
  Consumer Lambda
         │
         ├──► PostgreSQL (experiment results)
         └──► S3 (raw event archive)

Related

• Feature Flags — decision object shape, flag states, and exposure tracking
• Targeted Delivery — how audience rules and percentage splits are structured
• A/B Testing — how bucketing is used to run controlled experiments
• Events & Metrics — trackEvent() and the conversion event pipeline
• Node.js SDK — full API reference for the server-side SDK