# thomaspoignant/go-feature-flag architecture

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

- Interactive diagram: https://gitdiagram.com/thomaspoignant/go-feature-flag
- Repository: https://github.com/thomaspoignant/go-feature-flag

## Overview

GO Feature Flag is a self-hosted feature-flag service and SDK ecosystem. Its principal workflow is an application requesting a flag evaluation from the relay proxy, which routes the request to a flagset client and returns a result evaluated against configured flags and user context. The Go module also supports in-process evaluation; the README describes OpenFeature support across languages. The graph includes configuration retrieval, evaluation, data export, notifications, and streaming updates. Some subsystem links reflect documented capabilities and tree structure; unsampled implementation details are not asserted.

Main entry points: [`cmd/relayproxy/service/flagset_manager.go`](https://github.com/thomaspoignant/go-feature-flag/blob/main/cmd/relayproxy/service/flagset_manager.go) (Flagset manager), [`cmd/relayproxy/api/server.go`](https://github.com/thomaspoignant/go-feature-flag/blob/main/cmd/relayproxy/api/server.go) (HTTP API), [`cmd/relayproxy/main.go`](https://github.com/thomaspoignant/go-feature-flag/blob/main/cmd/relayproxy/main.go) (Relay proxy), [`cmd/relayproxy/api/routes_goff.go`](https://github.com/thomaspoignant/go-feature-flag/blob/main/cmd/relayproxy/api/routes_goff.go) (API routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Relay runtime"]
  node_proxy["Relay proxy<br/>[main.go]"]
  node_api["HTTP API<br/>[server.go]"]
  node_routes["API routes<br/>[routes_goff.go]"]
  node_eval_handler["Evaluation handlers<br/>[flag_eval.go]"]
  node_ofrep_handler["OFREP handler<br/>[evaluate.go]"]
  node_flagsets["Flagset manager<br/>[flagset_manager.go]"]
  node_config["Proxy configuration<br/>[config.go]"]
  node_streams["Streaming updates"]
end

subgraph group_flags["Flag configuration"]
  node_retriever_manager["Retriever manager<br/>[manager.go]"]
  node_retriever_adapters["Storage retrievers"]
  node_cache[("Flag cache<br/>[cache_manager.go]")]
  node_flag_model["Flag definitions<br/>[flag.go]"]
end

subgraph group_evaluation["Evaluation"]
  node_context["Evaluation context<br/>[context.go]"]
  node_core_eval["Core evaluation<br/>[evaluation.go]"]
  node_variation["Variation result"]
end

subgraph group_integrations["Data integrations"]
  node_export_manager["Export manager<br/>[manager.go]"]
  node_export_adapters["Export destinations"]
  node_notifiers["Change notifiers<br/>[notifier.go]"]
end

subgraph group_clients["SDK ecosystem"]
  node_go_sdk["Go SDK<br/>[feature_flag.go]"]
  node_openfeature["OpenFeature providers"]
end

node_app(("Application"))
node_external_store[("Configuration stores")]
node_data_sink[("Export destinations")]

node_app -->|"requests flags"| node_api
node_proxy -->|"loads settings"| node_config
node_proxy -->|"initializes"| node_flagsets
node_proxy -->|"starts server"| node_api
node_api -->|"registers routes"| node_routes
node_routes -->|"dispatches evaluation"| node_eval_handler
node_routes -->|"dispatches OFREP"| node_ofrep_handler
node_flagsets -->|"creates clients"| node_retriever_manager
node_retriever_manager -->|"retrieves flags"| node_retriever_adapters
node_retriever_manager -->|"updates cache"| node_cache
node_retriever_adapters -.->|"loads configuration"| node_external_store
node_cache -->|"holds flags"| node_flag_model
node_eval_handler -->|"selects flagset"| node_flagsets
node_ofrep_handler -->|"selects flagset"| node_flagsets
node_flagsets -->|"manages clients"| node_go_sdk
node_go_sdk -->|"evaluates flags"| node_core_eval
node_core_eval -->|"uses targeting context"| node_context
node_core_eval -->|"produces result"| node_variation
node_variation -->|"returns evaluation"| node_eval_handler
node_variation -->|"returns evaluation"| node_ofrep_handler
node_go_sdk -->|"records events"| node_export_manager
node_export_manager -->|"dispatches events"| node_export_adapters
node_export_adapters -.->|"exports data"| node_data_sink
node_cache -->|"announces changes"| node_notifiers
node_notifiers -.->|"notifies clients"| node_streams
node_openfeature -.->|"uses relay API"| node_api

click node_proxy "https://github.com/thomaspoignant/go-feature-flag/blob/main/cmd/relayproxy/main.go"
click node_api "https://github.com/thomaspoignant/go-feature-flag/blob/main/cmd/relayproxy/api/server.go"
click node_routes "https://github.com/thomaspoignant/go-feature-flag/blob/main/cmd/relayproxy/api/routes_goff.go"
click node_eval_handler "https://github.com/thomaspoignant/go-feature-flag/blob/main/cmd/relayproxy/handler/goff/flag_eval.go"
click node_ofrep_handler "https://github.com/thomaspoignant/go-feature-flag/blob/main/cmd/relayproxy/handler/ofrep/evaluate.go"
click node_flagsets "https://github.com/thomaspoignant/go-feature-flag/blob/main/cmd/relayproxy/service/flagset_manager.go"
click node_config "https://github.com/thomaspoignant/go-feature-flag/blob/main/cmd/relayproxy/config/config.go"
click node_retriever_manager "https://github.com/thomaspoignant/go-feature-flag/blob/main/retriever/manager.go"
click node_retriever_adapters "https://github.com/thomaspoignant/go-feature-flag/tree/main/retriever"
click node_cache "https://github.com/thomaspoignant/go-feature-flag/blob/main/internal/cache/cache_manager.go"
click node_flag_model "https://github.com/thomaspoignant/go-feature-flag/blob/main/modules/core/flag/flag.go"
click node_context "https://github.com/thomaspoignant/go-feature-flag/blob/main/modules/core/ffcontext/context.go"
click node_core_eval "https://github.com/thomaspoignant/go-feature-flag/blob/main/modules/core/evaluation/evaluation.go"
click node_variation "https://github.com/thomaspoignant/go-feature-flag/blob/main/modules/core/model/variation_result.go"
click node_go_sdk "https://github.com/thomaspoignant/go-feature-flag/blob/main/feature_flag.go"
click node_openfeature "https://github.com/thomaspoignant/go-feature-flag/tree/main/openfeature/providers"
click node_export_manager "https://github.com/thomaspoignant/go-feature-flag/blob/main/exporter/manager.go"
click node_export_adapters "https://github.com/thomaspoignant/go-feature-flag/tree/main/exporter"
click node_notifiers "https://github.com/thomaspoignant/go-feature-flag/blob/main/notifier/notifier.go"
click node_streams "https://github.com/thomaspoignant/go-feature-flag/tree/main/cmd/relayproxy/service/stream"

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_proxy,node_api,node_routes,node_eval_handler,node_ofrep_handler,node_flagsets,node_config,node_streams toneBlue
class node_retriever_manager,node_retriever_adapters,node_cache,node_flag_model,node_external_store,node_data_sink toneAmber
class node_context,node_core_eval,node_variation toneMint
class node_export_manager,node_export_adapters,node_notifiers toneRose
class node_go_sdk,node_openfeature,node_app toneIndigo
```

## Components

### Relay runtime

- [Relay proxy](https://github.com/thomaspoignant/go-feature-flag/blob/main/cmd/relayproxy/main.go): `cmd/relayproxy/main.go`
- [HTTP API](https://github.com/thomaspoignant/go-feature-flag/blob/main/cmd/relayproxy/api/server.go): `cmd/relayproxy/api/server.go`
- [API routes](https://github.com/thomaspoignant/go-feature-flag/blob/main/cmd/relayproxy/api/routes_goff.go): `cmd/relayproxy/api/routes_goff.go`
- [Evaluation handlers](https://github.com/thomaspoignant/go-feature-flag/blob/main/cmd/relayproxy/handler/goff/flag_eval.go): `cmd/relayproxy/handler/goff/flag_eval.go`
- [OFREP handler](https://github.com/thomaspoignant/go-feature-flag/blob/main/cmd/relayproxy/handler/ofrep/evaluate.go): `cmd/relayproxy/handler/ofrep/evaluate.go`
- [Flagset manager](https://github.com/thomaspoignant/go-feature-flag/blob/main/cmd/relayproxy/service/flagset_manager.go): `cmd/relayproxy/service/flagset_manager.go`
- [Proxy configuration](https://github.com/thomaspoignant/go-feature-flag/blob/main/cmd/relayproxy/config/config.go): `cmd/relayproxy/config/config.go`
- [Streaming updates](https://github.com/thomaspoignant/go-feature-flag/tree/main/cmd/relayproxy/service/stream): `cmd/relayproxy/service/stream`

### Flag configuration

- [Retriever manager](https://github.com/thomaspoignant/go-feature-flag/blob/main/retriever/manager.go): `retriever/manager.go`
- [Storage retrievers](https://github.com/thomaspoignant/go-feature-flag/tree/main/retriever): `retriever`
- [Flag cache](https://github.com/thomaspoignant/go-feature-flag/blob/main/internal/cache/cache_manager.go): `internal/cache/cache_manager.go`
- [Flag definitions](https://github.com/thomaspoignant/go-feature-flag/blob/main/modules/core/flag/flag.go): `modules/core/flag/flag.go`

### Evaluation

- [Evaluation context](https://github.com/thomaspoignant/go-feature-flag/blob/main/modules/core/ffcontext/context.go): `modules/core/ffcontext/context.go`
- [Core evaluation](https://github.com/thomaspoignant/go-feature-flag/blob/main/modules/core/evaluation/evaluation.go): `modules/core/evaluation/evaluation.go`
- [Variation result](https://github.com/thomaspoignant/go-feature-flag/blob/main/modules/core/model/variation_result.go): `modules/core/model/variation_result.go`

### Data integrations

- [Export manager](https://github.com/thomaspoignant/go-feature-flag/blob/main/exporter/manager.go): `exporter/manager.go`
- [Export destinations](https://github.com/thomaspoignant/go-feature-flag/tree/main/exporter): `exporter`
- [Change notifiers](https://github.com/thomaspoignant/go-feature-flag/blob/main/notifier/notifier.go): `notifier/notifier.go`

### SDK ecosystem

- [Go SDK](https://github.com/thomaspoignant/go-feature-flag/blob/main/feature_flag.go): `feature_flag.go`
- [OpenFeature providers](https://github.com/thomaspoignant/go-feature-flag/tree/main/openfeature/providers): `openfeature/providers`

### Other components

- **Application**
- **Configuration stores**
- **Export destinations**

## Connections

- Application → HTTP API: requests flags
- Relay proxy → Proxy configuration: loads settings
- Relay proxy → Flagset manager: initializes
- Relay proxy → HTTP API: starts server
- HTTP API → API routes: registers routes
- API routes → Evaluation handlers: dispatches evaluation
- API routes → OFREP handler: dispatches OFREP
- Flagset manager → Retriever manager: creates clients
- Retriever manager → Storage retrievers: retrieves flags
- Retriever manager → Flag cache: updates cache
- Storage retrievers → Configuration stores: loads configuration
- Flag cache → Flag definitions: holds flags
- Evaluation handlers → Flagset manager: selects flagset
- OFREP handler → Flagset manager: selects flagset
- Flagset manager → Go SDK: manages clients
- Go SDK → Core evaluation: evaluates flags
- Core evaluation → Evaluation context: uses targeting context
- Core evaluation → Variation result: produces result
- Variation result → Evaluation handlers: returns evaluation
- Variation result → OFREP handler: returns evaluation
- Go SDK → Export manager: records events
- Export manager → Export destinations: dispatches events
- Export destinations → Export destinations: exports data
- Flag cache → Change notifiers: announces changes
- Change notifiers → Streaming updates: notifies clients
- OpenFeature providers → HTTP API: uses relay API