# featurehub-io/featurehub architecture

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

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

## Overview

##### Project type and purpose
- This repo implements FeatureHub, a Cloud-Native, open-source feature-flagging and experimentation platform.
- It’s a full-stack, microservices-based system:
- Frontends (admin console GUI and CLI) for users
- A set of backend services (Management Repository, cache service “Dacha,” streaming “Edge” service, event processors, messaging, security)
- Persistent storage (relational DB via Ebean/SQL modules) and event bus (NATS/Google PubSub/Kinesis adapters)
- SDKs and end-to-end test layers

##### File structure
- Top-level directories:
- adks – Admin SDK examples & E2E SDK for testing
- admin-frontend – Dart/Flutter web admin console + CLI layer + code-gen layers
- backend – dozens of maven sub-modules:
­– common-db, common-web (shared frameworks)
­– mr-api, mr (Management Repository REST service & API definitions)
­– dacha, dacha2 (cache service listening to events and exposing cache API)
­– edge-*, edge-full, edge-rest (services exposing feature-state to client SDKs via REST/SSE)
­– eventing-* (cloud-events, pubsub, kinesis, nats adapters)
­– messaging-delivery, webhook-common, security-oauth, security-saml (auxiliary microservices)
­– mr-db-* (DB API, Ebean migrations, SQL implementations, services)
­– mr-eventing-* (glue between MR and event bus)
­– party-server (lightweight in-memory server for demos)
- infra – Pulumi bucket API hosting, S3 metadata
- pipeline – CI/CD definitions (Cloudbuild, Dockerfiles, Helm charts under pipeline/deploy)
- e2e – end-to-end test harness in Dart
- docs – Antora-driven documentation site
- Configuration & build files: global pom.xml, many module-level pom.xml, Dockerfiles, shell scripts

##### Architecture insights from README
- Core services:
a. Management Repository (“mr”) – the source-of-truth, REST API for feature metadata, user & environment management
b. Dacha – event-driven cache service maintaining feature state snapshots
c. Edge – streaming/REST service serving SDK clients in real time via SSE or HTTP
- Event-driven: MR publishes change events to an event bus; Dacha, Edge, “mr-eventing” consume and process them.
- Supports multiple pub/sub backends (NATS, Google PubSub, Kinesis, CloudEvents).
- DB layers: API definitions (mr-db-api), SQL implementations (mr-db-sql), migrations (mr-db-ebean), services (mr-db-services).

##### How to model this
- Frontend layer:
- Admin Console (Flutter web)
- CLI (Dart/featurehub-cli)
- Admin SDKs (adks/e2e-sdk)
- API layer:
- MR-API (OpenAPI) – code-gen module under backend/mr-api
- Backend services:
- Management Repository service (“mr”)
- Dacha cache service
- Edge streaming/REST service
- Event processors (mr-eventing, eventing-*, webhook-feature-update, messaging-delivery)
- Security adapters (security-oauth, security-saml)
- Data stores & bus:
- Relational Database (Ebean via mr-db-ebean)
- Pub/Sub/Event Bus (NATS, PubSub, Kinesis)
- Clients & SDKs:
- Edge SDKs (JavaScript, Android, iOS, .NET, etc.)
- Custom apps using EdgeFeatureHubConfig
- Infrastructure & CI/CD:
- Pulumi S3 API bucket (infra/api-bucket)
- Docker/K8s Helm (pipeline/deploy)
- CI pipelines (pipeline/app-build-pipeline, .github/workflows)
b. Relationships & data flows:
1. Admin Console or CLI → MR service (HTTP REST) → DB
2. MR service → publishes change events to Event Bus
3. Dacha & mr-eventing consume Event Bus → update in-memory feature snapshots
4. Edge service consumes Dacha snapshots & Event Bus → serves feature states to SDK clients via SSE/REST
5. SDK clients ←→ Edge service (continuous streaming)
6. Event processors & webhooks → subscribe to change events for analytics or external notifications
7. Security services integrate MR & Frontend with OAuth/SAML providers
8. CI/CD pipelines & Pulumi deploy services into Kubernetes or Docker
c. Architectural patterns & principles:
- Microservices (single responsibility per module)
- Event-driven pub/sub for scaling & decoupling
- Hexagonal modules: API definitions separate from implementations
- Shared “common-db” and “common-web” libraries to enforce consistency
- Modular DB API vs. SQL implementation to allow multiple DB backends
d. Technologies & frameworks:
- Java/Kotlin, Maven, Jersey + Grizzly for REST services
- Ebean ORM for DB migrations & access
- CloudEvents + NATS/Google PubSub/Kinesis connectors
- Dart/Flutter for web UI and CLI
- Docker, Kubernetes (Helm), Pulumi for infra
- Cucumber/Gherkin for E2E tests

