Architecture & Performance

Flagpool is built on a local-evaluation, edge-first architecture. Flag configurations are served from a global CDN, cached in-memory by the SDK, and evaluated locally — no network calls per flag check.

How it works

┌──────────────┐       ┌──────────────────┐       ┌──────────────────┐
│   Dashboard  │       │   Global CDN     │       │    Your App      │
│  (Manage)    │ ────▶ │   (Edge Cache)   │ ────▶ │   (SDK Cache)    │
└──────────────┘       └──────────────────┘       └──────────────────┘
                              ~20-60ms                   < 1ms
                          initial fetch              every evaluation

1. You configure flags in the Flagpool dashboard
2. Configurations are exported to Cloudflare R2 with global edge caching
3. The SDK fetches the payload once (~50ms from the nearest edge node)
4. Every subsequent isEnabled() or getValue() call evaluates locally in-memory

Local evaluation

All flag evaluations happen inside the SDK — no API calls, no round trips, no waiting. The evaluation engine processes targeting rules, user attributes, and percentage rollouts in microseconds.

Approach	12 flag checks	100 flag checks
Remote API per check	~1,200ms	~10,000ms
Flagpool (local)	< 1ms	< 1ms

This is what makes Flagpool safe for hot code paths — checkout flows, rendering loops, API middleware — anywhere latency matters.

Global edge network

Flag configurations are distributed across Cloudflare's global edge network, meaning your SDK always fetches from the nearest point of presence:

Region	Typical edge response
Americas	~20ms
Europe	~15ms
Asia-Pacific	~25ms

Updates propagate globally in under 50ms after a flag change. The CDN uses Cloudflare R2 with free egress, so there are no bandwidth charges regardless of scale.

Two-layer caching

Flagpool uses two layers of caching to ensure near-instant flag availability:

Layer	TTL	Purpose
Edge cache	1 hour	Fast global delivery from nearest edge node
SDK cache	60 seconds	Reduce requests, instant subsequent loads

Stale-while-revalidate

The SDK implements smart caching so users never wait for a flag fetch after the initial load:

0-60s:    Serve from SDK cache (instant)
60-360s:  Serve stale, fetch fresh in background (instant + update)
360s+:    Fetch fresh (wait for response)

This means flag evaluations are always fast, even during cache revalidation.

Cache invalidation

When flags change in the dashboard:

Flag change → Export to storage → Purge edge cache → Fresh content
                                                          │
                                              Next SDK poll gets
                                              updated flags immediately

Payload efficiency

Flag configurations are optimized for minimal bandwidth. With gzip/brotli compression, even large flag sets load quickly on slow connections:

Flag count	Compressed size
10 flags	~1-2 KB
50 flags	~5-8 KB
100 flags	~10-15 KB

Real-world performance

Scenario	Response time
Edge cache HIT	~20-60ms
Origin fetch (cache MISS)	~150-250ms
SDK evaluation (local)	< 1ms

Typical user experience

First visit:
  └── Fetch flags from edge: ~50ms
  └── SDK initialization: ~5ms
  └── Flag evaluations: < 1ms each

Return visit (within 60s):
  └── Flags served from SDK cache: ~0ms
  └── Flag evaluations: < 1ms each

Return visit (after 60s):
  └── Revalidate from edge: ~50ms (background)
  └── Flag evaluations: < 1ms each (stale-while-revalidate)

Reliability & uptime

Flagpool is designed so that your application is never blocked by the flag service:

• Edge-first delivery — no single point of failure; flags are served from hundreds of edge locations
• Offline resilience — SDKs cache flags locally and continue working during network interruptions (see Offline & Caching)
• Safe defaults — if the SDK cannot reach the CDN and has no cache, it falls back to the default values you specify in code
• No single-region dependency — Cloudflare's global anycast network routes requests to the nearest healthy node

Cross-SDK consistency

The evaluation logic is identical across all platforms and SDKs. Whether your application runs on web, mobile, server, or edge, the same user with the same attributes always receives the same flag values — guaranteed. All SDKs pass 72+ conformance tests ensuring identical hash algorithms, rule evaluation, and operator behavior.

Next steps

• Offline & Caching — how the SDK handles network interruptions
• Security Overview — encryption and data handling
• SDKs — choose the right SDK for your platform