# tompave/fun_with_flags architecture

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

- Interactive diagram: https://gitdiagram.com/tompave/fun_with_flags
- Repository: https://github.com/tompave/fun_with_flags

## Overview

This project is an Elixir OTP application that implements a feature flag system. The core functionality revolves around toggling, querying, and managing feature flags in real time using different kinds of “gates” (e.g. boolean, actor, group, percentage-of-time, and percentage-of-actors). It provides a two-level storage model: a local ETS cache for quick lookups and a persistent store (either Redis or an Ecto-backed relational database) for durability and cross-node synchronization. In addition, it supports cache-busting notifications via PubSub, with adapters for Redis PubSub and Phoenix PubSub.

##### Main Components
- Application Core: Represent the FunWithFlags OTP application along with its supervision tree (see modules like FunWithFlags.Supervisor, FunWithFlags.Application). Indicate that this is the entry point and coordinator.
- API Layer: Show the exposed API functions (e.g. FunWithFlags.enabled?/2, enable/disable/clear) which serve as an interface for other parts of the host application.
- Persistence Adapter: Illustrate the two persistence strategies – one using Redis (via the Redix adapter) and one using Ecto (supporting PostgreSQL, MySQL, SQLite). Include components like:
- Persistent Store modules (under lib/fun_with_flags/store/persistent).
- Serializer submodules for translating internal data structures (under lib/fun_with_flags/store/serializer).
- Notification System: Include the PubSub component for distributed cache invalidation. Display the two notification modules available – one for Redis (lib/fun_with_flags/notifications/redis.ex) and another for Phoenix PubSub (lib/fun_with_flags/notifications/phoenix_pubsub.ex).
- Protocols: Represent the extensibility points via protocols (FunWithFlags.Actor and FunWithFlags.Group) which allow custom types to be used as “actors” or group identifiers. These define how entity IDs are computed and group membership is determined.
- Development & Benchmark Tools: Optionally, include components like the benchmarking scripts (in benchmarks/) that help assess performance.

##### Relationships and Interactions
- The API Layer calls into the core modules which check the ETS cache first. If required, they invoke persistence adapter operations (read/write flag definitions) to get the latest data.
- When a flag’s state is modified (e.g. toggled on/off, updated percentages, or cleared), the persistence adapter updates the store and then triggers a notification via the PubSub system.
- The Notification System then broadcasts a “cache bust” which causes the ETS cache in all nodes to refresh.
- The gate handlers determine the final enabled/disabled state by evaluating the rules stored for a flag, following the specific priority order (actor > group > boolean > percentage).
- The protocols ensure that custom actor or group data is converted appropriately for evaluation.

##### Architectural Patterns and Design Principles
- Layered Architecture: The system is clearly separated into concerns – API, caching, persistence, notifications, and gate evaluation logic.
- Adapter/Plug-in Pattern: The design supports multiple persistence and PubSub adapters. This abstraction makes the system flexible and easily extensible.
- Caching with Cache Invalidation: The use of ETS for caching, combined with PubSub notifications, is an important performance optimization concept reflected in the design.
- Use of Protocols: The protocol approach in Elixir gives you polymorphic behavior for handling various actor types.
- Supervision and Fault Tolerance: As an OTP app, starting and managing processes (using a supervision tree) is central to the design.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% API Layer
    API("API Layer"):::api

    %% FunWithFlags OTP Application Subgraph
    subgraph "FunWithFlags OTP Application"
        App("Application"):::core
        SUP("Supervisor"):::core
    end

    %% Gate Handlers
    Gate("Gate Handlers"):::gate

    %% Caching Layer
    Cache("Cache (ETS)"):::cache

    %% Persistence Adapter Subgraph
    subgraph "Persistence Adapter"
        EctoP("Persistent Store Ecto"):::persistence
        EctoSer("Serializer Ecto"):::persistence
        RedisP("Persistent Store Redis"):::persistence
        RedisSer("Serializer Redis"):::persistence
    end

    %% Notification System Subgraph
    subgraph "Notification System"
        RedisNotif("Redis PubSub"):::notification
        PhoenixNotif("Phoenix PubSub"):::notification
    end

    %% Protocols Subgraph
    subgraph "Protocols"
        ActorP("Actor Protocol"):::protocols
        GroupP("Group Protocol"):::protocols
    end

    %% Benchmark Tools
    Bench("Benchmark Tools"):::benchmark

    %% Connections
    API -->|"calls"| App
    App -->|"supervises"| SUP
    App -->|"initiates"| Gate
    Gate -->|"checks"| Cache
    Gate -->|"persists (Ecto)"| EctoP
    Gate -->|"persists (Redis)"| RedisP
    EctoP -->|"triggers"| RedisNotif
    RedisP -->|"triggers"| PhoenixNotif
    RedisNotif -->|"cache_bust"| Cache
    PhoenixNotif -->|"cache_bust"| Cache
    Gate -->|"evaluates via"| ActorP
    Gate -->|"evaluates via"| GroupP

    %% Benchmark Tools optional connection
    API -->|"benchmark"| Bench

    %% Click Events
    click API "https://github.com/tompave/fun_with_flags/blob/master/lib/fun_with_flags.ex"
    click App "https://github.com/tompave/fun_with_flags/blob/master/lib/fun_with_flags/application.ex"
    click SUP "https://github.com/tompave/fun_with_flags/blob/master/lib/fun_with_flags/supervisor.ex"
    click Gate "https://github.com/tompave/fun_with_flags/blob/master/lib/fun_with_flags/gate.ex"
    click EctoP "https://github.com/tompave/fun_with_flags/blob/master/lib/fun_with_flags/store/persistent/ecto.ex"
    click EctoSer "https://github.com/tompave/fun_with_flags/blob/master/lib/fun_with_flags/store/serializer/ecto.ex"
    click RedisP "https://github.com/tompave/fun_with_flags/blob/master/lib/fun_with_flags/store/persistent/redis.ex"
    click RedisSer "https://github.com/tompave/fun_with_flags/blob/master/lib/fun_with_flags/store/serializer/redis.ex"
    click Cache "https://github.com/tompave/fun_with_flags/blob/master/lib/fun_with_flags/store/cache.ex"
    click RedisNotif "https://github.com/tompave/fun_with_flags/blob/master/lib/fun_with_flags/notifications/redis.ex"
    click PhoenixNotif "https://github.com/tompave/fun_with_flags/blob/master/lib/fun_with_flags/notifications/phoenix_pubsub.ex"
    click ActorP "https://github.com/tompave/fun_with_flags/blob/master/lib/fun_with_flags/protocols/actor.ex"
    click GroupP "https://github.com/tompave/fun_with_flags/blob/master/lib/fun_with_flags/protocols/group.ex"
    click Bench "https://github.com/tompave/fun_with_flags/tree/master/benchmarks/"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef api fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef gate fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef persistence fill:#DDA0DD,stroke:#000,stroke-width:2px;
    classDef cache fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef notification fill:#FFA500,stroke:#000,stroke-width:2px;
    classDef protocols fill:#87CEFA,stroke:#000,stroke-width:2px;
    classDef benchmark fill:#E6E6FA,stroke:#000,stroke-width:2px;
```
