# flipt-io/flipt architecture

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

- Interactive diagram: https://gitdiagram.com/flipt-io/flipt
- Repository: https://github.com/flipt-io/flipt

## Overview

Based on our analysis of the file tree and README, this project is Flipt – an enterprise-ready feature management system that supports GitOps workflows, offering feature-flag evaluation via GRPC and REST, a modern UI, comprehensive audit logging, and integrations with various databases, caches, and external monitoring systems. The project is mainly written in Go (for the backend, various internal packages, server components, authentication and evaluation modules, storage integrations, etc.) and TypeScript/React (for the UI in the “ui” directory). There are also several examples demonstrating integrations, testing, and configuration for different storage backends and authentication methods.

##### Main Components
- Backend Service: This is the core of Flipt, implemented largely in Go. It includes submodules for feature flag evaluation, audit logging, authentication, authorization, and rule/rollout management. Identify separate packages such as “internal/server”, “internal/config”, “internal/metrics”, “internal/cache”, “internal/storage”, and “internal/tracing” that work together to provide the server’s functionality.
- API Interfaces: Indicate dual API layers – the GRPC interface (documented under the “rpc” directories and GRPC-related workflows) and the REST/HTTP API that also powers the UI.
- UI Component: The “ui” directory contains the front-end application (written in React/TypeScript) that communicates with the API layer. It covers both the dashboard and administration consoles.
- Storage Backends: Flipt supports multiple storage solutions (MySQL, PostgreSQL, CockroachDB, SQLite, LibSQL, Redis, object storage via GitOps, Filesystem, OCI, etc.). Represent these as separate database or storage modules that interface with the backend.
- External Integrations: This includes integration with Prometheus, OpenTelemetry, and third-party authentication systems (OIDC, JWT, OAuth, etc.) as shown in both configuration and example directories.
- Caching Layer: Internal caching is done using in-memory caches and via Redis (as seen under “internal/cache” with subdirectories for memory and redis).

##### Relationships and Data Flows
- The backend uses an evaluation module and a rules engine to process feature flag queries. This module in turn interfaces with the storage backends via SQL or Filesystem modules.
- Audit logging, authentication, and authorization modules operate as middleware – intercepting incoming requests for validation (using tokens, OIDC flows, GitHub methods, etc.) and passing verified requests to the evaluation logic.
- The caching layer sits between the backend and the data store, reducing latency for flag evaluations. Indicate directional relationships where the server writes to/reads from these caches.

##### Architectural Patterns and Design Principles
- Modular Design: Emphasize the separation of concerns: configuration, evaluation, caching, storage, logging, and integrations are organized as independent packages which can be diagrammed as discrete subsystems.
- API Gateway Pattern: The dual API (REST and GRPC) is used to decouple the client-facing interfaces from the core evaluation logic.
- GitOps/Declarative Storage: Highlight the support for Git and filesystem as a configuration source—the “internal/gitfs” package is an example.
- Extensibility and Pluggability: Note that Flipt is designed to allow new storage backends, caching strategies, and integrations to be added with minimal disruption.

##### Relevant Technologies and Frameworks
- Programming language: Go (server side) and TypeScript/React (UI).
- Communication protocols: GRPC (binary, low-latency) and REST (HTTP/JSON) APIs.
- Storage: SQL databases (MySQL, Postgres, CockroachDB, SQLite) and declarative storage backends (GitOps enabled systems, filesystems, object storage, OCI).
- Caching: In-memory caches and Redis.
- External monitoring and telemetry: Prometheus for metrics and OpenTelemetry for tracing.
- Authentication: Methods include HTTPS, OIDC, JWT, OAuth, Kubernetes Service Token, and API Token, integrated via internal auth modules.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Frontend"
        UI["Frontend UI (React/TypeScript)"]:::ui
    end

    subgraph "API Layer"
        REST["REST API"]:::api
        GRPC["GRPC API"]:::api
    end

    subgraph "Backend Services"
        Core["Flipt Core (cmd/flipt)"]:::backend
        Server["Server Module (internal/server)"]:::backend
        Audit["Audit Logging (internal/server/audit)"]:::backend
        Auth["Authentication/Authorization (internal/server/authn)"]:::backend
        Metrics["Metrics (internal/metrics)"]:::backend
        Tracing["Tracing (internal/tracing)"]:::backend
    end

    subgraph "Supporting Layers"
        Storage["Storage Backends (internal/storage, config/migrations)"]:::database
        Cache["Caching Layer (internal/cache)"]:::cache
    end

    subgraph "External Integrations"
        ExtAuth["External Auth (internal/config/authentication)"]:::external
        Telemetry["Telemetry (internal/telemetry)"]:::external
    end

    UI -->|"HTTP_call"| REST
    UI -->|"GRPC_call"| GRPC

    REST -->|"request"| Core
    GRPC -->|"request"| Core

    Core -->|"internal_call"| Server
    Core -->|"logs"| Audit
    Core -->|"validates"| Auth
    Core -->|"collects"| Metrics
    Core -->|"traces"| Tracing
    Core -->|"cache_IO"| Cache
    Core -->|"storage_IO"| Storage

    Auth -->|"fetches"| ExtAuth
    Metrics -->|"sends_data"| Telemetry
    Tracing -->|"sends_traces"| Telemetry

    %% Click Events
    click UI "https://github.com/flipt-io/flipt/tree/main/ui"
    click REST "https://github.com/flipt-io/flipt/tree/main/internal/cmd/http"
    click GRPC "https://github.com/flipt-io/flipt/tree/main/rpc/flipt"
    click GRPC "https://github.com/flipt-io/flipt/tree/main/internal/cmd/grpc"
    click Core "https://github.com/flipt-io/flipt/tree/main/cmd/flipt"
    click Server "https://github.com/flipt-io/flipt/tree/main/internal/server"
    click Audit "https://github.com/flipt-io/flipt/tree/main/internal/server/audit"
    click Auth "https://github.com/flipt-io/flipt/tree/main/internal/server/authn"
    click ExtAuth "https://github.com/flipt-io/flipt/tree/main/internal/config/authentication"
    click Storage "https://github.com/flipt-io/flipt/tree/main/internal/storage"
    click Storage "https://github.com/flipt-io/flipt/tree/main/config/migrations"
    click Cache "https://github.com/flipt-io/flipt/tree/main/internal/cache"
    click Metrics "https://github.com/flipt-io/flipt/tree/main/internal/metrics"
    click Tracing "https://github.com/flipt-io/flipt/tree/main/internal/tracing"
    click Telemetry "https://github.com/flipt-io/flipt/tree/main/internal/telemetry"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef api fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef backend fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef database fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef cache fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef external fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
```
