# nayanjaiswal1/flagforge-feature-flags architecture

> Architecture diagram of the GitHub repository nayanjaiswal1/flagforge-feature-flags, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nayanjaiswal1/flagforge-feature-flags
- Repository: https://github.com/nayanjaiswal1/flagforge-feature-flags

## Overview

FlagForge is a multi-tenant feature-flag control plane. Application code supplies a tenant/user/environment context to an evaluation engine, which loads definitions and tenant overrides, resolves targeting and rollout rules, and returns flag values. Django and FastAPI expose framework-specific evaluation and management; storage and cache backends are pluggable, while the CLI and YAML loader support configuration. The React package fetches resolved values for frontend use. Some integrations are documented but unsampled, so their internal wiring is shown only where the README or source index supports it.

Main entry points: [`src/flagforge/core/engine.py`](https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/core/engine.py) (Flag engine), [`src/flagforge/contrib/fastapi/storage.py`](https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/contrib/fastapi/storage.py) (Async SQL storage), [`src/flagforge/contrib/django/engine.py`](https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/contrib/django/engine.py) (Django integration), [`src/flagforge/contrib/django/storage.py`](https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/contrib/django/storage.py) (Django storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_evaluation["Evaluation core"]
  node_context["Evaluation context<br/>[context.py]"]
  node_definitions["Flag definitions<br/>[models.py]"]
  node_engine["Flag engine<br/>[engine.py]"]
  node_resolver["Rule resolver<br/>[resolver.py]"]
end

subgraph group_backends["Storage and cache"]
  node_storage_api["Storage interfaces<br/>[base.py]"]
  node_memory_store[("Memory storage<br/>[memory.py]")]
  node_django_store[("Django storage<br/>[storage.py]")]
  node_async_store[("Async SQL storage<br/>[storage.py]")]
  node_cache["Cache backends"]
end

subgraph group_integrations["Framework integrations"]
  node_django_models[("Django flag models<br/>[models.py]")]
  node_async_models[("Async ORM models<br/>[models.py]")]
  node_django_app["Django integration<br/>[engine.py]"]
  node_django_api["Django REST API<br/>[views.py]"]
  node_django_helpers["Django UI helpers"]
  node_fastapi_context["FastAPI context<br/>[context.py]"]
  node_fastapi_router["FastAPI routes<br/>[router.py]"]
  node_fastapi_dependencies["FastAPI dependencies<br/>[dependencies.py]"]
  node_fastapi_lifespan["FastAPI lifespan<br/>[lifespan.py]"]
end

subgraph group_frontend["Frontend client"]
  node_react_provider["React provider<br/>[context.tsx]"]
  node_react_components["React components<br/>[components.tsx]"]
end

subgraph group_operations["Flag operations"]
  node_yaml_loader["YAML loader<br/>[yaml_loader.py]"]
  node_cli["CLI management<br/>[main.py]"]
end

node_app(("Application"))
node_http_api["Flag API"]
node_database[("Configured database")]

node_app -->|"builds context"| node_context
node_app -->|"evaluates flags"| node_engine
node_engine -->|"loads flags"| node_storage_api
node_engine -->|"resolves rules"| node_resolver
node_engine -->|"checks cache"| node_cache
node_engine -->|"uses context"| node_context
node_engine -->|"evaluates definitions"| node_definitions
node_memory_store -->|"implements"| node_storage_api
node_django_store -->|"implements"| node_storage_api
node_django_store -->|"reads and writes"| node_django_models
node_async_store -->|"implements"| node_storage_api
node_async_store -->|"queries"| node_async_models
node_django_app -->|"configures"| node_django_store
node_django_app -->|"creates engine"| node_engine
node_django_app -->|"configures cache"| node_cache
node_django_api -.->|"evaluates flags"| node_django_app
node_django_helpers -->|"uses evaluation"| node_django_app
node_fastapi_context -->|"creates context"| node_context
node_fastapi_router -->|"builds context"| node_fastapi_context
node_fastapi_router -->|"evaluates flags"| node_engine
node_fastapi_router -->|"manages definitions"| node_async_store
node_fastapi_dependencies -->|"extracts context"| node_fastapi_context
node_fastapi_dependencies -->|"provides engine"| node_engine
node_fastapi_dependencies -->|"provides storage"| node_async_store
node_fastapi_lifespan -.->|"initializes storage"| node_async_store
node_yaml_loader -->|"loads definitions"| node_definitions
node_cli -->|"loads configuration"| node_yaml_loader
node_cli -->|"manages Django flags"| node_django_store
node_react_provider -->|"fetches flags"| node_http_api
node_http_api -->|"served by"| node_django_api
node_http_api -->|"served by"| node_fastapi_router
node_react_components -->|"consumes context"| node_react_provider
node_database -.->|"persists flags"| node_django_store
node_database -->|"persists flags"| node_async_store

click node_context "https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/core/context.py"
click node_definitions "https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/core/models.py"
click node_engine "https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/core/engine.py"
click node_resolver "https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/core/resolver.py"
click node_storage_api "https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/storage/base.py"
click node_memory_store "https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/storage/memory.py"
click node_yaml_loader "https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/storage/yaml_loader.py"
click node_django_store "https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/contrib/django/storage.py"
click node_django_models "https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/contrib/django/models.py"
click node_async_store "https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/contrib/fastapi/storage.py"
click node_async_models "https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/contrib/fastapi/models.py"
click node_cache "https://github.com/nayanjaiswal1/flagforge-feature-flags/tree/master/src/flagforge/cache"
click node_django_app "https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/contrib/django/engine.py"
click node_django_api "https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/contrib/django/views.py"
click node_django_helpers "https://github.com/nayanjaiswal1/flagforge-feature-flags/tree/master/src/flagforge/contrib/django"
click node_fastapi_context "https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/contrib/fastapi/context.py"
click node_fastapi_router "https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/contrib/fastapi/router.py"
click node_fastapi_dependencies "https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/contrib/fastapi/dependencies.py"
click node_fastapi_lifespan "https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/contrib/fastapi/lifespan.py"
click node_cli "https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/cli/main.py"
click node_react_provider "https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/packages/flagforge-react/src/context.tsx"
click node_react_components "https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/packages/flagforge-react/src/components.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_context,node_definitions,node_engine,node_resolver toneBlue
class node_storage_api,node_memory_store,node_django_store,node_async_store,node_cache,node_database toneAmber
class node_django_models,node_async_models,node_django_app,node_django_api,node_django_helpers,node_fastapi_context,node_fastapi_router,node_fastapi_dependencies,node_fastapi_lifespan,node_http_api toneMint
class node_react_provider,node_react_components toneRose
class node_yaml_loader,node_cli,node_app toneIndigo
```

## Components

### Evaluation core

- [Evaluation context](https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/core/context.py): `src/flagforge/core/context.py`
- [Flag definitions](https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/core/models.py): `src/flagforge/core/models.py`
- [Flag engine](https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/core/engine.py): `src/flagforge/core/engine.py`
- [Rule resolver](https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/core/resolver.py): `src/flagforge/core/resolver.py`

### Storage and cache

- [Storage interfaces](https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/storage/base.py): `src/flagforge/storage/base.py`
- [Memory storage](https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/storage/memory.py): `src/flagforge/storage/memory.py`
- [Django storage](https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/contrib/django/storage.py): `src/flagforge/contrib/django/storage.py`
- [Async SQL storage](https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/contrib/fastapi/storage.py): `src/flagforge/contrib/fastapi/storage.py`
- [Cache backends](https://github.com/nayanjaiswal1/flagforge-feature-flags/tree/master/src/flagforge/cache): `src/flagforge/cache`

### Framework integrations

- [Django flag models](https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/contrib/django/models.py): `src/flagforge/contrib/django/models.py`
- [Async ORM models](https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/contrib/fastapi/models.py): `src/flagforge/contrib/fastapi/models.py`
- [Django integration](https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/contrib/django/engine.py): `src/flagforge/contrib/django/engine.py`
- [Django REST API](https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/contrib/django/views.py): `src/flagforge/contrib/django/views.py`
- [Django UI helpers](https://github.com/nayanjaiswal1/flagforge-feature-flags/tree/master/src/flagforge/contrib/django): `src/flagforge/contrib/django`
- [FastAPI context](https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/contrib/fastapi/context.py): `src/flagforge/contrib/fastapi/context.py`
- [FastAPI routes](https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/contrib/fastapi/router.py): `src/flagforge/contrib/fastapi/router.py`
- [FastAPI dependencies](https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/contrib/fastapi/dependencies.py): `src/flagforge/contrib/fastapi/dependencies.py`
- [FastAPI lifespan](https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/contrib/fastapi/lifespan.py): `src/flagforge/contrib/fastapi/lifespan.py`

### Frontend client

- [React provider](https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/packages/flagforge-react/src/context.tsx): `packages/flagforge-react/src/context.tsx`
- [React components](https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/packages/flagforge-react/src/components.tsx): `packages/flagforge-react/src/components.tsx`

### Flag operations

- [YAML loader](https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/storage/yaml_loader.py): `src/flagforge/storage/yaml_loader.py`
- [CLI management](https://github.com/nayanjaiswal1/flagforge-feature-flags/blob/master/src/flagforge/cli/main.py): `src/flagforge/cli/main.py`

### Other components

- **Application**
- **Flag API**
- **Configured database**

## Connections

- Application → Evaluation context: builds context (evidence: `README.md`)
- Application → Flag engine: evaluates flags (evidence: `README.md`)
- Flag engine → Storage interfaces: loads flags (evidence: `src/flagforge/core/engine.py`)
- Flag engine → Rule resolver: resolves rules (evidence: `src/flagforge/core/engine.py`)
- Flag engine → Cache backends: checks cache (evidence: `src/flagforge/core/engine.py`)
- Flag engine → Evaluation context: uses context (evidence: `src/flagforge/core/engine.py`)
- Flag engine → Flag definitions: evaluates definitions (evidence: `src/flagforge/core/engine.py`)
- Memory storage → Storage interfaces: implements (evidence: `src/flagforge/storage/memory.py`)
- Django storage → Storage interfaces: implements (evidence: `src/flagforge/contrib/django/storage.py`)
- Django storage → Django flag models: reads and writes (evidence: `src/flagforge/contrib/django/storage.py`)
- Async SQL storage → Storage interfaces: implements (evidence: `src/flagforge/contrib/fastapi/storage.py`)
- Async SQL storage → Async ORM models: queries (evidence: `src/flagforge/contrib/fastapi/storage.py`)
- Django integration → Django storage: configures (evidence: `src/flagforge/contrib/django/engine.py`)
- Django integration → Flag engine: creates engine (evidence: `src/flagforge/contrib/django/engine.py`)
- Django integration → Cache backends: configures cache (evidence: `src/flagforge/contrib/django/engine.py`)
- Django REST API → Django integration: evaluates flags
- Django UI helpers → Django integration: uses evaluation (evidence: `src/flagforge/contrib/django/templatetags/flagforge.py`)
- FastAPI context → Evaluation context: creates context (evidence: `src/flagforge/contrib/fastapi/context.py`)
- FastAPI routes → FastAPI context: builds context (evidence: `src/flagforge/contrib/fastapi/router.py`)
- FastAPI routes → Flag engine: evaluates flags (evidence: `src/flagforge/contrib/fastapi/router.py`)
- FastAPI routes → Async SQL storage: manages definitions (evidence: `src/flagforge/contrib/fastapi/router.py`)
- FastAPI dependencies → FastAPI context: extracts context (evidence: `src/flagforge/contrib/fastapi/dependencies.py`)
- FastAPI dependencies → Flag engine: provides engine (evidence: `src/flagforge/contrib/fastapi/dependencies.py`)
- FastAPI dependencies → Async SQL storage: provides storage (evidence: `src/flagforge/contrib/fastapi/dependencies.py`)
- FastAPI lifespan → Async SQL storage: initializes storage
- YAML loader → Flag definitions: loads definitions (evidence: `src/flagforge/storage/yaml_loader.py`)
- CLI management → YAML loader: loads configuration (evidence: `src/flagforge/cli/main.py`)
- CLI management → Django storage: manages Django flags (evidence: `src/flagforge/cli/main.py`)
- React provider → Flag API: fetches flags (evidence: `packages/flagforge-react/src/context.tsx`)
- Flag API → Django REST API: served by (evidence: `README.md`)
- Flag API → FastAPI routes: served by (evidence: `src/flagforge/contrib/fastapi/router.py`)
- React components → React provider: consumes context (evidence: `packages/flagforge-react/src/components.tsx`)
- Configured database → Django storage: persists flags
- Configured database → Async SQL storage: persists flags (evidence: `src/flagforge/contrib/fastapi/storage.py`)
