# project-arbr/arbr-control-plane architecture

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

- Interactive diagram: https://gitdiagram.com/project-arbr/arbr-control-plane
- Repository: https://github.com/project-arbr/arbr-control-plane

## Overview

Arbr is a self-hosted model-optimization and governance control plane. Applications send requests through its compatible gateway, which classifies and routes traffic to providers while recording request outcomes. The console and recommendation engine turn that history into savings opportunities; representative traffic can be evaluated before a human approves a reversible rule, shadow run, or guarded canary. Post-rollout requested-versus-served records support verification. The README documents the product lifecycle and capabilities; some subsystem links below are documented there because their source was not sampled.

Main entry points: [`server/src/gateway/handler.js`](https://github.com/project-arbr/arbr-control-plane/blob/main/server/src/gateway/handler.js) (Request handling), [`web/src/api.js`](https://github.com/project-arbr/arbr-control-plane/blob/main/web/src/api.js) (Console API client), [`web/src/App.jsx`](https://github.com/project-arbr/arbr-control-plane/blob/main/web/src/App.jsx) (Console application), [`server/src/models/RequestRecord.js`](https://github.com/project-arbr/arbr-control-plane/blob/main/server/src/models/RequestRecord.js) (Request records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Traffic gateway"]
  node_gateway_api["OpenAI-compatible gateway<br/>[openaiCompat.js]"]
  node_request_handler["Request handling<br/>[handler.js]"]
  node_classifier["Workload classification<br/>[classifier.js]"]
  node_provider_connections["Provider connections<br/>[connections.js]"]
  node_provider_router["Provider dispatch<br/>[router.js]"]
  node_model_registry["Model and pricing registry<br/>[registry.js]"]
end

subgraph group_insights["Optimization evidence"]
  node_request_logs[("Request records<br/>[RequestRecord.js]")]
  node_analytics["Usage analytics<br/>[aggregate.js]"]
  node_recommendations["Savings recommendations<br/>[engine.js]"]
  node_evaluation["Candidate evaluation<br/>[replay.js]"]
  node_eval_worker["Evaluation worker<br/>[worker.js]"]
end

subgraph group_control["Governance controls"]
  node_routing["Routing policies<br/>[ruleEngine.js]"]
  node_canary["Canary monitoring<br/>[canaryEngine.js]"]
  node_budgets["Budget enforcement<br/>[capEngine.js]"]
  node_settings[("Runtime settings<br/>[Settings.js]")]
  node_mongo_context["Request database context<br/>[context.js]"]
end

subgraph group_console["Operator console"]
  node_console_app["Console application<br/>[App.jsx]"]
  node_console_api["Console API client<br/>[api.js]"]
  node_routing_page["Routing controls<br/>[Routing.jsx]"]
  node_eval_page["Evaluation console<br/>[ModelEvals.jsx]"]
  node_applications_page["Application insights<br/>[Applications.jsx]"]
end

subgraph group_access["Client access"]
  node_clients["Gateway clients<br/>[index.js]"]
end

node_application(("AI application"))
node_providers["Model providers"]

node_application -->|"sends requests"| node_clients
node_application -->|"sends requests"| node_gateway_api
node_clients -->|"calls gateway"| node_gateway_api
node_gateway_api -->|"dispatches requests"| node_request_handler
node_request_handler -->|"classifies workload"| node_classifier
node_request_handler -->|"selects route"| node_routing
node_request_handler -->|"dispatches call"| node_provider_router
node_provider_router -->|"resolves credentials"| node_provider_connections
node_provider_router -->|"calls provider"| node_providers
node_request_handler -->|"prices request"| node_model_registry
node_request_handler -->|"records outcome"| node_request_logs
node_request_logs -.->|"aggregated by"| node_analytics
node_analytics -->|"informs discovery"| node_recommendations
node_request_logs -->|"reads traffic"| node_recommendations
node_recommendations -->|"builds evidence"| node_evaluation
node_evaluation -->|"runs evaluation"| node_eval_worker
node_routing -->|"reads mode"| node_settings
node_request_handler -->|"enforces caps"| node_budgets
node_request_handler -->|"checks canary"| node_canary
node_canary -.->|"uses configuration"| node_settings
node_console_app -->|"loads API"| node_console_api
node_console_app -->|"routes to"| node_routing_page
node_console_app -->|"routes to"| node_eval_page
node_console_api -.->|"configures routing"| node_routing
node_console_api -.->|"manages opportunities"| node_recommendations
node_console_api -.->|"manages evaluations"| node_evaluation
node_console_app -->|"routes to"| node_applications_page
node_applications_page -->|"loads app data"| node_console_api
node_routing_page -->|"updates controls"| node_console_api
node_eval_page -->|"manages evaluations"| node_console_api
node_mongo_context -->|"scopes model access"| node_settings
node_mongo_context -.->|"scopes model access"| node_request_logs

click node_clients "https://github.com/project-arbr/arbr-control-plane/blob/main/clients/js/src/index.js"
click node_gateway_api "https://github.com/project-arbr/arbr-control-plane/blob/main/server/src/gateway/openaiCompat.js"
click node_request_handler "https://github.com/project-arbr/arbr-control-plane/blob/main/server/src/gateway/handler.js"
click node_classifier "https://github.com/project-arbr/arbr-control-plane/blob/main/server/src/classify/classifier.js"
click node_routing "https://github.com/project-arbr/arbr-control-plane/blob/main/server/src/routing/ruleEngine.js"
click node_provider_connections "https://github.com/project-arbr/arbr-control-plane/blob/main/server/src/providers/connections.js"
click node_provider_router "https://github.com/project-arbr/arbr-control-plane/blob/main/server/src/providers/router.js"
click node_request_logs "https://github.com/project-arbr/arbr-control-plane/blob/main/server/src/models/RequestRecord.js"
click node_analytics "https://github.com/project-arbr/arbr-control-plane/blob/main/server/src/analytics/aggregate.js"
click node_recommendations "https://github.com/project-arbr/arbr-control-plane/blob/main/server/src/recommend/engine.js"
click node_evaluation "https://github.com/project-arbr/arbr-control-plane/blob/main/server/src/eval/replay.js"
click node_eval_worker "https://github.com/project-arbr/arbr-control-plane/blob/main/server/src/eval/worker.js"
click node_canary "https://github.com/project-arbr/arbr-control-plane/blob/main/server/src/routing/canaryEngine.js"
click node_budgets "https://github.com/project-arbr/arbr-control-plane/blob/main/server/src/routing/capEngine.js"
click node_model_registry "https://github.com/project-arbr/arbr-control-plane/blob/main/server/src/pricing/registry.js"
click node_settings "https://github.com/project-arbr/arbr-control-plane/blob/main/server/src/models/Settings.js"
click node_mongo_context "https://github.com/project-arbr/arbr-control-plane/blob/main/server/src/db/context.js"
click node_console_app "https://github.com/project-arbr/arbr-control-plane/blob/main/web/src/App.jsx"
click node_console_api "https://github.com/project-arbr/arbr-control-plane/blob/main/web/src/api.js"
click node_routing_page "https://github.com/project-arbr/arbr-control-plane/blob/main/web/src/pages/Routing.jsx"
click node_eval_page "https://github.com/project-arbr/arbr-control-plane/blob/main/web/src/pages/ModelEvals.jsx"
click node_applications_page "https://github.com/project-arbr/arbr-control-plane/blob/main/web/src/pages/Applications.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_api,node_request_handler,node_classifier,node_provider_connections,node_provider_router,node_model_registry toneBlue
class node_request_logs,node_analytics,node_recommendations,node_evaluation,node_eval_worker toneAmber
class node_routing,node_canary,node_budgets,node_settings,node_mongo_context toneMint
class node_console_app,node_console_api,node_routing_page,node_eval_page,node_applications_page toneRose
class node_clients,node_application,node_providers toneIndigo
```

## Components

### Traffic gateway

- [OpenAI-compatible gateway](https://github.com/project-arbr/arbr-control-plane/blob/main/server/src/gateway/openaiCompat.js): `server/src/gateway/openaiCompat.js`
- [Request handling](https://github.com/project-arbr/arbr-control-plane/blob/main/server/src/gateway/handler.js): `server/src/gateway/handler.js`
- [Workload classification](https://github.com/project-arbr/arbr-control-plane/blob/main/server/src/classify/classifier.js): `server/src/classify/classifier.js`
- [Provider connections](https://github.com/project-arbr/arbr-control-plane/blob/main/server/src/providers/connections.js): `server/src/providers/connections.js`
- [Provider dispatch](https://github.com/project-arbr/arbr-control-plane/blob/main/server/src/providers/router.js): `server/src/providers/router.js`
- [Model and pricing registry](https://github.com/project-arbr/arbr-control-plane/blob/main/server/src/pricing/registry.js): `server/src/pricing/registry.js`

### Optimization evidence

- [Request records](https://github.com/project-arbr/arbr-control-plane/blob/main/server/src/models/RequestRecord.js): `server/src/models/RequestRecord.js`
- [Usage analytics](https://github.com/project-arbr/arbr-control-plane/blob/main/server/src/analytics/aggregate.js): `server/src/analytics/aggregate.js`
- [Savings recommendations](https://github.com/project-arbr/arbr-control-plane/blob/main/server/src/recommend/engine.js): `server/src/recommend/engine.js`
- [Candidate evaluation](https://github.com/project-arbr/arbr-control-plane/blob/main/server/src/eval/replay.js): `server/src/eval/replay.js`
- [Evaluation worker](https://github.com/project-arbr/arbr-control-plane/blob/main/server/src/eval/worker.js): `server/src/eval/worker.js`

### Governance controls

- [Routing policies](https://github.com/project-arbr/arbr-control-plane/blob/main/server/src/routing/ruleEngine.js): `server/src/routing/ruleEngine.js`
- [Canary monitoring](https://github.com/project-arbr/arbr-control-plane/blob/main/server/src/routing/canaryEngine.js): `server/src/routing/canaryEngine.js`
- [Budget enforcement](https://github.com/project-arbr/arbr-control-plane/blob/main/server/src/routing/capEngine.js): `server/src/routing/capEngine.js`
- [Runtime settings](https://github.com/project-arbr/arbr-control-plane/blob/main/server/src/models/Settings.js): `server/src/models/Settings.js`
- [Request database context](https://github.com/project-arbr/arbr-control-plane/blob/main/server/src/db/context.js): `server/src/db/context.js`

### Operator console

- [Console application](https://github.com/project-arbr/arbr-control-plane/blob/main/web/src/App.jsx): `web/src/App.jsx`
- [Console API client](https://github.com/project-arbr/arbr-control-plane/blob/main/web/src/api.js): `web/src/api.js`
- [Routing controls](https://github.com/project-arbr/arbr-control-plane/blob/main/web/src/pages/Routing.jsx): `web/src/pages/Routing.jsx`
- [Evaluation console](https://github.com/project-arbr/arbr-control-plane/blob/main/web/src/pages/ModelEvals.jsx): `web/src/pages/ModelEvals.jsx`
- [Application insights](https://github.com/project-arbr/arbr-control-plane/blob/main/web/src/pages/Applications.jsx): `web/src/pages/Applications.jsx`

### Client access

- [Gateway clients](https://github.com/project-arbr/arbr-control-plane/blob/main/clients/js/src/index.js): `clients/js/src/index.js`

### Other components

- **AI application**
- **Model providers**

## Connections

- AI application → Gateway clients: sends requests (evidence: `README.md`)
- AI application → OpenAI-compatible gateway: sends requests (evidence: `README.md`)
- Gateway clients → OpenAI-compatible gateway: calls gateway (evidence: `README.md`)
- OpenAI-compatible gateway → Request handling: dispatches requests (evidence: `server/src/index.js`)
- Request handling → Workload classification: classifies workload (evidence: `server/src/gateway/handler.js`)
- Request handling → Routing policies: selects route (evidence: `server/src/gateway/handler.js`)
- Request handling → Provider dispatch: dispatches call (evidence: `server/src/gateway/handler.js`)
- Provider dispatch → Provider connections: resolves credentials (evidence: `server/src/providers/router.js`)
- Provider dispatch → Model providers: calls provider (evidence: `README.md`)
- Request handling → Model and pricing registry: prices request (evidence: `server/src/gateway/handler.js`)
- Request handling → Request records: records outcome
- Request records → Usage analytics: aggregated by
- Usage analytics → Savings recommendations: informs discovery (evidence: `README.md`)
- Request records → Savings recommendations: reads traffic (evidence: `server/src/recommend/engine.js`)
- Savings recommendations → Candidate evaluation: builds evidence (evidence: `README.md`)
- Candidate evaluation → Evaluation worker: runs evaluation (evidence: `server/src/eval/worker.js`)
- Routing policies → Runtime settings: reads mode (evidence: `server/src/routing/ruleEngine.js`)
- Request handling → Budget enforcement: enforces caps (evidence: `server/src/gateway/handler.js`)
- Request handling → Canary monitoring: checks canary (evidence: `server/src/gateway/handler.js`)
- Canary monitoring → Runtime settings: uses configuration
- Console application → Console API client: loads API (evidence: `web/src/App.jsx`)
- Console application → Routing controls: routes to (evidence: `web/src/App.jsx`)
- Console application → Evaluation console: routes to (evidence: `web/src/App.jsx`)
- Console API client → Routing policies: configures routing
- Console API client → Savings recommendations: manages opportunities
- Console API client → Candidate evaluation: manages evaluations
- Console application → Application insights: routes to (evidence: `web/src/App.jsx`)
- Application insights → Console API client: loads app data (evidence: `web/src/pages/Applications.jsx`)
- Routing controls → Console API client: updates controls (evidence: `web/src/pages/Routing.jsx`)
- Evaluation console → Console API client: manages evaluations (evidence: `web/src/pages/ModelEvals.jsx`)
- Request database context → Runtime settings: scopes model access (evidence: `server/src/models/Settings.js`)
- Request database context → Request records: scopes model access
