# parijatpal/flagforge architecture

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

- Interactive diagram: https://gitdiagram.com/parijatpal/flagforge
- Repository: https://github.com/parijatpal/flagforge

## Overview

FlagForge is a self-hosted feature-flag service. Administrators manage environment-specific flags and review audit history through the dashboard or API; applications evaluate flags directly or use the SDK’s locally cached snapshot, refreshed by SSE updates. The graph preserves flag management, validation, evaluation, audit, streaming, dashboard, and SDK responsibilities. Edges follow shown calls or README claims; unsampled dashboard/API wiring and documented capabilities are cited at the README level.

Main entry points: [`api/src/app.js`](https://github.com/parijatpal/flagforge/blob/main/api/src/app.js) (API Routing), [`api/src/routes/evaluate.js`](https://github.com/parijatpal/flagforge/blob/main/api/src/routes/evaluate.js) (Evaluate Route), [`api/src/db/flagRepository.js`](https://github.com/parijatpal/flagforge/blob/main/api/src/db/flagRepository.js) (Flag Repository), [`sdk/src/client.js`](https://github.com/parijatpal/flagforge/blob/main/sdk/src/client.js) (Remote SDK Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_admin["Administration"]
  node_dashboard["Admin Dashboard<br/>[App.jsx]"]
  node_dashboard_api["Dashboard API<br/>[api.js]"]
end

subgraph group_api["API Runtime"]
  node_api_server["API Server<br/>[server.js]"]
  node_api_app["API Routing<br/>[app.js]"]
  node_auth["Admin Auth<br/>[auth.js]"]
  node_rate_limit["Rate Limiting<br/>[rateLimit.js]"]
  node_flag_routes["Flag Management<br/>[flags.js]"]
  node_flag_schema["Flag Validation<br/>[flagSchema.js]"]
  node_eval_route["Evaluate Route<br/>[evaluate.js]"]
  node_evaluation["Decision Logic<br/>[evaluation.js]"]
  node_sdk_route["SDK Snapshot Route<br/>[sdk.js]"]
  node_audit_route["Audit Route<br/>[audit.js]"]
  node_stream_route["SSE Stream<br/>[stream.js]"]
end

subgraph group_state["State and Updates"]
  node_flag_repo["Flag Repository<br/>[flagRepository.js]"]
  node_audit_repo["Audit Repository<br/>[auditRepository.js]"]
  node_redis_client["Redis Client<br/>[redisClient.js]"]
  node_redis_store[("Redis")]
end

subgraph group_sdk["SDK Evaluation"]
  node_sdk_client["Remote SDK Client<br/>[client.js]"]
  node_local_client["Local SDK Client<br/>[local-client.js]"]
  node_sdk_evaluation["SDK Decision Logic<br/>[evaluation.js]"]
end

node_admin_user(("Administrator"))
node_app_developer(("Application"))

node_admin_user -->|"manages flags"| node_dashboard
node_dashboard -->|"requests data"| node_dashboard_api
node_dashboard_api -->|"calls API"| node_api_app
node_api_server -->|"starts"| node_api_app
node_api_app -->|"routes flags"| node_flag_routes
node_api_app -->|"routes evaluation"| node_eval_route
node_api_app -->|"routes snapshots"| node_sdk_route
node_api_app -->|"routes audits"| node_audit_route
node_api_app -->|"routes streams"| node_stream_route
node_api_app -->|"guards admin routes"| node_auth
node_api_app -->|"limits requests"| node_rate_limit
node_flag_routes -->|"validates flags"| node_flag_schema
node_flag_routes -->|"manages records"| node_flag_repo
node_eval_route -->|"loads flag"| node_flag_repo
node_eval_route -->|"evaluates flag"| node_evaluation
node_eval_route -->|"validates environment"| node_flag_schema
node_sdk_route -->|"loads snapshot"| node_flag_repo
node_sdk_route -->|"validates environment"| node_flag_schema
node_audit_route -->|"lists history"| node_audit_repo
node_stream_route -->|"subscribes updates"| node_redis_client
node_flag_repo -->|"reads and writes"| node_redis_client
node_flag_repo -->|"records changes"| node_audit_repo
node_audit_repo -->|"stores history"| node_redis_client
node_redis_client -->|"issues commands"| node_redis_store
node_app_developer -->|"checks flags"| node_sdk_client
node_sdk_client -->|"requests decisions"| node_eval_route
node_sdk_client -->|"opens event stream"| node_stream_route
node_sdk_client -->|"extends client"| node_local_client
node_local_client -->|"fetches snapshots"| node_sdk_route
node_local_client -->|"evaluates locally"| node_sdk_evaluation
node_local_client -->|"resyncs on events"| node_stream_route
node_app_developer -->|"evaluates directly"| node_eval_route

click node_dashboard "https://github.com/parijatpal/flagforge/blob/main/dashboard/src/App.jsx"
click node_dashboard_api "https://github.com/parijatpal/flagforge/blob/main/dashboard/src/api.js"
click node_api_server "https://github.com/parijatpal/flagforge/blob/main/api/src/server.js"
click node_api_app "https://github.com/parijatpal/flagforge/blob/main/api/src/app.js"
click node_auth "https://github.com/parijatpal/flagforge/blob/main/api/src/middleware/auth.js"
click node_rate_limit "https://github.com/parijatpal/flagforge/blob/main/api/src/middleware/rateLimit.js"
click node_flag_routes "https://github.com/parijatpal/flagforge/blob/main/api/src/routes/flags.js"
click node_flag_schema "https://github.com/parijatpal/flagforge/blob/main/api/src/models/flagSchema.js"
click node_eval_route "https://github.com/parijatpal/flagforge/blob/main/api/src/routes/evaluate.js"
click node_evaluation "https://github.com/parijatpal/flagforge/blob/main/api/src/services/evaluation.js"
click node_sdk_route "https://github.com/parijatpal/flagforge/blob/main/api/src/routes/sdk.js"
click node_audit_route "https://github.com/parijatpal/flagforge/blob/main/api/src/routes/audit.js"
click node_stream_route "https://github.com/parijatpal/flagforge/blob/main/api/src/routes/stream.js"
click node_flag_repo "https://github.com/parijatpal/flagforge/blob/main/api/src/db/flagRepository.js"
click node_audit_repo "https://github.com/parijatpal/flagforge/blob/main/api/src/db/auditRepository.js"
click node_redis_client "https://github.com/parijatpal/flagforge/blob/main/api/src/db/redisClient.js"
click node_sdk_client "https://github.com/parijatpal/flagforge/blob/main/sdk/src/client.js"
click node_local_client "https://github.com/parijatpal/flagforge/blob/main/sdk/src/local-client.js"
click node_sdk_evaluation "https://github.com/parijatpal/flagforge/blob/main/sdk/src/evaluation.js"

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_dashboard,node_dashboard_api toneBlue
class node_api_server,node_api_app,node_auth,node_rate_limit,node_flag_routes,node_flag_schema,node_eval_route,node_evaluation,node_sdk_route,node_audit_route,node_stream_route toneAmber
class node_flag_repo,node_audit_repo,node_redis_client,node_redis_store toneMint
class node_sdk_client,node_local_client,node_sdk_evaluation toneRose
class node_admin_user,node_app_developer toneIndigo
```

## Components

### Administration

- [Admin Dashboard](https://github.com/parijatpal/flagforge/blob/main/dashboard/src/App.jsx): `dashboard/src/App.jsx`
- [Dashboard API](https://github.com/parijatpal/flagforge/blob/main/dashboard/src/api.js): `dashboard/src/api.js`

### API Runtime

- [API Server](https://github.com/parijatpal/flagforge/blob/main/api/src/server.js): `api/src/server.js`
- [API Routing](https://github.com/parijatpal/flagforge/blob/main/api/src/app.js): `api/src/app.js`
- [Admin Auth](https://github.com/parijatpal/flagforge/blob/main/api/src/middleware/auth.js): `api/src/middleware/auth.js`
- [Rate Limiting](https://github.com/parijatpal/flagforge/blob/main/api/src/middleware/rateLimit.js): `api/src/middleware/rateLimit.js`
- [Flag Management](https://github.com/parijatpal/flagforge/blob/main/api/src/routes/flags.js): `api/src/routes/flags.js`
- [Flag Validation](https://github.com/parijatpal/flagforge/blob/main/api/src/models/flagSchema.js): `api/src/models/flagSchema.js`
- [Evaluate Route](https://github.com/parijatpal/flagforge/blob/main/api/src/routes/evaluate.js): `api/src/routes/evaluate.js`
- [Decision Logic](https://github.com/parijatpal/flagforge/blob/main/api/src/services/evaluation.js): `api/src/services/evaluation.js`
- [SDK Snapshot Route](https://github.com/parijatpal/flagforge/blob/main/api/src/routes/sdk.js): `api/src/routes/sdk.js`
- [Audit Route](https://github.com/parijatpal/flagforge/blob/main/api/src/routes/audit.js): `api/src/routes/audit.js`
- [SSE Stream](https://github.com/parijatpal/flagforge/blob/main/api/src/routes/stream.js): `api/src/routes/stream.js`

### State and Updates

- [Flag Repository](https://github.com/parijatpal/flagforge/blob/main/api/src/db/flagRepository.js): `api/src/db/flagRepository.js`
- [Audit Repository](https://github.com/parijatpal/flagforge/blob/main/api/src/db/auditRepository.js): `api/src/db/auditRepository.js`
- [Redis Client](https://github.com/parijatpal/flagforge/blob/main/api/src/db/redisClient.js): `api/src/db/redisClient.js`
- **Redis**

### SDK Evaluation

- [Remote SDK Client](https://github.com/parijatpal/flagforge/blob/main/sdk/src/client.js): `sdk/src/client.js`
- [Local SDK Client](https://github.com/parijatpal/flagforge/blob/main/sdk/src/local-client.js): `sdk/src/local-client.js`
- [SDK Decision Logic](https://github.com/parijatpal/flagforge/blob/main/sdk/src/evaluation.js): `sdk/src/evaluation.js`

### Other components

- **Administrator**
- **Application**

## Connections

- Administrator → Admin Dashboard: manages flags (evidence: `README.md`)
- Admin Dashboard → Dashboard API: requests data (evidence: `dashboard/src/App.jsx`)
- Dashboard API → API Routing: calls API (evidence: `README.md`)
- API Server → API Routing: starts (evidence: `api/src/server.js`)
- API Routing → Flag Management: routes flags (evidence: `api/src/app.js`)
- API Routing → Evaluate Route: routes evaluation (evidence: `api/src/app.js`)
- API Routing → SDK Snapshot Route: routes snapshots (evidence: `api/src/app.js`)
- API Routing → Audit Route: routes audits (evidence: `api/src/app.js`)
- API Routing → SSE Stream: routes streams (evidence: `api/src/app.js`)
- API Routing → Admin Auth: guards admin routes (evidence: `api/src/app.js`)
- API Routing → Rate Limiting: limits requests (evidence: `api/src/app.js`)
- Flag Management → Flag Validation: validates flags (evidence: `api/src/routes/flags.js`)
- Flag Management → Flag Repository: manages records (evidence: `api/src/routes/flags.js`)
- Evaluate Route → Flag Repository: loads flag (evidence: `api/src/routes/evaluate.js`)
- Evaluate Route → Decision Logic: evaluates flag (evidence: `api/src/routes/evaluate.js`)
- Evaluate Route → Flag Validation: validates environment (evidence: `api/src/routes/evaluate.js`)
- SDK Snapshot Route → Flag Repository: loads snapshot (evidence: `api/src/routes/sdk.js`)
- SDK Snapshot Route → Flag Validation: validates environment (evidence: `api/src/routes/sdk.js`)
- Audit Route → Audit Repository: lists history (evidence: `api/src/routes/audit.js`)
- SSE Stream → Redis Client: subscribes updates (evidence: `api/src/routes/stream.js`)
- Flag Repository → Redis Client: reads and writes (evidence: `api/src/db/flagRepository.js`)
- Flag Repository → Audit Repository: records changes (evidence: `api/src/db/flagRepository.js`)
- Audit Repository → Redis Client: stores history (evidence: `api/src/db/auditRepository.js`)
- Redis Client → Redis: issues commands (evidence: `api/src/db/redisClient.js`)
- Application → Remote SDK Client: checks flags (evidence: `README.md`)
- Remote SDK Client → Evaluate Route: requests decisions (evidence: `sdk/src/client.js`)
- Remote SDK Client → SSE Stream: opens event stream (evidence: `sdk/src/client.js`)
- Remote SDK Client → Local SDK Client: extends client (evidence: `sdk/src/local-client.js`)
- Local SDK Client → SDK Snapshot Route: fetches snapshots (evidence: `sdk/src/local-client.js`)
- Local SDK Client → SDK Decision Logic: evaluates locally (evidence: `sdk/src/local-client.js`)
- Local SDK Client → SSE Stream: resyncs on events (evidence: `sdk/src/local-client.js`)
- Application → Evaluate Route: evaluates directly (evidence: `README.md`)
