Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

System Architecture

Stitchd Feature Flag is a self-hosted feature flagging and experimentation platform built on a small set of Rust crates with two external data stores.

High-Level Diagram

graph TB
    subgraph Clients
        AdminUI[Admin UI / curl]
        App[Your Application]
        SDK[stitchd-sdk]
    end

    subgraph Gateway["stitchd-gateway"]
        REST[REST API\n:8080]
        GRPC_GW[gRPC FlagSync\n:50050]
    end

    subgraph Services
        AS[stitchd-auth-service\n:50051]
        FS[stitchd-flag-service\n:50052]
        SS[stitchd-segmentation-service\n:50053]
        ES[stitchd-event-service\n:50054]
        XS[stitchd-experimentation-service\n:50055]
    end

    subgraph Stores
        PG[(PostgreSQL\nconfig store)]
        CH[(ClickHouse\nevents store)]
    end

    AdminUI -->|HTTP REST| REST
    App -->|SdkClient::init| SDK
    SDK -->|gRPC SyncDefinitions| GRPC_GW
    SDK -->|REST list-segment check| REST

    REST -->|gRPC| AS
    REST -->|gRPC| FS
    REST -->|gRPC| SS
    REST -->|gRPC| ES
    REST -->|gRPC| XS
    GRPC_GW -->|gRPC proxy| FS

    AS -->|sqlx| PG
    FS -->|sqlx| PG
    SS -->|sqlx| PG
    XS -->|sqlx| PG
    ES -->|sqlx| PG
    ES -->|ClickHouse client| CH

Crate Map

CrateRoleType
stitchd-gatewayREST + gRPC gateway — single entry point for all external trafficBinary
stitchd-auth-serviceAuthentication (login, JWT) and organisation/project managementBinary
stitchd-flag-serviceFlag definitions, variant management, SDK flag-sync streamingBinary
stitchd-segmentation-serviceSegment membership evaluation and list-segment checksBinary
stitchd-event-serviceExperiment event ingestion, forwarded to ClickHouseBinary
stitchd-experimentation-serviceExperiment CRUD and result aggregationBinary
stitchd-stats-serviceScheduled statistics computation (60-min loop), on-demand recompute jobs, stats_jobs + stats_schedule managementBinary
stitchd-sdkServer-side Rust SDK — in-process flag evaluationLibrary
stitchd-coreDomain model, rule engine, segmentation logic, hashing, ID typesLibrary
stitchd-dbDatabase access layer (sqlx repositories + ClickHouse)Library
stitchd-protoProtobuf definitions and generated tonic stubs for all servicesLibrary
stitchd-eventsClickHouse event ingestion and migration helpersLibrary
xtaskBuild tool: mdBook docs generation, tool installationBinary

Design Principles

Gateway-fronted microservices — All external traffic (admin API, SDK flag sync, event ingestion) enters through stitchd-gateway. Backend services are never exposed directly, making it straightforward to add auth, rate limiting, or TLS termination in one place.

In-process evaluation — The SDK syncs flag definitions via gRPC on startup and keeps them in memory. Rule evaluation happens locally with zero network hops per request.

Dual data store — PostgreSQL handles transactional config; ClickHouse handles append-only, analytical event data. The two stores are intentionally separate so event load cannot affect flag evaluation latency.

Multi-tenancy at the project level — A single deployment hosts multiple tenants. Isolation is enforced at the database layer; every query is scoped to a tenant/project/env.

Further Reading