Architecture Overview

FeatureSignals is built on a hexagonal architecture with a Go API server at the core, PostgreSQL for persistence, Redis for evaluation caching, and a stateless evaluation engine that serves sub-millisecond flag resolutions. This page gives you the high-level picture.

System Topology

A FeatureSignals deployment typically looks like this:

┌──────────────────────────────────────────────────────────────┐
│                     LOAD BALANCER                             │
│                  (NGINX / Cloud LB)                           │
└──────────┬─────────────────────────────────────┬─────────────┘
           │                                     │
    ┌──────▼──────┐  ┌──────────┐       ┌──────▼──────┐
    │ API Server 1 │  │   ...    │       │ API Server N│
    │  (Go, chi)   │  │          │       │  (Go, chi)  │
    └──────┬───────┘  └──────────┘       └──────┬───────┘
           │                                     │
    ┌──────▼──────┐                       ┌──────▼──────┐
    │    Redis    │◄──── PG LISTEN ──────►│    Redis    │
    │  (Cache)    │       /NOTIFY         │  (Cache)    │
    └─────────────┘                       └─────────────┘
           │                                     │
           └──────────────┬──────────────────────┘
                          │
                   ┌──────▼──────┐
                   │ PostgreSQL  │
                   │  (Primary)  │
                   └─────────────┘
                          │
        ┌─────────────────┼─────────────────┐
        │                 │                 │
   ┌────▼────┐     ┌─────▼─────┐     ┌────▼────┐
   │  SDK    │     │  Relay    │     │ Webhooks│
   │ Clients │     │  Proxy    │     │  (Async)│
   └─────────┘     └───────────┘     └─────────┘

All server instances are stateless and interchangeable. The Redis cache is populated at startup and invalidated in real-time via PostgreSQL LISTEN/NOTIFY. SDKs connect to the API or Relay Proxy for flag evaluation.

Core Components

Hexagonal Architecture

The Go server follows a ports-and-adapters (hexagonal) architecture. Domain logic sits at the center with zero dependencies on infrastructure:

handlers (HTTP) ──→ domain interfaces (ports) ←── store/postgres (DB adapter)
                 ──→ domain entities & logic  ←── cache adapter
                 ──→ eval engine              ←── webhook adapter

• Handlers only import domain interfaces — never concrete implementations.
• Domain logic is pure Go with no database, HTTP, or cache dependencies.
• Adapters (PostgreSQL store, Redis cache, webhook sender) implement domain interfaces and are wired in at startup.
• This means you can swap PostgreSQL for another database, or add gRPC alongside REST, without touching business logic.

Evaluation Hot Path

The flag evaluation path is the most performance-critical code in the system. It's designed for sub-millisecond latencies:

1. SDK checks local cache. If the flag ruleset is cached and fresh, evaluate locally. No network call.
2. SDK calls evaluation API. If the local cache is stale or missing, the SDK calls POST /v1/evaluate or the client-side evaluation endpoint.
3. API server reads from Redis. The compiled ruleset is fetched from Redis. No database query.
4. Evaluation engine resolves the flag. A stateless, allocation-minimizing Go engine runs the evaluation order and returns the result.
5. SDK caches the result. The SDK updates its local cache and returns the value to the application.

Deployment Models

Deep Dives

• Evaluation Engine — How flags resolve in <1ms
• Real-Time Updates — WebSocket streaming and polling
• SDKs — Client libraries for every stack