##### Detail
- Every service boundary and data store.
- Code-generation modules (mr-api, dacha-api, edge-api) feeding into client/stub code.
- Don’t oversimplify: retaining all major modules (mr-eventing, eventing-*, security-*) helps maintain clarity on extensibility.
- CI/CD and documentation delivery pipelines as part of the deployment flow.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        AdminConsole["Admin Console (Flutter Web)"]:::frontend
        CLI["CLI (Dart CLI)"]:::frontend
        AdminSDK["Admin SDK / E2E SDK"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        MRAPI["MR-API (OpenAPI)"]:::api
    end

    %% Backend Services
    subgraph "Backend Services"
        direction TB
        MRService["Management Repository Service\nJava/Kotlin (Jersey)"]:::service
        CommonLibs["Common Libs\ncommon-web & common-db"]:::service
        DachaV1["Dacha Cache v1"]:::cache
        DachaV2["Dacha Cache v2"]:::cache
        EdgeFull["Edge Full (SSE/Streaming)"]:::cache
        EdgeREST["Edge REST (HTTP)"]:::cache
        EdgeAPI["Edge API Definitions"]:::service
        EdgeCommon["Edge Common Logic"]:::service
        EventCE["CloudEvents Adapter"]:::service
        EventGCP["Google PubSub Adapter"]:::service
        EventNATS["NATS Adapter"]:::service
        EventKinesis["Kinesis Adapter"]:::service
        MREventCommon["MR-Eventing Common Utils"]:::service
        MREvent["MR-Eventing Processor"]:::service
        MREventNATS["MR-Eventing NATS"]:::service
        Messaging["Messaging Delivery"]:::service
        WebhookAPI["Webhook API"]:::service
        WebhookCommon["Webhook Common Utils"]:::service
        WebhookProc["Webhook Feature Update"]:::service
        SecCommon["Security Common"]:::service
        SecOAuth["OAuth2 Provider"]:::service
        SecSAML["SAML Provider"]:::service
        PartyServer["Party Server (In-Mem Demo)"]:::service
    end

    %% Data Stores & Event Bus
    subgraph "Data & Event Bus"
        direction TB
        RelDB["Relational DB (Ebean/SQL)"]:::db
        EventBus["Event Bus\nNATS/PubSub/Kinesis"]:::bus
    end

    %% SDK Clients
    subgraph "SDK Clients"
        direction TB
        EdgeSDKs["Edge SDKs\nJS/Android/iOS/.NET"]:::sdk
        CustomApps["Custom Apps\nEdgeFeatureHubConfig"]:::sdk
    end

    %% External Integrations
    subgraph "External Integrations"
        direction TB
        OAuth2["OAuth2 Provider"]:::external
        SAML["SAML Provider"]:::external
        Analytics["Analytics/Webhooks"]:::external
    end

    %% Infra & CI/CD
    subgraph "Infra & CI/CD"
        direction TB
        Pulumi["Pulumi S3 API Bucket"]:::infra
        CIApp["App Build Pipelines"]:::infra
        DeployCharts["Helm Charts & Deploy"]:::infra
    end

    %% Docs & Testing
    subgraph "Docs & Testing"
        direction TB
        Docs["Documentation Site (Antora)"]:::external
        E2E["End-to-End Tests (Cucumber)"]:::external
    end

    %% Relationships
    AdminConsole -->|"REST"| MRAPI
    CLI -->|"REST"| MRAPI
    AdminSDK -->|"REST"| MRAPI

    MRAPI -->|"serves API"| MRService
    MRService -->|"reads/writes"| RelDB
    MRService -->|"publishes events"| EventBus

    EventBus -->|"consume"| DachaV1
    EventBus -->|"consume"| DachaV2
    EventBus -->|"consume"| MREvent
    EventBus -->|"consume"| MREventCommon
    EventBus -->|"consume"| EventCE
    EventBus -->|"consume"| EventGCP
    EventBus -->|"consume"| EventNATS
    EventBus -->|"consume"| EventKinesis
    EventBus -->|"consume"| Messaging
    EventBus -->|"consume"| WebhookProc

    DachaV1 -->|"snapshot feed"| EdgeFull
    DachaV2 -->|"snapshot feed"| EdgeREST
    MREvent -->|"forward events"| EventBus

    EdgeFull -->|"SSE/REST"| EdgeSDKs
    EdgeREST -->|"HTTP"| EdgeSDKs
    EdgeFull -->|"HTTP"| CustomApps
    EdgeREST -->|"HTTP"| CustomApps

    SecCommon -->|"sec frameworks"| MRService
    SecOAuth -->|"OAuth2"| AdminConsole
    SecSAML -->|"SAML"| AdminConsole

    Pulumi -->|"deploys"| MRService
    Pulumi -->|"deploys"| DachaV1
    Pulumi -->|"deploys"| DachaV2
    Pulumi -->|"deploys"| EdgeFull
    Pulumi -->|"deploys"| EdgeREST
    CIApp -->|"builds images"| DeployCharts
    DeployCharts -->|"deploys to k8s"| MRService
    DeployCharts -->|"deploys to k8s"| DachaV1
    DeployCharts -->|"deploys to k8s"| DachaV2
    DeployCharts -->|"deploys to k8s"| EdgeFull
    DeployCharts -->|"deploys to k8s"| EdgeREST

    Docs -->|"docs"| AdminConsole
    E2E -->|"tests"| MRService

    %% Click Events
    click AdminConsole "https://github.com/featurehub-io/featurehub/tree/main/admin-frontend/open_admin_app"
    click CLI "https://github.com/featurehub-io/featurehub/tree/main/admin-frontend/cli"
    click AdminSDK "https://github.com/featurehub-io/featurehub/tree/main/adks/e2e-sdk"
    click MRAPI "https://github.com/featurehub-io/featurehub/tree/main/backend/mr-api"
    click MRService "https://github.com/featurehub-io/featurehub/tree/main/backend/mr"
    click CommonLibs "https://github.com/featurehub-io/featurehub/tree/main/backend/common-web"
    click CommonLibs "https://github.com/featurehub-io/featurehub/tree/main/backend/common-db"
    click DachaV1 "https://github.com/featurehub-io/featurehub/tree/main/backend/dacha"
    click DachaV2 "https://github.com/featurehub-io/featurehub/tree/main/backend/dacha2"
    click EdgeFull "https://github.com/featurehub-io/featurehub/tree/main/backend/edge-full"
    click EdgeREST "https://github.com/featurehub-io/featurehub/tree/main/backend/edge-rest"
    click EdgeAPI "https://github.com/featurehub-io/featurehub/tree/main/backend/edge-api"
    click EdgeCommon "https://github.com/featurehub-io/featurehub/tree/main/backend/edge-common"
    click EventCE "https://github.com/featurehub-io/featurehub/tree/main/backend/eventing-cloudevents"
    click EventGCP "https://github.com/featurehub-io/featurehub/tree/main/backend/eventing-google-pubsub"
    click EventNATS "https://github.com/featurehub-io/featurehub/tree/main/backend/eventing-nats"
    click EventKinesis "https://github.com/featurehub-io/featurehub/tree/main/backend/eventing-kinesis"
    click MREventCommon "https://github.com/featurehub-io/featurehub/tree/main/backend/mr-eventing-common"
    click MREvent "https://github.com/featurehub-io/featurehub/tree/main/backend/mr-eventing"
    click MREventNATS "https://github.com/featurehub-io/featurehub/tree/main/backend/mr-eventing-nats"
    click Messaging "https://github.com/featurehub-io/featurehub/tree/main/backend/messaging-delivery"
    click WebhookAPI "https://github.com/featurehub-io/featurehub/tree/main/backend/webhook-api"
    click WebhookCommon "https://github.com/featurehub-io/featurehub/tree/main/backend/webhook-common"
    click WebhookProc "https://github.com/featurehub-io/featurehub/tree/main/backend/webhook-feature-update"
    click SecCommon "https://github.com/featurehub-io/featurehub/tree/main/backend/security-common"
    click SecOAuth "https://github.com/featurehub-io/featurehub/tree/main/backend/security-oauth"
    click SecSAML "https://github.com/featurehub-io/featurehub/tree/main/backend/security-saml"
    click RelDB "https://github.com/featurehub-io/featurehub/tree/main/backend/mr-db-ebean"
    click PartyServer "https://github.com/featurehub-io/featurehub/tree/main/backend/party-server"
    click PartyServer "https://github.com/featurehub-io/featurehub/tree/main/backend/party-server-ish"
    click Pulumi "https://github.com/featurehub-io/featurehub/tree/main/infra/api-bucket"
    click CIApp "https://github.com/featurehub-io/featurehub/tree/main/pipeline/app-build-pipeline"
    click CIApp "https://github.com/featurehub-io/featurehub/tree/main/pipeline/app-master-pipeline"
    click CIApp "https://github.com/featurehub-io/featurehub/tree/main/pipeline/app-prerelease-pipeline"
    click DeployCharts "https://github.com/featurehub-io/featurehub/tree/main/pipeline/deploy"
    click Docs "https://github.com/featurehub-io/featurehub/tree/main/docs"
    click E2E "https://github.com/featurehub-io/featurehub/tree/main/e2e"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#000
    classDef api fill:#D6FFD0,stroke:#000
    classDef service fill:#FFE6A1,stroke:#000
    classDef db fill:#FFE0E0,stroke:#000
    classDef bus fill:#FFD8B8,stroke:#000
    classDef cache fill:#E8D0FF,stroke:#000
    classDef sdk fill:#CEE0FF,stroke:#000
    classDef infra fill:#D0F0E8,stroke:#000
    classDef external fill:#F0F0F0,stroke:#000
```
