# mahakagarwal7/featureflag architecture

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

- Interactive diagram: https://gitdiagram.com/mahakagarwal7/featureflag
- Repository: https://github.com/mahakagarwal7/featureflag

## Overview

#### Purpose and Entrypoints
This repository is a feature-flag rollout simulation benchmark: agents make sequential rollout decisions while telemetry, risk, revenue, and health evolve. The primary runtime is Python; entrypoints include API servers at `backend/feature_flag_env/server/app.py` and `backend/server/app.py`, local/remote evaluation in `backend/inference.py`, and training scripts `backend/train_rl.py` and `backend/train_enterprise.py`.

#### Simulation Environment
The environment owns episode state, action application, and telemetry transitions for rollout actions such as increase, halt, full rollout, and rollback. `backend/feature_flag_env/server/feature_flag_environment.py` is the central environment boundary; `backend/feature_flag_env/server/simulation_engine.py` supplies simulation behavior, while `backend/feature_flag_env/models.py` defines domain/state models. Scenario and mission inputs extend the core simulation through `backend/feature_flag_env/configs/scenario_library.py` and `backend/feature_flag_env/missions.py`.

#### Evaluation and Reward Pipeline
A step produces updated observation and reward; a completed trajectory is task-scored. Task definitions separate benchmark objectives—safe rollout, risk-aware scaling, and multi-objective optimization—in `backend/feature_flag_env/tasks/task1_safe_rollout.py`, `backend/feature_flag_env/tasks/task2_risk_aware.py`, and `backend/feature_flag_env/tasks/task3_multi_objective.py`. Shared trajectory grading is in `backend/feature_flag_env/tasks/graders.py`; reward policy and extended reward signals reside in `backend/feature_flag_env/utils/reward_functions.py` and `backend/feature_flag_env/utils/extended_rewards.py`.

#### Agent Layer
Agents consume observations and emit environment actions behind a common abstraction. `backend/agents/base_agent.py` establishes the agent contract, and `backend/agents/factory.py` selects implementations. Major policy variants are deterministic baseline (`backend/agents/baseline_agent.py`), LLM-driven (`backend/agents/llm_agent.py`), RL/checkpoint-driven (`backend/agents/rl_agent.py`), and enterprise orchestration (`backend/agents/enterprise_agent_v2.py`, `backend/agents/master_agent.py`). Ensemble and human-approval modes are separate decision boundaries in `backend/agents/ensemble_agent.py` and `backend/agents/human_in_loop_agent.py`.

#### API, Security, and Operational Controls
The simulation is exposed as an HTTP API with reset, step, state, health, and info operations through `backend/feature_flag_env/server/app.py`. Server concerns are split from environment behavior: `backend/feature_flag_env/server/security.py` handles security controls, and `backend/feature_flag_env/utils/monitoring.py` provides monitoring/alerting support. Persistence/audit-oriented infrastructure is represented by `backend/feature_flag_env/utils/database.py` and repository runtime artifacts under `logs/`.

#### Integrations and External Services
Tooling isolates external actions behind interfaces and a manager: `backend/feature_flag_env/tools/tool_interface.py`, `backend/feature_flag_env/tools/tool_manager.py`, and `backend/feature_flag_env/tools/connectors.py`. GitHub and Slack integrations have dedicated adapters in `backend/feature_flag_env/tools/github_integration.py` and `backend/feature_flag_env/tools/slack_integration.py`; mock versus real adapter boundaries are explicit in `backend/feature_flag_env/tools/mock_adapters.py` and `backend/feature_flag_env/tools/real_adapters.py`. The LLM agent supports OpenAI-compatible/Hugging Face router-style inference via environment configuration.

#### UI and Deployment Boundary
A separate Next.js/TypeScript frontend presents dashboard, flag, experiment, monitoring, integration, and AI-decision workflows. Route composition begins at `frontend/app/layout.tsx`, dashboard pages live under `frontend/app/(dashboard)/`, and backend communication is centralized in `frontend/lib/api.ts`. The backend can also serve committed static frontend output from `backend/static/`. Docker deployment is defined by `Dockerfile` and `backend/Dockerfile`, targeting Hugging Face Spaces’ Docker runtime and port 7860.

