# vercel/flags architecture

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

- Interactive diagram: https://gitdiagram.com/vercel/flags
- Repository: https://github.com/vercel/flags

## Overview

##### Project Type and Purpose
- This is a monorepo that houses a feature flag system. The core functionality is implemented in the “flags” package (with its own README) and is extended via multiple adapter packages (e.g., adapter-edge-config, adapter-happykit, adapter-hypertune, adapter-launchdarkly, adapter-optimizely, adapter-split, adapter-statsig) that integrate with popular feature flag providers.
- The repository also contains various examples (for Next.js, SvelteKit, etc.) and extensive tests to illustrate integrations and usage across different platforms. This indicates that the project is meant to be used as an open-source library to integrate feature flags into different web frameworks.

##### Analyzing the File Structure
- Top-Level Directories: Notice the “packages” folder (which contains the core “flags” package as well as multiple “adapter-…” packages), “examples” (with subdirectories demonstrating concepts in different frameworks like Next.js and SvelteKit), “tests” (covering different test suites including e2e tests), and “tooling” (containing configurations for ESLint, TypeScript, etc.), along with CI/CD workflows in .github.
- Each adapter package follows a similar structure with source files, provider-specific implementations, test files, and configuration files. This hints at a modular and extensible design where the “flags” core is decoupled from provider-specific logic through well-defined adapters.
- The examples further reinforce how to integrate the library with popular frameworks and show real-world usage scenarios.

##### Guiding the Creation
a. Main Components:
- Core Flags Library: Represent the “flags” package as the central component that exposes APIs and core business logic.
- Adapter Modules: For each of the adapter packages (adapter-edge-config, adapter-happykit, etc.), create individual components that implement provider-specific logic. These should be shown as connected to the core flags library.
- External Services: Include representations for external feature flag providers (i.e., LaunchDarkly, Optimizely, Statsig, Split, etc.) that adapters communicate with.

b. Relationships and Interactions:

c. Architectural Patterns & Design Principles:
- Modular monorepo pattern where each package (core and adapters) is a separate module with its own configuration, tests, and documentation.
- Adapter pattern, which decouples the feature flag core logic from provider-specific implementations.
- If applicable, mention how the examples demonstrate integration points (e.g., middleware usage in Next.js or hooks in React) that follow framework-specific best practices.

d. Technologies, Frameworks, & Libraries:
- That the project is built with JavaScript/TypeScript.
- References to testing technologies (Vitest, Playwright, etc.) and CI/CD (GitHub Actions workflows).
- Optionally mention linting and formatting tools that help maintain code quality across the monorepo.

##### Elements
- Clear labels for each main component (Core Flags Library, each Adapter, Example Applications, Testing Infrastructure, External Feature Flag Providers).
- Core libraries (central component)
- Integration examples (distinct area representing client apps)
- Testing, CI/CD, and tooling (perhaps a lighter shade to indicate supporting components)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Integration Examples Subgraph
    subgraph "Integration Examples"
        nextjs1("Next.js (summer-sale)"):::integration
        nextjs2("Next.js (snippets)"):::integration
        sveltekit("SvelteKit Example"):::integration
    end

    %% Core System Subgraph
    subgraph "Core System"
        flags("Core Flags Library"):::core
        %% Adapter Modules Subgraph
        subgraph "Adapter Modules"
            adapterEdge("Edge Config"):::adapter
            adapterHappy("HappyKit"):::adapter
            adapterHyper("Hypertune"):::adapter
            adapterLD("LaunchDarkly"):::adapter
            adapterOpt("Optimizely"):::adapter
            adapterSplit("Split"):::adapter
            adapterStats("Statsig"):::adapter
        end
    end

    %% Testing and CI/CD
    testing("Testing Infrastructure"):::tooling
    cicd("CI/CD & Tooling"):::tooling

    %% External Providers Subgraph
    subgraph "External Providers"
        extEC("Edge Config Provider"):::external
        extHappy("HappyKit Provider"):::external
        extHyper("Hypertune Provider"):::external
        extLD("LaunchDarkly Provider"):::external
        extOpt("Optimizely Provider"):::external
        extSplit("Split Provider"):::external
        extStats("Statsig Provider"):::external
    end

    %% Connections from Integration Examples to Core
    nextjs1 -->|"calls"| flags
    nextjs2 -->|"calls"| flags
    sveltekit -->|"calls"| flags

    %% Connections from Core to Adapters
    flags -->|"delegates"| adapterEdge
    flags -->|"delegates"| adapterHappy
    flags -->|"delegates"| adapterHyper
    flags -->|"delegates"| adapterLD
    flags -->|"delegates"| adapterOpt
    flags -->|"delegates"| adapterSplit
    flags -->|"delegates"| adapterStats

    %% Connections from Adapters to External Providers
    adapterEdge -->|"communicates"| extEC
    adapterHappy -->|"communicates"| extHappy
    adapterHyper -->|"communicates"| extHyper
    adapterLD -->|"communicates"| extLD
    adapterOpt -->|"communicates"| extOpt
    adapterSplit -->|"communicates"| extSplit
    adapterStats -->|"communicates"| extStats

    %% Supporting Infrastructure connections
    testing -.->|"monitors"| flags
    cicd -.->|"deploys"| flags
    cicd -.->|"triggers"| testing

    %% Click Events
    click flags "https://github.com/vercel/flags/tree/main/packages/flags"
    click adapterEdge "https://github.com/vercel/flags/tree/main/packages/adapter-edge-config"
    click adapterHappy "https://github.com/vercel/flags/tree/main/packages/adapter-happykit"
    click adapterHyper "https://github.com/vercel/flags/tree/main/packages/adapter-hypertune"
    click adapterLD "https://github.com/vercel/flags/tree/main/packages/adapter-launchdarkly"
    click adapterOpt "https://github.com/vercel/flags/tree/main/packages/adapter-optimizely"
    click adapterSplit "https://github.com/vercel/flags/tree/main/packages/adapter-split"
    click adapterStats "https://github.com/vercel/flags/tree/main/packages/adapter-statsig"
    click nextjs1 "https://github.com/vercel/flags/tree/main/examples/summer-sale"
    click nextjs2 "https://github.com/vercel/flags/tree/main/examples/snippets"
    click sveltekit "https://github.com/vercel/flags/tree/main/examples/sveltekit-example"
    click testing "https://github.com/vercel/flags/tree/main/tests"
    click cicd "https://github.com/vercel/flags/tree/main/.github/workflows"

    %% Styles
    classDef core fill:#AED6F1,stroke:#5DADE2,stroke-width:2px;
    classDef adapter fill:#F9E79F,stroke:#F4D03F,stroke-width:2px;
    classDef integration fill:#ABEBC6,stroke:#58D68D,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#EC7063,stroke-width:2px;
    classDef tooling fill:#D7BDE2,stroke:#AF7AC5,stroke-width:2px;
```
