# flippercloud/flipper architecture

> Architecture diagram of the GitHub repository flippercloud/flipper, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/flippercloud/flipper
- Repository: https://github.com/flippercloud/flipper

## Overview

##### Main components
- Core Library (lib/flipper):
- DSL & Configuration (Flipper, Flipper::DSL, Flipper::Configuration)
- Feature & Gate Model (Flipper::Feature, Flipper::Gate, Flipper::Gates::* classes)
- Expression Engine (Flipper::Expression::Builder & expression classes)
- Adapter Builder (Flipper::AdapterBuilder)
- Instrumentation (Flipper::Instrumentation, Instrumenters, Subscribers)
- Exporters (Flipper::Export, Exporters::JSON)
- Adapters (lib/flipper/adapters/*):
- Built-in: Memory, ActiveRecord, Redis, Moneta, PStore, Mongo, Sequel, HTTP, etc.
- Adapter Wrappers: Memoizable, Instrumented, Failover, Sync, Cache base, etc.
- REST API (flipper-api gem):
- Rack Middleware (Flipper::API::Middleware)
- JSON endpoints (lib/flipper/api/v1/actions & decorators)
- UI (flipper-ui gem):
- Rack App / Engine (Flipper::UI)
- Views & Assets (ERB templates, CSS/JS)
- Actions & Decorators
- Cloud Integration (flipper-cloud gem):
- Cloud DSL & Config (Flipper::Cloud::Configuration, DSL)
- Middleware & Routes
- Telemetry & Backoff (Flipper::Cloud::Telemetry)
- CLI (exe/flipper, lib/flipper/cli)
- Generators (lib/generators/flipper)
- Examples & Benchmarks (examples/*, benchmark/*)

##### Relationships & data flows
- Application code → uses → Flipper DSL/API → checks/enables/disables features
- Flipper Core → delegates → AdapterBuilder → selected Adapter → persists/reads flags from external store (DB, Redis, etc.)
- Instrumentation wrappers around Adapters → emit metrics/logs → Instrumenters/Subscribers
- Exporters → read from Core → output JSON, GZIP
- flipper-api middleware → receives HTTP requests → invokes Core → returns JSON
- flipper-ui Rack app → web UI → uses Core (through DSL/API) to display & modify flags → persists via Adapter
- flipper-cloud middleware → synchronizes Core with remote Cloud service → uses HTTP adapter under the hood → Telemetry & Backoff
- CLI → invokes Core & Exporters → outputs to STDOUT or files
- Generators → scaffolding for Rails apps → create initializer & migrations

##### Architectural patterns & principles
- Adapter Pattern: Core is adapter-agnostic; adapters plug in to support any data store
- Middleware Pipeline (Rack) for both API & UI
- DSL for expressive, Ruby-friendly feature checks & configuration
- Strategy Pattern for expressions & gates
- Separation of concerns:
- Core logic vs. persistence (adapters)
- UI vs. API vs. Cloud sync vs. CLI vs. Generators

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Consumers
    subgraph "Consumers"
        direction TB
        Apps["Consumer Apps"]:::external
        UIApp["UI Rack App"]:::apiui
        APIApp["API Rack App"]:::apiui
        CLI["CLI Tool"]:::apiui
    end

    %% Core Library
    subgraph "Flipper Core" 
        direction TB
        DSL["DSL & Configuration"]:::core
        FeatureGate["Feature & Gate Model"]:::core
        Expression["Expression Engine"]:::core
        AdapterBuilder["AdapterBuilder"]:::core
        Instrumentation["Instrumentation"]:::core
        Exporters["Exporters"]:::core
    end

    %% Adapters
    subgraph "Adapters" 
        direction TB
        AdapterWrappers["Adapter Wrappers"]:::adapters
        BuiltInAdapters["Built-In Adapters"]:::adapters
    end

    %% External Stores
    subgraph "External Stores"
        direction TB
        PostgreSQL("PostgreSQL"):::external
        Redis("Redis"):::external
        MongoDB("MongoDB"):::external
        HTTPService("HTTP Service"):::external
    end

    %% API/UI/Cloud/Gens/Examples/Benchmarks
    subgraph "flipper-api"
        direction TB
        APIMiddleware["API Middleware"]:::apiui
    end
    subgraph "flipper-ui"
        direction TB
        UIMiddleware["UI Middleware & Views"]:::apiui
    end
    subgraph "flipper-cloud"
        direction TB
        CloudMid["Cloud Middleware"]:::cloud
        Telemetry["Telemetry & Backoff"]:::cloud
    end
    subgraph "Generators"
        direction TB
        Gens["Rails Generators"]:::apiui
    end
    subgraph "Examples"
        direction TB
        Examples["Examples"]:::external
    end
    subgraph "Benchmarks"
        direction TB
        Bench["Benchmarks"]:::external
    end

    %% Connections
    Apps -->|"uses"| DSL
    UIApp -->|"uses"| DSL
    APIApp -->|"uses"| DSL
    CLI -->|"uses"| DSL

    DSL --> FeatureGate
    FeatureGate --> Expression
    Expression --> AdapterBuilder
    AdapterBuilder --> AdapterWrappers
    AdapterWrappers --> BuiltInAdapters
    BuiltInAdapters --> PostgreSQL
    BuiltInAdapters --> Redis
    BuiltInAdapters --> MongoDB
    BuiltInAdapters --> HTTPService
    AdapterWrappers --> Instrumentation
    Instrumentation -->|"wraps"| BuiltInAdapters
    DSL --> Exporters
    Exporters -->|"outputs JSON/GZIP"| CLI

    APIApp --> APIMiddleware
    APIMiddleware --> DSL
    UIMiddleware --> DSL
    UIApp --> UIMiddleware

    CloudMid --> DSL
    CloudMid --> HTTPService
    CloudMid --> Telemetry

    Gens --> DSL
    Examples --> DSL
    Bench --> DSL

    %% Click events
    click DSL "https://github.com/flippercloud/flipper/blob/main/lib/flipper.rb"
    click FeatureGate "https://github.com/flippercloud/flipper/blob/main/lib/flipper/feature.rb"
    click Expression "https://github.com/flippercloud/flipper/blob/main/lib/flipper/expression/builder.rb"
    click AdapterBuilder "https://github.com/flippercloud/flipper/blob/main/lib/flipper/adapter_builder.rb"
    click Instrumentation "https://github.com/flippercloud/flipper/tree/main/lib/flipper/instrumentation"
    click Exporters "https://github.com/flippercloud/flipper/blob/main/lib/flipper/export.rb"
    click BuiltInAdapters "https://github.com/flippercloud/flipper/tree/main/lib/flipper/adapters"
    click APIMiddleware "https://github.com/flippercloud/flipper/blob/main/lib/flipper/api/middleware.rb"
    click UIMiddleware "https://github.com/flippercloud/flipper/tree/main/lib/flipper/ui"
    click CloudMid "https://github.com/flippercloud/flipper/tree/main/lib/flipper/cloud"
    click CLI "https://github.com/flippercloud/flipper/tree/main/exe/flipper"
    click Gens "https://github.com/flippercloud/flipper/tree/main/lib/generators/flipper"
    click Examples "https://github.com/flippercloud/flipper/tree/main/examples/"
    click Bench "https://github.com/flippercloud/flipper/tree/main/benchmark/"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085,color:#004085;
    classDef adapters fill:#d4edda,stroke:#155724,color:#155724;
    classDef external fill:#f8d7da,stroke:#721c24,color:#721c24;
    classDef apiui fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef cloud fill:#d1ecf1,stroke:#0c5460,color:#0c5460;
```