Main entry points: [`backend/feature_flag_env/server/feature_flag_environment.py`](https://github.com/mahakagarwal7/featureflag/blob/main/backend/feature_flag_env/server/feature_flag_environment.py) (Feature Flag Environment), [`backend/agents/enterprise_agent_v2.py`](https://github.com/mahakagarwal7/featureflag/blob/main/backend/agents/enterprise_agent_v2.py) (Enterprise Orchestration), [`backend/feature_flag_env/server/app.py`](https://github.com/mahakagarwal7/featureflag/blob/main/backend/feature_flag_env/server/app.py) (Simulation HTTP API), [`backend/agents/base_agent.py`](https://github.com/mahakagarwal7/featureflag/blob/main/backend/agents/base_agent.py) (Agent Contract & Factory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entrypoints["Runtimes"]
  node_env_api["Simulation HTTP API<br/>FastAPI server<br/>[app.py]"]
  node_legacy_api["Backend API<br/>Python server<br/>[app.py]"]
  node_evaluation["Evaluation Runner<br/>evaluation runtime<br/>[inference.py]"]
  node_training["RL &amp; Enterprise Training<br/>training scripts<br/>[train_rl.py]"]
end

subgraph group_simulation["Simulation &amp; Scoring"]
  node_environment{{"Feature Flag Environment<br/>episode boundary"}}
  node_simulation_engine["Simulation Engine<br/>transition engine"]
  node_domain_models["Domain Models<br/>state models<br/>[models.py]"]
  node_scenario_missions["Scenarios &amp; Missions<br/>episode inputs"]
  node_tasks["Benchmark Tasks<br/>task definitions"]
  node_grading_rewards["Trajectory Grading &amp; Rewards<br/>scoring policy<br/>[graders.py]"]
end

subgraph group_agents["Agent Policies"]
  node_agent_contract{{"Agent Contract &amp; Factory<br/>agent abstraction<br/>[base_agent.py]"}}
  node_policy_agents["Baseline, LLM &amp; RL Agents<br/>policy implementations<br/>[llm_agent.py]"]
  node_enterprise_agents["Enterprise Orchestration<br/>orchestrating policy"]
  node_decision_modes["Ensemble &amp; Human Approval<br/>decision controls<br/>[ensemble_agent.py]"]
end

subgraph group_operations["Operations &amp; Integrations"]
  node_security["Security Controls<br/>API security<br/>[security.py]"]
  node_monitoring_audit[("Monitoring &amp; Audit Store<br/>operational telemetry<br/>[monitoring.py]")]
  node_tool_manager{{"Tool Manager<br/>integration boundary<br/>[tool_manager.py]"}}
  node_external_adapters["GitHub &amp; Slack Adapters<br/>external connectors"]
end

subgraph group_ui["UI &amp; Deployment"]
  node_frontend["Next.js Dashboard<br/>web frontend<br/>[layout.tsx]"]
  node_frontend_api["Frontend API Client<br/>backend client<br/>[api.ts]"]
  node_deployment["Docker / Spaces Runtime<br/>deployment"]
end

node_env_api -->|"protects requests"| node_security
node_env_api -->|"reset / step"| node_environment
node_legacy_api -->|"serves simulation"| node_environment
node_evaluation -->|"selects agent"| node_agent_contract
node_evaluation -->|"runs episodes"| node_environment
node_training -->|"collects rollouts"| node_environment
node_environment -->|"applies actions"| node_simulation_engine
node_environment -->|"reads and updates state"| node_domain_models
node_scenario_missions -->|"configures episode"| node_environment
node_environment -->|"provides trajectory"| node_tasks
node_tasks -->|"uses scoring policy"| node_grading_rewards
node_grading_rewards -->|"returns reward"| node_environment
node_agent_contract -->|"instantiates policies"| node_policy_agents
node_agent_contract -->|"instantiates orchestration"| node_enterprise_agents
node_enterprise_agents -->|"uses approval modes"| node_decision_modes
node_policy_agents -->|"actions from observations"| node_environment
node_enterprise_agents -->|"orchestrated actions"| node_environment
node_environment -->|"emits telemetry"| node_monitoring_audit
node_enterprise_agents -->|"invokes external actions"| node_tool_manager
node_tool_manager -->|"routes integrations"| node_external_adapters
node_frontend -->|"uses"| node_frontend_api
node_frontend_api -->|"backend requests"| node_env_api
node_deployment -->|"runs"| node_env_api
node_deployment -->|"deploys UI"| node_frontend

click node_env_api "https://github.com/mahakagarwal7/featureflag/blob/main/backend/feature_flag_env/server/app.py"
click node_legacy_api "https://github.com/mahakagarwal7/featureflag/blob/main/backend/server/app.py"
click node_evaluation "https://github.com/mahakagarwal7/featureflag/blob/main/backend/inference.py"
click node_training "https://github.com/mahakagarwal7/featureflag/blob/main/backend/train_rl.py"
click node_environment "https://github.com/mahakagarwal7/featureflag/blob/main/backend/feature_flag_env/server/feature_flag_environment.py"
click node_simulation_engine "https://github.com/mahakagarwal7/featureflag/blob/main/backend/feature_flag_env/server/simulation_engine.py"
click node_domain_models "https://github.com/mahakagarwal7/featureflag/blob/main/backend/feature_flag_env/models.py"
click node_scenario_missions "https://github.com/mahakagarwal7/featureflag/blob/main/backend/feature_flag_env/configs/scenario_library.py"
click node_tasks "https://github.com/mahakagarwal7/featureflag/blob/main/backend/feature_flag_env/tasks/task1_safe_rollout.py"
click node_grading_rewards "https://github.com/mahakagarwal7/featureflag/blob/main/backend/feature_flag_env/tasks/graders.py"
click node_agent_contract "https://github.com/mahakagarwal7/featureflag/blob/main/backend/agents/base_agent.py"
click node_policy_agents "https://github.com/mahakagarwal7/featureflag/blob/main/backend/agents/llm_agent.py"
click node_enterprise_agents "https://github.com/mahakagarwal7/featureflag/blob/main/backend/agents/enterprise_agent_v2.py"
click node_decision_modes "https://github.com/mahakagarwal7/featureflag/blob/main/backend/agents/ensemble_agent.py"
click node_security "https://github.com/mahakagarwal7/featureflag/blob/main/backend/feature_flag_env/server/security.py"
click node_monitoring_audit "https://github.com/mahakagarwal7/featureflag/blob/main/backend/feature_flag_env/utils/monitoring.py"
click node_tool_manager "https://github.com/mahakagarwal7/featureflag/blob/main/backend/feature_flag_env/tools/tool_manager.py"
click node_external_adapters "https://github.com/mahakagarwal7/featureflag/blob/main/backend/feature_flag_env/tools/github_integration.py"
click node_frontend "https://github.com/mahakagarwal7/featureflag/blob/main/frontend/app/layout.tsx"
click node_frontend_api "https://github.com/mahakagarwal7/featureflag/blob/main/frontend/lib/api.ts"
click node_deployment "https://github.com/mahakagarwal7/featureflag/blob/main/Dockerfile"

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_env_api,node_legacy_api,node_evaluation,node_training toneBlue
class node_environment,node_simulation_engine,node_domain_models,node_scenario_missions,node_tasks,node_grading_rewards toneAmber
class node_agent_contract,node_policy_agents,node_enterprise_agents,node_decision_modes toneMint
class node_security,node_monitoring_audit,node_tool_manager,node_external_adapters toneRose
class node_frontend,node_frontend_api,node_deployment toneIndigo
```

## Components

### Runtimes

- [Simulation HTTP API](https://github.com/mahakagarwal7/featureflag/blob/main/backend/feature_flag_env/server/app.py): FastAPI server · Exposes reset, step, state, health, and info operations. · `backend/feature_flag_env/server/app.py`
- [Backend API](https://github.com/mahakagarwal7/featureflag/blob/main/backend/server/app.py): Python server · `backend/server/app.py`
- [Evaluation Runner](https://github.com/mahakagarwal7/featureflag/blob/main/backend/inference.py): evaluation runtime · Runs local or remote agent evaluation. · `backend/inference.py`
- [RL & Enterprise Training](https://github.com/mahakagarwal7/featureflag/blob/main/backend/train_rl.py): training scripts · `backend/train_rl.py`

### Simulation & Scoring

- [Feature Flag Environment](https://github.com/mahakagarwal7/featureflag/blob/main/backend/feature_flag_env/server/feature_flag_environment.py): episode boundary · Owns state, action application, observations, and transitions. · `backend/feature_flag_env/server/feature_flag_environment.py`
- [Simulation Engine](https://github.com/mahakagarwal7/featureflag/blob/main/backend/feature_flag_env/server/simulation_engine.py): transition engine · `backend/feature_flag_env/server/simulation_engine.py`
- [Domain Models](https://github.com/mahakagarwal7/featureflag/blob/main/backend/feature_flag_env/models.py): state models · `backend/feature_flag_env/models.py`
- [Scenarios & Missions](https://github.com/mahakagarwal7/featureflag/blob/main/backend/feature_flag_env/configs/scenario_library.py): episode inputs · `backend/feature_flag_env/configs/scenario_library.py`
- [Benchmark Tasks](https://github.com/mahakagarwal7/featureflag/blob/main/backend/feature_flag_env/tasks/task1_safe_rollout.py): task definitions · Safe rollout, risk-aware scaling, and multi-objective objectives. · `backend/feature_flag_env/tasks/task1_safe_rollout.py`
- [Trajectory Grading & Rewards](https://github.com/mahakagarwal7/featureflag/blob/main/backend/feature_flag_env/tasks/graders.py): scoring policy · `backend/feature_flag_env/tasks/graders.py`

### Agent Policies

- [Agent Contract & Factory](https://github.com/mahakagarwal7/featureflag/blob/main/backend/agents/base_agent.py): agent abstraction · `backend/agents/base_agent.py`
- [Baseline, LLM & RL Agents](https://github.com/mahakagarwal7/featureflag/blob/main/backend/agents/llm_agent.py): policy implementations · `backend/agents/llm_agent.py`
- [Enterprise Orchestration](https://github.com/mahakagarwal7/featureflag/blob/main/backend/agents/enterprise_agent_v2.py): orchestrating policy · `backend/agents/enterprise_agent_v2.py`
- [Ensemble & Human Approval](https://github.com/mahakagarwal7/featureflag/blob/main/backend/agents/ensemble_agent.py): decision controls · `backend/agents/ensemble_agent.py`

### Operations & Integrations

- [Security Controls](https://github.com/mahakagarwal7/featureflag/blob/main/backend/feature_flag_env/server/security.py): API security · `backend/feature_flag_env/server/security.py`
- [Monitoring & Audit Store](https://github.com/mahakagarwal7/featureflag/blob/main/backend/feature_flag_env/utils/monitoring.py): operational telemetry · `backend/feature_flag_env/utils/monitoring.py`
- [Tool Manager](https://github.com/mahakagarwal7/featureflag/blob/main/backend/feature_flag_env/tools/tool_manager.py): integration boundary · Coordinates isolated external actions through tool interfaces. · `backend/feature_flag_env/tools/tool_manager.py`
- [GitHub & Slack Adapters](https://github.com/mahakagarwal7/featureflag/blob/main/backend/feature_flag_env/tools/github_integration.py): external connectors · Supports mock and real external-service adapters. · `backend/feature_flag_env/tools/github_integration.py`

### UI & Deployment

- [Next.js Dashboard](https://github.com/mahakagarwal7/featureflag/blob/main/frontend/app/layout.tsx): web frontend · Presents rollout, monitoring, integrations, and AI decisions. · `frontend/app/layout.tsx`
- [Frontend API Client](https://github.com/mahakagarwal7/featureflag/blob/main/frontend/lib/api.ts): backend client · `frontend/lib/api.ts`
- [Docker / Spaces Runtime](https://github.com/mahakagarwal7/featureflag/blob/main/Dockerfile): deployment · Targets Hugging Face Spaces on port 7860. · `Dockerfile`

## Connections

- Simulation HTTP API → Security Controls: protects requests
- Simulation HTTP API → Feature Flag Environment: reset / step
- Backend API → Feature Flag Environment: serves simulation
- Evaluation Runner → Agent Contract & Factory: selects agent
- Evaluation Runner → Feature Flag Environment: runs episodes
- RL & Enterprise Training → Feature Flag Environment: collects rollouts
- Feature Flag Environment → Simulation Engine: applies actions
- Feature Flag Environment → Domain Models: reads and updates state
- Scenarios & Missions → Feature Flag Environment: configures episode
- Feature Flag Environment → Benchmark Tasks: provides trajectory
- Benchmark Tasks → Trajectory Grading & Rewards: uses scoring policy
- Trajectory Grading & Rewards → Feature Flag Environment: returns reward
- Agent Contract & Factory → Baseline, LLM & RL Agents: instantiates policies
- Agent Contract & Factory → Enterprise Orchestration: instantiates orchestration
- Enterprise Orchestration → Ensemble & Human Approval: uses approval modes
- Baseline, LLM & RL Agents → Feature Flag Environment: actions from observations
- Enterprise Orchestration → Feature Flag Environment: orchestrated actions
- Feature Flag Environment → Monitoring & Audit Store: emits telemetry
- Enterprise Orchestration → Tool Manager: invokes external actions
- Tool Manager → GitHub & Slack Adapters: routes integrations
- Next.js Dashboard → Frontend API Client: uses
- Frontend API Client → Simulation HTTP API: backend requests
- Docker / Spaces Runtime → Simulation HTTP API: runs
- Docker / Spaces Runtime → Next.js Dashboard: deploys UI