# saikrishna0817/markov-cero architecture

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

- Interactive diagram: https://gitdiagram.com/saikrishna0817/markov-cero
- Repository: https://github.com/saikrishna0817/markov-cero

## Overview

markov-cero is a C++ mathematical optimization solver, with CLI, Python, and optional authenticated web entry points. Its main workflow is to parse and classify an LP/MPS model, prepare it for solving, dispatch to an appropriate optimization engine, then verify and report the result; supported MILP cases can also export replayable proofs. The README documents this pipeline and the major LP, MILP, QP, nonlinear, GPU, and ML capabilities. Some internal links below follow that documentation because the corresponding implementation was not sampled.

Main entry points: [`src/api/api.cpp`](https://github.com/saikrishna0817/markov-cero/blob/main/src/api/api.cpp) (Solve API), [`src/verify/primal_verifier.cpp`](https://github.com/saikrishna0817/markov-cero/blob/main/src/verify/primal_verifier.cpp) (Result verification), [`src/api/engine_milp.cpp`](https://github.com/saikrishna0817/markov-cero/blob/main/src/api/engine_milp.cpp) (MILP branch and cut), [`web/backend/server.py`](https://github.com/saikrishna0817/markov-cero/blob/main/web/backend/server.py) (Web solve adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI tools"]
  node_python["Python binding<br/>[bindings.cpp]"]
  node_webapp["Web workspace<br/>[App.tsx]"]
  node_webserver["Web solve adapter<br/>[server.py]"]
end

subgraph group_preparation["Model preparation"]
  node_api["Solve API<br/>[api.cpp]"]
  node_parsers["LP MPS NLP parsers<br/>[mps.cpp]"]
  node_model["Sparse model<br/>[model.cpp]"]
  node_classification["Model classification<br/>[classifier.cpp]"]
  node_presolve["Presolve scaling canonicalize<br/>[presolve.cpp]"]
end

subgraph group_engines["Solve engines"]
  node_lp["LP engines<br/>[engine_lp.cpp]"]
  node_milp["MILP branch and cut<br/>[engine_milp.cpp]"]
  node_parallel["Parallel tree search"]
  node_qp["QP ADMM KKT<br/>[engine_qp.cpp]"]
  node_nonlinear["Nonlinear SQP OA"]
end

subgraph group_trust["Verification and results"]
  node_verify["Result verification"]
  node_proof["MIP proof replay<br/>[mip_proof.cpp]"]
  node_report["JSON results<br/>[json_output.hpp]"]
end

subgraph group_extensions["Specialized capabilities"]
  node_gpu["GPU kernels<br/>[pdhg_solver.cpp]"]
  node_ml["ML branching scorer<br/>[onnx_scorer.cpp]"]
  node_refinery["Refinery modeling<br/>[refinery_model.cpp]"]
end

node_user(("Model user"))
node_supabase["Supabase auth"]

node_user -->|"submits model"| node_cli
node_user -->|"submits model"| node_python
node_user -->|"uses workspace"| node_webapp
node_webapp -->|"sends solve request"| node_webserver
node_webserver -.->|"validates session"| node_supabase
node_webserver -->|"runs solver"| node_cli
node_cli -->|"calls solve"| node_api
node_python -->|"exposes solve API"| node_api
node_api -->|"reads model"| node_parsers
node_parsers -->|"builds model"| node_model
node_api -->|"classifies model"| node_classification
node_api -->|"prepares model"| node_presolve
node_api -->|"dispatches LP"| node_lp
node_api -->|"dispatches MILP"| node_milp
node_api -->|"dispatches parallel search"| node_parallel
node_api -->|"dispatches QP"| node_qp
node_api -->|"dispatches nonlinear"| node_nonlinear
node_lp -->|"checks witnesses"| node_verify
node_milp -->|"checks primal"| node_verify
node_parallel -->|"checks primal"| node_verify
node_qp -->|"checks KKT"| node_verify
node_nonlinear -->|"checks local KKT"| node_verify
node_milp -->|"certifies result"| node_proof
node_parallel -->|"certifies result"| node_proof
node_api -->|"formats result"| node_report
node_lp -.->|"uses optional backend"| node_gpu
node_milp -.->|"scores branches"| node_ml
node_user -->|"models refinery decisions"| node_refinery

click node_cli "https://github.com/saikrishna0817/markov-cero/blob/main/apps/markov_cero_solve.cpp"
click node_python "https://github.com/saikrishna0817/markov-cero/blob/main/python/src/bindings.cpp"
click node_webapp "https://github.com/saikrishna0817/markov-cero/blob/main/web/src/App.tsx"
click node_webserver "https://github.com/saikrishna0817/markov-cero/blob/main/web/backend/server.py"
click node_api "https://github.com/saikrishna0817/markov-cero/blob/main/src/api/api.cpp"
click node_parsers "https://github.com/saikrishna0817/markov-cero/blob/main/src/io/mps.cpp"
click node_model "https://github.com/saikrishna0817/markov-cero/blob/main/src/model/model.cpp"
click node_classification "https://github.com/saikrishna0817/markov-cero/blob/main/src/model/classifier.cpp"
click node_presolve "https://github.com/saikrishna0817/markov-cero/blob/main/src/presolve/presolve.cpp"
click node_lp "https://github.com/saikrishna0817/markov-cero/blob/main/src/api/engine_lp.cpp"
click node_milp "https://github.com/saikrishna0817/markov-cero/blob/main/src/api/engine_milp.cpp"
click node_parallel "https://github.com/saikrishna0817/markov-cero/blob/main/src/api/engine_parallel.cpp"
click node_qp "https://github.com/saikrishna0817/markov-cero/blob/main/src/api/engine_qp.cpp"
click node_nonlinear "https://github.com/saikrishna0817/markov-cero/blob/main/src/api/engine_nonlinear.cpp"
click node_gpu "https://github.com/saikrishna0817/markov-cero/blob/main/gpu/src/pdhg_solver.cpp"
click node_ml "https://github.com/saikrishna0817/markov-cero/blob/main/src/milp/ml_branching/onnx_scorer.cpp"
click node_refinery "https://github.com/saikrishna0817/markov-cero/blob/main/src/refinery/refinery_model.cpp"
click node_verify "https://github.com/saikrishna0817/markov-cero/blob/main/src/verify/primal_verifier.cpp"
click node_proof "https://github.com/saikrishna0817/markov-cero/blob/main/src/verify/mip_proof.cpp"
click node_report "https://github.com/saikrishna0817/markov-cero/blob/main/apps/json_output.hpp"

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_cli,node_python,node_webapp,node_webserver,node_user toneBlue
class node_api,node_parsers,node_model,node_classification,node_presolve toneAmber
class node_lp,node_milp,node_parallel,node_qp,node_nonlinear toneMint
class node_verify,node_proof,node_report toneRose
class node_gpu,node_ml,node_refinery,node_supabase toneIndigo
```

## Components

### User interfaces

- [CLI tools](https://github.com/saikrishna0817/markov-cero/blob/main/apps/markov_cero_solve.cpp): `apps/markov_cero_solve.cpp`
- [Python binding](https://github.com/saikrishna0817/markov-cero/blob/main/python/src/bindings.cpp): `python/src/bindings.cpp`
- [Web workspace](https://github.com/saikrishna0817/markov-cero/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Web solve adapter](https://github.com/saikrishna0817/markov-cero/blob/main/web/backend/server.py): `web/backend/server.py`

### Model preparation

- [Solve API](https://github.com/saikrishna0817/markov-cero/blob/main/src/api/api.cpp): `src/api/api.cpp`
- [LP MPS NLP parsers](https://github.com/saikrishna0817/markov-cero/blob/main/src/io/mps.cpp): `src/io/mps.cpp`
- [Sparse model](https://github.com/saikrishna0817/markov-cero/blob/main/src/model/model.cpp): `src/model/model.cpp`
- [Model classification](https://github.com/saikrishna0817/markov-cero/blob/main/src/model/classifier.cpp): `src/model/classifier.cpp`
- [Presolve scaling canonicalize](https://github.com/saikrishna0817/markov-cero/blob/main/src/presolve/presolve.cpp): `src/presolve/presolve.cpp`

### Solve engines

- [LP engines](https://github.com/saikrishna0817/markov-cero/blob/main/src/api/engine_lp.cpp): `src/api/engine_lp.cpp`
- [MILP branch and cut](https://github.com/saikrishna0817/markov-cero/blob/main/src/api/engine_milp.cpp): `src/api/engine_milp.cpp`
- [Parallel tree search](https://github.com/saikrishna0817/markov-cero/blob/main/src/api/engine_parallel.cpp): `src/api/engine_parallel.cpp`
- [QP ADMM KKT](https://github.com/saikrishna0817/markov-cero/blob/main/src/api/engine_qp.cpp): `src/api/engine_qp.cpp`
- [Nonlinear SQP OA](https://github.com/saikrishna0817/markov-cero/blob/main/src/api/engine_nonlinear.cpp): `src/api/engine_nonlinear.cpp`

### Verification and results

- [Result verification](https://github.com/saikrishna0817/markov-cero/blob/main/src/verify/primal_verifier.cpp): `src/verify/primal_verifier.cpp`
- [MIP proof replay](https://github.com/saikrishna0817/markov-cero/blob/main/src/verify/mip_proof.cpp): `src/verify/mip_proof.cpp`
- [JSON results](https://github.com/saikrishna0817/markov-cero/blob/main/apps/json_output.hpp): `apps/json_output.hpp`

### Specialized capabilities

- [GPU kernels](https://github.com/saikrishna0817/markov-cero/blob/main/gpu/src/pdhg_solver.cpp): `gpu/src/pdhg_solver.cpp`
- [ML branching scorer](https://github.com/saikrishna0817/markov-cero/blob/main/src/milp/ml_branching/onnx_scorer.cpp): `src/milp/ml_branching/onnx_scorer.cpp`
- [Refinery modeling](https://github.com/saikrishna0817/markov-cero/blob/main/src/refinery/refinery_model.cpp): `src/refinery/refinery_model.cpp`

### Other components

- **Model user**
- **Supabase auth**

## Connections

- Model user → CLI tools: submits model
- Model user → Python binding: submits model
- Model user → Web workspace: uses workspace
- Web workspace → Web solve adapter: sends solve request
- Web solve adapter → Supabase auth: validates session
- Web solve adapter → CLI tools: runs solver
- CLI tools → Solve API: calls solve
- Python binding → Solve API: exposes solve API
- Solve API → LP MPS NLP parsers: reads model
- LP MPS NLP parsers → Sparse model: builds model
- Solve API → Model classification: classifies model
- Solve API → Presolve scaling canonicalize: prepares model
- Solve API → LP engines: dispatches LP
- Solve API → MILP branch and cut: dispatches MILP
- Solve API → Parallel tree search: dispatches parallel search
- Solve API → QP ADMM KKT: dispatches QP
- Solve API → Nonlinear SQP OA: dispatches nonlinear
- LP engines → Result verification: checks witnesses
- MILP branch and cut → Result verification: checks primal
- Parallel tree search → Result verification: checks primal
- QP ADMM KKT → Result verification: checks KKT
- Nonlinear SQP OA → Result verification: checks local KKT
- MILP branch and cut → MIP proof replay: certifies result
- Parallel tree search → MIP proof replay: certifies result
- Solve API → JSON results: formats result
- LP engines → GPU kernels: uses optional backend
- MILP branch and cut → ML branching scorer: scores branches
- Model user → Refinery modeling: models refinery decisions