Docs Hub VaagaTech Main
Overview Architecture API & SDK Docs Hub VaagaTech Main →
Architecture & Internals

VaakFlags Architecture

Decoupled control plane and distributed evaluation architecture ensuring sub-millisecond lookups, offline resilience, and zero network hops on hot execution paths.

Explore API Reference Return to Overview

End-to-End System Topology

Distributed edge and client architecture eliminating centralized evaluation bottlenecks.

Central Control Plane

Visual administrative console for authoring rules, defining targeting cohorts, assigning rollout percentages, and scheduling releases.

In-Memory Evaluation Engine

Client SDKs evaluate rules entirely in local RAM. Features zero network latency overhead during user evaluations and zero API rate limits.

Real-Time SSE Sync

Server-Sent Events push rule modifications instantly to connected applications within 50ms, with automatic backoff and reconnection.

Audit Log & Single-Click Rollbacks

Every toggle, percentage change, and rule update is cryptographically recorded with full actor identity, enabling single-click instant rollbacks.

Part I

Logical Architecture

Domain model decomposition, hierarchical folder management, contextual rule graphs, segment relationships, and the 10-step evaluation pipeline.

1. LOGICAL ACTORS & GOVERNANCE INTERFACES DevOps & Release Engineers Product & Feature Owners Edge & Microservice Consumers 2. CONTROL PLANE LOGICAL DOMAINS Folder Hierarchy Tree & Explorer Grid DateTime Rules before/after/between Segment Overrides Cohort & Prereq sets Zero-Context Gate Public flag isolation 3. DETERMINISTIC 10-STEP EVALUATION PIPELINE 0. Circuit Breaker → 1. Enabled Gate → 2. Schedule Window → 3. Prerequisite Flags → 4. Prerequisite Segments → 5. Segment Overrides → 6. DateTime & Context Rules → 7. Progressive Rollout → 8. Percentage Bucketing → 9. Default Fallback 4. TELEMETRY, AUDIT & ZOMBIE DETECTION Cryptographic Audit Trail Latency Percentiles (p50 / p90 / p99) Zombie & Stale Flag Detector
Part II

Technical Architecture & Physical Infrastructure

Physical Kubernetes container sizing, real-time SSE push streaming (< 50ms), Redis Pub/Sub cluster, and zero-network-hop in-memory SDK evaluation.

1. INGRESS & TRAFFIC ROUTING Application Load Balancer / Envoy Gateway (TLS 1.3) WAF Rate Limiting & HTTP/2 Persistent SSE Streaming 2. KUBERNETES CONTROL PLANE PODS (PORT 4300) API Pod 1 (Active) • Fastify REST + SSE Event Bus (Port 4300) • Node.js 24 LTS (--max-old-space-size=768) • Up to 10,000 Concurrent SSE Connections API Pod 2 (Active) • Webhook Dispatcher & Scheduled Toggles • Prometheus Telemetry Scrape (Port 9090) • Graceful Draining: /readyz 503 during deployment 3. MULTI-LANGUAGE EDGE SDKs & IN-MEMORY CACHE (LATENCY < 1MS) TypeScript Client OpenFeature Provider Python 3.10+ SDK Asyncio SSE client Go 1.22+ SDK Goroutine sync pool Java & Rust Zero-copy FFI 4. DISTRIBUTED STATE MESH, CACHE & COLD STORAGE Redis 7 Pub/Sub Cluster Broadcasts toggles in < 20ms PostgreSQL 16 Primary Row-Level Security & Audit Logs S3 / GCS Cold Storage 365-day compressed telemetry archive

Evaluation Operators & Priority Chains

Rules evaluate sequentially in an explicit priority chain until a matching rule fires.

Operator Description Example Rule Condition
EQUALS / NOT_EQUALS Exact string, numeric, or boolean equality matching. country EQUALS "IN"
IN / NOT_IN Membership in a set of allowed values. tier IN ["enterprise", "growth"]
CONTAINS / STARTS_WITH Sub-string or prefix matching on string attributes. email ENDS_WITH "@vaagatech.com"
GREATER_THAN / LESS_THAN Numeric threshold comparisons. account_age_days GREATER_THAN 30
SEMVER_GTE / SEMVER_LTE Semantic version comparison for mobile and native apps. client_version SEMVER_GTE "2.4.0"
PERCENTAGE_ROLLOUT Deterministic MurmurHash3 bucketing (0–100%). rollout 25% OF userId
BEFORE / AFTER / BETWEEN_DATETIME Compares live current_datetime (or a context timestamp) with ISO-8601 values. current_datetime between_datetime ["2026-11-20T00:00:00Z","2026-11-30T23:59:59Z"]
DATE_EQ Calendar-day equality (UTC). current_datetime date_eq "2026-12-25"
IN_SEGMENT / NOT_IN_SEGMENT Reusable segment membership. segment in_segment ["enterprise-orgs"]
FLAG_EVAL_EQ Depends on the state of another flag. payment-v2 flag_eval_eq "true"
Evaluation pipeline: Circuit breaker → enabled → schedule → prerequisite flags → prerequisite segments → segment overrides → target rules → progressive rollout → percentage rollout → default. Post-processors (ATTACH_SEGMENT, SET_TELEMETRY) run after a match.
Public vs. secure flags: Public flags may only reference global attributes (current_datetime, app_version, environment). User-context rules and segment overrides are rejected at create/update time.
Circuit breaker: When the failure counter reaches the threshold the breaker trips to OPEN and the flag serves its off value with reason CIRCUIT_BREAKER_TRIPPED. Operators can FORCE_OPEN, FORCE_CLOSED or RESET manually.
Deterministic MurmurHash3 Bucketing: Percentage rollouts hash the combined string `${flagKey}:${userId}` through a 32-bit MurmurHash3 algorithm modulo 100. This guarantees identical user bucket assignment across multiple services and servers.