# manjeetjay/adaptive-lb-m architecture

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

- Interactive diagram: https://gitdiagram.com/manjeetjay/adaptive-lb-m
- Repository: https://github.com/manjeetjay/adaptive-lb-m

## Overview

ALB-M is a research-oriented Layer-7 adaptive load balancer. Requests enter the gateway, which discovers worker instances, selects one using a configurable routing strategy and live telemetry, then forwards traffic. Workers expose workload and chaos controls plus metrics; a separate benchmark harness exercises strategies and fault scenarios, and the frontend presents live controls and research results. The README documents additional observability and experiment capabilities; some implementation paths are unsampled, so those branches are shown only where supported by documentation or indexed references.

Main entry points: [`gateway/src/main/java/com/alb/gateway/routing/filter/AdaptiveRoutingFilter.java`](https://github.com/manjeetjay/adaptive-lb-m/blob/main/gateway/src/main/java/com/alb/gateway/routing/filter/AdaptiveRoutingFilter.java) (Routing filter), [`experiments/orchestrator.py`](https://github.com/manjeetjay/adaptive-lb-m/blob/main/experiments/orchestrator.py) (Experiment orchestrator), [`frontend/src/App.jsx`](https://github.com/manjeetjay/adaptive-lb-m/blob/main/frontend/src/App.jsx) (Research dashboard), [`gateway/src/main/java/com/alb/gateway/routing/adaptive/MetricPollerService.java`](https://github.com/manjeetjay/adaptive-lb-m/blob/main/gateway/src/main/java/com/alb/gateway/routing/adaptive/MetricPollerService.java) (Metric poller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_routing["Gateway routing"]
  node_gateway_filter["Routing filter"]
  node_strategies["Routing strategies"]
  node_registry["Strategy registry"]
  node_poller["Metric poller"]
  node_metric_cache["Metric cache<br/>[MetricCache.java]"]
  node_score["Scoring and normalization"]
  node_adaptive_config["Adaptive configuration"]
  node_admin["Routing admin API"]
  node_connection_tracker["Connection tracking"]
  node_snapshot["Instance metric snapshot"]
end

subgraph group_workers["Workers and faults"]
  node_workers["Worker service"]
  node_worker_metrics["Worker telemetry"]
  node_chaos_api["Chaos controls"]
  node_chaos_service["Fault injection<br/>[ChaosService.java]"]
  node_chaos_filter["Chaos request filter<br/>[ChaosFilter.java]"]
end

subgraph group_evaluation["Benchmark evaluation"]
  node_orchestrator["Experiment orchestrator<br/>[orchestrator.py]"]
  node_simulator["Benchmark simulator"]
  node_scenario_suite["Seven load scenarios"]
  node_calibration["Host calibration<br/>[calibration.py]"]
  node_statistics["Statistical analysis<br/>[compute_stats.py]"]
end

subgraph group_research_ui["Research frontend"]
  node_benchmark_ui["Benchmark explorer"]
  node_visualizations["Visualizations<br/>[Visualizations.jsx]"]
  node_hypotheses["Hypothesis testing"]
  node_live_console["Live console<br/>[LiveConsole.jsx]"]
  node_paper_viewer["Paper viewer<br/>[PaperViewer.jsx]"]
  node_dashboard["Research dashboard<br/>[App.jsx]"]
end

subgraph group_discovery["Service discovery"]
  node_service_registry["Service registry"]
end

node_client(("Traffic clients"))
node_operator(("Research operator"))

node_client -->|"sends traffic"| node_gateway_filter
node_gateway_filter -.->|"discovers instances"| node_service_registry
node_gateway_filter -->|"selects instance"| node_strategies
node_gateway_filter -->|"gets active strategy"| node_registry
node_gateway_filter -->|"reads metrics"| node_metric_cache
node_gateway_filter -->|"tracks connections"| node_connection_tracker
node_gateway_filter -->|"forwards request"| node_workers
node_poller -->|"scrapes telemetry"| node_workers
node_poller -->|"scores snapshots"| node_score
node_poller -->|"updates snapshots"| node_metric_cache
node_poller -->|"reads connections"| node_connection_tracker
node_score -->|"uses thresholds"| node_adaptive_config
node_score -->|"scores metrics"| node_snapshot
node_metric_cache -->|"stores snapshots"| node_snapshot
node_registry -->|"registers implementations"| node_strategies
node_admin -->|"switches strategy"| node_registry
node_admin -->|"reports telemetry"| node_metric_cache
node_admin -->|"sets instance weights"| node_connection_tracker
node_workers -->|"records workload"| node_worker_metrics
node_chaos_api -->|"configures faults"| node_chaos_service
node_chaos_filter -.->|"applies injected faults"| node_chaos_service
node_worker_metrics -.->|"exports scrape metrics"| node_poller
node_workers -.->|"registers instances"| node_service_registry
node_operator -->|"runs experiments"| node_orchestrator
node_orchestrator -->|"executes scenarios"| node_scenario_suite
node_orchestrator -->|"simulates runs"| node_simulator
node_orchestrator -->|"calibrates host"| node_calibration
node_orchestrator -->|"configures routing"| node_gateway_filter
node_orchestrator -->|"injects worker faults"| node_chaos_api
node_orchestrator -.->|"produces experiment data"| node_statistics
node_operator -->|"explores results"| node_dashboard
node_dashboard -->|"renders tab"| node_benchmark_ui
node_dashboard -->|"renders tab"| node_visualizations
node_dashboard -->|"renders tab"| node_hypotheses
node_dashboard -->|"renders tab"| node_live_console
node_dashboard -->|"renders tab"| node_paper_viewer
node_dashboard -->|"checks gateway status"| node_admin

click node_gateway_filter "https://github.com/manjeetjay/adaptive-lb-m/blob/main/gateway/src/main/java/com/alb/gateway/routing/filter/AdaptiveRoutingFilter.java"
click node_strategies "https://github.com/manjeetjay/adaptive-lb-m/tree/main/gateway/src/main/java/com/alb/gateway/routing/strategy"
click node_registry "https://github.com/manjeetjay/adaptive-lb-m/blob/main/gateway/src/main/java/com/alb/gateway/routing/engine/RoutingStrategyRegistry.java"
click node_poller "https://github.com/manjeetjay/adaptive-lb-m/blob/main/gateway/src/main/java/com/alb/gateway/routing/adaptive/MetricPollerService.java"
click node_metric_cache "https://github.com/manjeetjay/adaptive-lb-m/blob/main/gateway/src/main/java/com/alb/gateway/routing/adaptive/MetricCache.java"
click node_score "https://github.com/manjeetjay/adaptive-lb-m/blob/main/gateway/src/main/java/com/alb/gateway/routing/adaptive/CompositeScoreCalculator.java"
click node_adaptive_config "https://github.com/manjeetjay/adaptive-lb-m/blob/main/gateway/src/main/java/com/alb/gateway/routing/adaptive/AdaptiveRoutingConfig.java"
click node_admin "https://github.com/manjeetjay/adaptive-lb-m/blob/main/gateway/src/main/java/com/alb/gateway/admin/RoutingAdminController.java"
click node_connection_tracker "https://github.com/manjeetjay/adaptive-lb-m/blob/main/gateway/src/main/java/com/alb/gateway/routing/engine/InstanceConnectionTracker.java"
click node_snapshot "https://github.com/manjeetjay/adaptive-lb-m/blob/main/gateway/src/main/java/com/alb/gateway/routing/model/InstanceMetricsSnapshot.java"
click node_workers "https://github.com/manjeetjay/adaptive-lb-m/blob/main/demo-worker/src/main/java/com/alb/worker/controller/WorkerController.java"
click node_worker_metrics "https://github.com/manjeetjay/adaptive-lb-m/blob/main/demo-worker/src/main/java/com/alb/worker/metrics/WorkerMetricsService.java"
click node_chaos_api "https://github.com/manjeetjay/adaptive-lb-m/blob/main/demo-worker/src/main/java/com/alb/worker/chaos/ChaosController.java"
click node_chaos_service "https://github.com/manjeetjay/adaptive-lb-m/blob/main/demo-worker/src/main/java/com/alb/worker/chaos/ChaosService.java"
click node_chaos_filter "https://github.com/manjeetjay/adaptive-lb-m/blob/main/demo-worker/src/main/java/com/alb/worker/chaos/ChaosFilter.java"
click node_service_registry "https://github.com/manjeetjay/adaptive-lb-m/blob/main/service-registry/src/main/java/com/alb/registry/ServiceRegistryApplication.java"
click node_orchestrator "https://github.com/manjeetjay/adaptive-lb-m/blob/main/experiments/orchestrator.py"
click node_simulator "https://github.com/manjeetjay/adaptive-lb-m/blob/main/experiments/benchmark_simulator.py"
click node_scenario_suite "https://github.com/manjeetjay/adaptive-lb-m/tree/main/experiments/scenarios"
click node_calibration "https://github.com/manjeetjay/adaptive-lb-m/blob/main/experiments/calibration.py"
click node_statistics "https://github.com/manjeetjay/adaptive-lb-m/blob/main/experiments/analysis/compute_stats.py"
click node_benchmark_ui "https://github.com/manjeetjay/adaptive-lb-m/blob/main/frontend/src/components/BenchmarkExplorer.jsx"
click node_visualizations "https://github.com/manjeetjay/adaptive-lb-m/blob/main/frontend/src/components/Visualizations.jsx"
click node_hypotheses "https://github.com/manjeetjay/adaptive-lb-m/blob/main/frontend/src/components/HypothesisTesting.jsx"
click node_live_console "https://github.com/manjeetjay/adaptive-lb-m/blob/main/frontend/src/components/LiveConsole.jsx"
click node_paper_viewer "https://github.com/manjeetjay/adaptive-lb-m/blob/main/frontend/src/components/PaperViewer.jsx"
click node_dashboard "https://github.com/manjeetjay/adaptive-lb-m/blob/main/frontend/src/App.jsx"

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_gateway_filter,node_strategies,node_registry,node_poller,node_metric_cache,node_score,node_adaptive_config,node_admin,node_connection_tracker,node_snapshot,node_client toneBlue
class node_workers,node_worker_metrics,node_chaos_api,node_chaos_service,node_chaos_filter toneAmber
class node_orchestrator,node_simulator,node_scenario_suite,node_calibration,node_statistics toneMint
class node_benchmark_ui,node_visualizations,node_hypotheses,node_live_console,node_paper_viewer,node_dashboard toneRose
class node_service_registry,node_operator toneIndigo
```

## Components

### Gateway routing

- [Routing filter](https://github.com/manjeetjay/adaptive-lb-m/blob/main/gateway/src/main/java/com/alb/gateway/routing/filter/AdaptiveRoutingFilter.java): `gateway/src/main/java/com/alb/gateway/routing/filter/AdaptiveRoutingFilter.java`
- [Routing strategies](https://github.com/manjeetjay/adaptive-lb-m/tree/main/gateway/src/main/java/com/alb/gateway/routing/strategy): `gateway/src/main/java/com/alb/gateway/routing/strategy`
- [Strategy registry](https://github.com/manjeetjay/adaptive-lb-m/blob/main/gateway/src/main/java/com/alb/gateway/routing/engine/RoutingStrategyRegistry.java): `gateway/src/main/java/com/alb/gateway/routing/engine/RoutingStrategyRegistry.java`
- [Metric poller](https://github.com/manjeetjay/adaptive-lb-m/blob/main/gateway/src/main/java/com/alb/gateway/routing/adaptive/MetricPollerService.java): `gateway/src/main/java/com/alb/gateway/routing/adaptive/MetricPollerService.java`
- [Metric cache](https://github.com/manjeetjay/adaptive-lb-m/blob/main/gateway/src/main/java/com/alb/gateway/routing/adaptive/MetricCache.java): `gateway/src/main/java/com/alb/gateway/routing/adaptive/MetricCache.java`
- [Scoring and normalization](https://github.com/manjeetjay/adaptive-lb-m/blob/main/gateway/src/main/java/com/alb/gateway/routing/adaptive/CompositeScoreCalculator.java): `gateway/src/main/java/com/alb/gateway/routing/adaptive/CompositeScoreCalculator.java`
- [Adaptive configuration](https://github.com/manjeetjay/adaptive-lb-m/blob/main/gateway/src/main/java/com/alb/gateway/routing/adaptive/AdaptiveRoutingConfig.java): `gateway/src/main/java/com/alb/gateway/routing/adaptive/AdaptiveRoutingConfig.java`
- [Routing admin API](https://github.com/manjeetjay/adaptive-lb-m/blob/main/gateway/src/main/java/com/alb/gateway/admin/RoutingAdminController.java): `gateway/src/main/java/com/alb/gateway/admin/RoutingAdminController.java`
- [Connection tracking](https://github.com/manjeetjay/adaptive-lb-m/blob/main/gateway/src/main/java/com/alb/gateway/routing/engine/InstanceConnectionTracker.java): `gateway/src/main/java/com/alb/gateway/routing/engine/InstanceConnectionTracker.java`
- [Instance metric snapshot](https://github.com/manjeetjay/adaptive-lb-m/blob/main/gateway/src/main/java/com/alb/gateway/routing/model/InstanceMetricsSnapshot.java): `gateway/src/main/java/com/alb/gateway/routing/model/InstanceMetricsSnapshot.java`

### Workers and faults

- [Worker service](https://github.com/manjeetjay/adaptive-lb-m/blob/main/demo-worker/src/main/java/com/alb/worker/controller/WorkerController.java): `demo-worker/src/main/java/com/alb/worker/controller/WorkerController.java`
- [Worker telemetry](https://github.com/manjeetjay/adaptive-lb-m/blob/main/demo-worker/src/main/java/com/alb/worker/metrics/WorkerMetricsService.java): `demo-worker/src/main/java/com/alb/worker/metrics/WorkerMetricsService.java`
- [Chaos controls](https://github.com/manjeetjay/adaptive-lb-m/blob/main/demo-worker/src/main/java/com/alb/worker/chaos/ChaosController.java): `demo-worker/src/main/java/com/alb/worker/chaos/ChaosController.java`
- [Fault injection](https://github.com/manjeetjay/adaptive-lb-m/blob/main/demo-worker/src/main/java/com/alb/worker/chaos/ChaosService.java): `demo-worker/src/main/java/com/alb/worker/chaos/ChaosService.java`
- [Chaos request filter](https://github.com/manjeetjay/adaptive-lb-m/blob/main/demo-worker/src/main/java/com/alb/worker/chaos/ChaosFilter.java): `demo-worker/src/main/java/com/alb/worker/chaos/ChaosFilter.java`

### Benchmark evaluation

- [Experiment orchestrator](https://github.com/manjeetjay/adaptive-lb-m/blob/main/experiments/orchestrator.py): `experiments/orchestrator.py`
- [Benchmark simulator](https://github.com/manjeetjay/adaptive-lb-m/blob/main/experiments/benchmark_simulator.py): `experiments/benchmark_simulator.py`
- [Seven load scenarios](https://github.com/manjeetjay/adaptive-lb-m/tree/main/experiments/scenarios): `experiments/scenarios`
- [Host calibration](https://github.com/manjeetjay/adaptive-lb-m/blob/main/experiments/calibration.py): `experiments/calibration.py`
- [Statistical analysis](https://github.com/manjeetjay/adaptive-lb-m/blob/main/experiments/analysis/compute_stats.py): `experiments/analysis/compute_stats.py`

### Research frontend

- [Benchmark explorer](https://github.com/manjeetjay/adaptive-lb-m/blob/main/frontend/src/components/BenchmarkExplorer.jsx): `frontend/src/components/BenchmarkExplorer.jsx`
- [Visualizations](https://github.com/manjeetjay/adaptive-lb-m/blob/main/frontend/src/components/Visualizations.jsx): `frontend/src/components/Visualizations.jsx`
- [Hypothesis testing](https://github.com/manjeetjay/adaptive-lb-m/blob/main/frontend/src/components/HypothesisTesting.jsx): `frontend/src/components/HypothesisTesting.jsx`
- [Live console](https://github.com/manjeetjay/adaptive-lb-m/blob/main/frontend/src/components/LiveConsole.jsx): `frontend/src/components/LiveConsole.jsx`
- [Paper viewer](https://github.com/manjeetjay/adaptive-lb-m/blob/main/frontend/src/components/PaperViewer.jsx): `frontend/src/components/PaperViewer.jsx`
- [Research dashboard](https://github.com/manjeetjay/adaptive-lb-m/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`

### Service discovery

- [Service registry](https://github.com/manjeetjay/adaptive-lb-m/blob/main/service-registry/src/main/java/com/alb/registry/ServiceRegistryApplication.java): `service-registry/src/main/java/com/alb/registry/ServiceRegistryApplication.java`

### Other components

- **Traffic clients**
- **Research operator**

## Connections

- Traffic clients → Routing filter: sends traffic
- Routing filter → Service registry: discovers instances
- Routing filter → Routing strategies: selects instance (evidence: `gateway/src/main/java/com/alb/gateway/routing/filter/AdaptiveRoutingFilter.java`)
- Routing filter → Strategy registry: gets active strategy (evidence: `gateway/src/main/java/com/alb/gateway/routing/filter/AdaptiveRoutingFilter.java`)
- Routing filter → Metric cache: reads metrics (evidence: `gateway/src/main/java/com/alb/gateway/routing/filter/AdaptiveRoutingFilter.java`)
- Routing filter → Connection tracking: tracks connections (evidence: `gateway/src/main/java/com/alb/gateway/routing/filter/AdaptiveRoutingFilter.java`)
- Routing filter → Worker service: forwards request
- Metric poller → Worker service: scrapes telemetry (evidence: `gateway/src/main/java/com/alb/gateway/routing/adaptive/MetricPollerService.java`)
- Metric poller → Scoring and normalization: scores snapshots (evidence: `gateway/src/main/java/com/alb/gateway/routing/adaptive/MetricPollerService.java`)
- Metric poller → Metric cache: updates snapshots (evidence: `gateway/src/main/java/com/alb/gateway/routing/adaptive/MetricPollerService.java`)
- Metric poller → Connection tracking: reads connections (evidence: `gateway/src/main/java/com/alb/gateway/routing/adaptive/MetricPollerService.java`)
- Scoring and normalization → Adaptive configuration: uses thresholds (evidence: `gateway/src/main/java/com/alb/gateway/routing/adaptive/CompositeScoreCalculator.java`)
- Scoring and normalization → Instance metric snapshot: scores metrics (evidence: `gateway/src/main/java/com/alb/gateway/routing/adaptive/CompositeScoreCalculator.java`)
- Metric cache → Instance metric snapshot: stores snapshots (evidence: `gateway/src/main/java/com/alb/gateway/routing/adaptive/MetricCache.java`)
- Strategy registry → Routing strategies: registers implementations (evidence: `gateway/src/main/java/com/alb/gateway/routing/engine/RoutingStrategyRegistry.java`)
- Routing admin API → Strategy registry: switches strategy (evidence: `gateway/src/main/java/com/alb/gateway/admin/RoutingAdminController.java`)
- Routing admin API → Metric cache: reports telemetry (evidence: `gateway/src/main/java/com/alb/gateway/admin/RoutingAdminController.java`)
- Routing admin API → Connection tracking: sets instance weights (evidence: `gateway/src/main/java/com/alb/gateway/admin/RoutingAdminController.java`)
- Worker service → Worker telemetry: records workload (evidence: `demo-worker/src/main/java/com/alb/worker/controller/WorkerController.java`)
- Chaos controls → Fault injection: configures faults (evidence: `demo-worker/src/main/java/com/alb/worker/chaos/ChaosController.java`)
- Chaos request filter → Fault injection: applies injected faults
- Worker telemetry → Metric poller: exports scrape metrics
- Worker service → Service registry: registers instances
- Research operator → Experiment orchestrator: runs experiments (evidence: `experiments/orchestrator.py`)
- Experiment orchestrator → Seven load scenarios: executes scenarios (evidence: `experiments/orchestrator.py`)
- Experiment orchestrator → Benchmark simulator: simulates runs (evidence: `experiments/orchestrator.py`)
- Experiment orchestrator → Host calibration: calibrates host (evidence: `experiments/orchestrator.py`)
- Experiment orchestrator → Routing filter: configures routing (evidence: `experiments/orchestrator.py`)
- Experiment orchestrator → Chaos controls: injects worker faults (evidence: `experiments/orchestrator.py`)
- Experiment orchestrator → Statistical analysis: produces experiment data
- Research operator → Research dashboard: explores results (evidence: `frontend/src/App.jsx`)
- Research dashboard → Benchmark explorer: renders tab (evidence: `frontend/src/App.jsx`)
- Research dashboard → Visualizations: renders tab (evidence: `frontend/src/App.jsx`)
- Research dashboard → Hypothesis testing: renders tab (evidence: `frontend/src/App.jsx`)
- Research dashboard → Live console: renders tab (evidence: `frontend/src/App.jsx`)
- Research dashboard → Paper viewer: renders tab (evidence: `frontend/src/App.jsx`)
- Research dashboard → Routing admin API: checks gateway status (evidence: `frontend/src/App.jsx`)