# meta/rebalancer architecture

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

- Interactive diagram: https://gitdiagram.com/meta/rebalancer
- Repository: https://github.com/meta/rebalancer

## Overview

Rebalancer is an assignment-optimization library: users define objects, containers, an initial assignment, constraints and goals, select a solving strategy, then receive an assignment result. The README documents local search and MIP solving, with Gurobi, Xpress and HiGHS backends. The repository also contains an Explorer web application for inspecting runs and assignments; sampled routes show its API-to-client dispatch. Some solver and Explorer implementation paths are represented by their exact enclosing directories because their source was not sampled.

Main entry points: [`algopt/rebalancer/explorer/app/app/api/rebalancer`](https://github.com/meta/rebalancer/tree/main/algopt/rebalancer/explorer/app/app/api/rebalancer) (Explorer API routes), [`algopt/lp/factory/ProblemFactory.cpp`](https://github.com/meta/rebalancer/blob/main/algopt/lp/factory/ProblemFactory.cpp) (Backend selection), [`algopt/rebalancer/explorer/cpp_server`](https://github.com/meta/rebalancer/tree/main/algopt/rebalancer/explorer/cpp_server) (Explorer backend), [`algopt/lp/generic/Problem.h`](https://github.com/meta/rebalancer/blob/main/algopt/lp/generic/Problem.h) (Problem API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_model["Problem modeling"]
  node_python_specs["Python specs<br/>[specs.py]"]
  node_problem_api["Problem API<br/>[Problem.h]"]
  node_domain_model["Assignment model"]
end

subgraph group_solve["Solving"]
  node_strategy["Solver strategy"]
  node_local_search["Local search"]
  node_mip_formulation["MIP formulation"]
  node_solution["Assignment result<br/>[ProblemSolver.cpp]"]
end

subgraph group_backends["MIP backends"]
  node_problem_factory["Backend selection<br/>[ProblemFactory.cpp]"]
  node_gurobi["Gurobi adapter<br/>[GurobiProblem.cpp]"]
  node_xpress["Xpress adapter<br/>[XpressProblem.cpp]"]
  node_highs["HiGHS adapter<br/>[HiGHSProblem.cpp]"]
end

subgraph group_explorer["Run Explorer"]
  node_explorer_ui["Run inspection UI"]
  node_explorer_routes["Explorer API routes"]
  node_api_handler["Handle route wrapper<br/>[api-handler.ts]"]
  node_entity_client["Entity queries<br/>[entity.ts]"]
  node_move_client["Move queries<br/>[moves.ts]"]
  node_evaluation_client["Evaluation queries<br/>[evaluation.ts]"]
  node_tree_client["Tree queries<br/>[tree.ts]"]
  node_explorer_backend["Explorer backend"]
end

node_user(("Problem author"))
node_explorer_user(("Explorer user"))

node_user -->|"defines specs"| node_python_specs
node_user -->|"defines problem"| node_problem_api
node_problem_api -.->|"models assignment"| node_domain_model
node_problem_api -->|"selects strategy"| node_strategy
node_strategy -->|"runs local search"| node_local_search
node_strategy -->|"chooses MIP"| node_mip_formulation
node_mip_formulation -.->|"uses backend"| node_problem_factory
node_problem_factory -.->|"selects backend"| node_gurobi
node_problem_factory -.->|"selects backend"| node_xpress
node_problem_factory -.->|"selects backend"| node_highs
node_local_search -->|"produces assignment"| node_solution
node_mip_formulation -->|"produces assignment"| node_solution
node_explorer_user -.->|"inspects runs"| node_explorer_ui
node_explorer_ui -.->|"requests run data"| node_explorer_routes
node_explorer_routes -->|"wraps requests"| node_api_handler
node_explorer_routes -->|"dispatches entity queries"| node_entity_client
node_explorer_routes -->|"dispatches move queries"| node_move_client
node_explorer_routes -->|"dispatches evaluations"| node_evaluation_client
node_explorer_routes -->|"dispatches tree queries"| node_tree_client
node_entity_client -.->|"queries backend"| node_explorer_backend
node_move_client -.->|"queries backend"| node_explorer_backend
node_evaluation_client -.->|"queries backend"| node_explorer_backend
node_tree_client -.->|"queries backend"| node_explorer_backend

click node_python_specs "https://github.com/meta/rebalancer/blob/main/src/rebalancer/specs.py"
click node_problem_api "https://github.com/meta/rebalancer/blob/main/algopt/lp/generic/Problem.h"
click node_domain_model "https://github.com/meta/rebalancer/tree/main/algopt/rebalancer/entities"
click node_strategy "https://github.com/meta/rebalancer/blob/main/algopt/rebalancer/interface/StrategyBuilder.cpp"
click node_local_search "https://github.com/meta/rebalancer/tree/main/algopt/rebalancer/solver"
click node_mip_formulation "https://github.com/meta/rebalancer/tree/main/algopt/lp"
click node_problem_factory "https://github.com/meta/rebalancer/blob/main/algopt/lp/factory/ProblemFactory.cpp"
click node_gurobi "https://github.com/meta/rebalancer/blob/main/algopt/lp/detail/gurobi/GurobiProblem.cpp"
click node_xpress "https://github.com/meta/rebalancer/blob/main/algopt/lp/detail/xpress/XpressProblem.cpp"
click node_highs "https://github.com/meta/rebalancer/blob/main/algopt/lp/detail/highs/HiGHSProblem.cpp"
click node_solution "https://github.com/meta/rebalancer/blob/main/algopt/rebalancer/interface/ProblemSolver.cpp"
click node_explorer_ui "https://github.com/meta/rebalancer/tree/main/algopt/rebalancer/explorer/app/app/(authenticated)/run/%5BrunId%5D"
click node_explorer_routes "https://github.com/meta/rebalancer/tree/main/algopt/rebalancer/explorer/app/app/api/rebalancer"
click node_api_handler "https://github.com/meta/rebalancer/blob/main/algopt/rebalancer/explorer/app/lib/api-handler.ts"
click node_entity_client "https://github.com/meta/rebalancer/blob/main/algopt/rebalancer/explorer/app/lib/client/entity.ts"
click node_move_client "https://github.com/meta/rebalancer/blob/main/algopt/rebalancer/explorer/app/lib/client/moves.ts"
click node_evaluation_client "https://github.com/meta/rebalancer/blob/main/algopt/rebalancer/explorer/app/lib/client/evaluation.ts"
click node_tree_client "https://github.com/meta/rebalancer/blob/main/algopt/rebalancer/explorer/app/lib/client/tree.ts"
click node_explorer_backend "https://github.com/meta/rebalancer/tree/main/algopt/rebalancer/explorer/cpp_server"

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_python_specs,node_problem_api,node_domain_model,node_explorer_user toneBlue
class node_strategy,node_local_search,node_mip_formulation,node_solution toneAmber
class node_problem_factory,node_gurobi,node_xpress,node_highs toneMint
class node_explorer_ui,node_explorer_routes,node_api_handler,node_entity_client,node_move_client,node_evaluation_client,node_tree_client,node_explorer_backend toneRose
class node_user toneIndigo
```

## Components

### Problem modeling

- [Python specs](https://github.com/meta/rebalancer/blob/main/src/rebalancer/specs.py): `src/rebalancer/specs.py`
- [Problem API](https://github.com/meta/rebalancer/blob/main/algopt/lp/generic/Problem.h): `algopt/lp/generic/Problem.h`
- [Assignment model](https://github.com/meta/rebalancer/tree/main/algopt/rebalancer/entities): `algopt/rebalancer/entities`

### Solving

- [Solver strategy](https://github.com/meta/rebalancer/blob/main/algopt/rebalancer/interface/StrategyBuilder.cpp): `algopt/rebalancer/interface/StrategyBuilder.cpp`
- [Local search](https://github.com/meta/rebalancer/tree/main/algopt/rebalancer/solver): `algopt/rebalancer/solver`
- [MIP formulation](https://github.com/meta/rebalancer/tree/main/algopt/lp): `algopt/lp`
- [Assignment result](https://github.com/meta/rebalancer/blob/main/algopt/rebalancer/interface/ProblemSolver.cpp): `algopt/rebalancer/interface/ProblemSolver.cpp`

### MIP backends

- [Backend selection](https://github.com/meta/rebalancer/blob/main/algopt/lp/factory/ProblemFactory.cpp): `algopt/lp/factory/ProblemFactory.cpp`
- [Gurobi adapter](https://github.com/meta/rebalancer/blob/main/algopt/lp/detail/gurobi/GurobiProblem.cpp): `algopt/lp/detail/gurobi/GurobiProblem.cpp`
- [Xpress adapter](https://github.com/meta/rebalancer/blob/main/algopt/lp/detail/xpress/XpressProblem.cpp): `algopt/lp/detail/xpress/XpressProblem.cpp`
- [HiGHS adapter](https://github.com/meta/rebalancer/blob/main/algopt/lp/detail/highs/HiGHSProblem.cpp): `algopt/lp/detail/highs/HiGHSProblem.cpp`

### Run Explorer

- [Run inspection UI](https://github.com/meta/rebalancer/tree/main/algopt/rebalancer/explorer/app/app/(authenticated)/run/%5BrunId%5D): `algopt/rebalancer/explorer/app/app/(authenticated)/run/[runId]`
- [Explorer API routes](https://github.com/meta/rebalancer/tree/main/algopt/rebalancer/explorer/app/app/api/rebalancer): `algopt/rebalancer/explorer/app/app/api/rebalancer`
- [Handle route wrapper](https://github.com/meta/rebalancer/blob/main/algopt/rebalancer/explorer/app/lib/api-handler.ts): `algopt/rebalancer/explorer/app/lib/api-handler.ts`
- [Entity queries](https://github.com/meta/rebalancer/blob/main/algopt/rebalancer/explorer/app/lib/client/entity.ts): `algopt/rebalancer/explorer/app/lib/client/entity.ts`
- [Move queries](https://github.com/meta/rebalancer/blob/main/algopt/rebalancer/explorer/app/lib/client/moves.ts): `algopt/rebalancer/explorer/app/lib/client/moves.ts`
- [Evaluation queries](https://github.com/meta/rebalancer/blob/main/algopt/rebalancer/explorer/app/lib/client/evaluation.ts): `algopt/rebalancer/explorer/app/lib/client/evaluation.ts`
- [Tree queries](https://github.com/meta/rebalancer/blob/main/algopt/rebalancer/explorer/app/lib/client/tree.ts): `algopt/rebalancer/explorer/app/lib/client/tree.ts`
- [Explorer backend](https://github.com/meta/rebalancer/tree/main/algopt/rebalancer/explorer/cpp_server): `algopt/rebalancer/explorer/cpp_server`

### Other components

- **Problem author**
- **Explorer user**

## Connections

- Problem author → Python specs: defines specs
- Problem author → Problem API: defines problem
- Problem API → Assignment model: models assignment
- Problem API → Solver strategy: selects strategy
- Solver strategy → Local search: runs local search
- Solver strategy → MIP formulation: chooses MIP
- MIP formulation → Backend selection: uses backend
- Backend selection → Gurobi adapter: selects backend
- Backend selection → Xpress adapter: selects backend
- Backend selection → HiGHS adapter: selects backend
- Local search → Assignment result: produces assignment
- MIP formulation → Assignment result: produces assignment
- Explorer user → Run inspection UI: inspects runs
- Run inspection UI → Explorer API routes: requests run data
- Explorer API routes → Handle route wrapper: wraps requests (evidence: `algopt/rebalancer/explorer/app/app/api/rebalancer/move-sets/route.ts`)
- Explorer API routes → Entity queries: dispatches entity queries (evidence: `algopt/rebalancer/explorer/app/app/api/rebalancer/typeahead/route.ts`)
- Explorer API routes → Move queries: dispatches move queries (evidence: `algopt/rebalancer/explorer/app/app/api/rebalancer/move-sets/route.ts`)
- Explorer API routes → Evaluation queries: dispatches evaluations (evidence: `algopt/rebalancer/explorer/app/app/api/rebalancer/evaluate-metric-collection/route.ts`)
- Explorer API routes → Tree queries: dispatches tree queries (evidence: `algopt/rebalancer/explorer/app/app/api/rebalancer/tree-node/route.ts`)
- Entity queries → Explorer backend: queries backend
- Move queries → Explorer backend: queries backend
- Evaluation queries → Explorer backend: queries backend
- Tree queries → Explorer backend: queries backend