# paultitus0702/saksham- architecture

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

- Interactive diagram: https://gitdiagram.com/paultitus0702/saksham-
- Repository: https://github.com/paultitus0702/saksham-

## Overview

SAKSHAM analyzes and solves LP/MPS optimization models, then independently checks solutions and emits certificates. The principal workflow is upload or benchmark input → parse and validate → structural/numerical analysis and strategy recommendation → HiGHS solve → verification and certificate. The dashboard presents system status, solve results, pipeline views, and Netlib benchmarks. The README documents synthetic refinery benchmarks and Netlib validation, though their runner implementation is not present in the supplied tree. Some edges reflect explicit README or SOURCE INDEX references; unsampled relationships are omitted or marked unverified.

Main entry points: [`engine/saksham/pipeline/runner.py`](https://github.com/paultitus0702/saksham-/blob/master/engine/saksham/pipeline/runner.py) (Pipeline Runner), [`frontend/src/App.tsx`](https://github.com/paultitus0702/saksham-/blob/master/frontend/src/App.tsx) (Dashboard App), [`backend/app/api/api_router.py`](https://github.com/paultitus0702/saksham-/blob/master/backend/app/api/api_router.py) (API Routes), [`engine/saksham/parser/mps_parser.py`](https://github.com/paultitus0702/saksham-/blob/master/engine/saksham/parser/mps_parser.py) (MPS Parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Dashboard"]
  node_dashboard["Dashboard App<br/>[App.tsx]"]
  node_api_client["API Client<br/>[client.ts]"]
  node_pipeline_view["Pipeline Views"]
  node_benchmark_view["Benchmark View<br/>[BenchmarkSuite.tsx]"]
end

subgraph group_service["API Service"]
  node_backend["FastAPI Service<br/>[main.py]"]
  node_api_router["API Routes<br/>[api_router.py]"]
end

subgraph group_model["Model Analysis"]
  node_lp_parser["LP Parser<br/>[lp_parser.py]"]
  node_mps_parser["MPS Parser<br/>[mps_parser.py]"]
  node_cir["Canonical Model<br/>[model.py]"]
  node_validator["Model Validator<br/>[validator.py]"]
  node_fingerprint["Structural Fingerprint<br/>[analyzer.py]"]
  node_isg["Structure Graph<br/>[graph_builder.py]"]
  node_health["Numerical Health<br/>[conditioner.py]"]
  node_strategy["Strategy Recommender<br/>[recommender.py]"]
end

subgraph group_solve["Solve and Assurance"]
  node_pipeline["Pipeline Runner<br/>[runner.py]"]
  node_solver_contract["Solver Contract<br/>[base.py]"]
  node_solver_registry["Solver Registry<br/>[registry.py]"]
  node_highs["HiGHS Backend<br/>[highs_backend.py]"]
  node_verifier["SAKSHI Verifier<br/>[verifier.py]"]
  node_certificate["Certificate Builder<br/>[cert_builder.py]"]
end

subgraph group_benchmark["Benchmark Inputs"]
  node_netlib["Netlib Runner"]
  node_refinery["Refinery Scenarios<br/>[refinery.py]"]
end

node_user(("Engineer"))

node_user -->|"uses"| node_dashboard
node_dashboard -->|"requests status"| node_api_client
node_dashboard -->|"renders results"| node_pipeline_view
node_dashboard -->|"renders benchmarks"| node_benchmark_view
node_api_client -->|"calls HTTP API"| node_api_router
node_backend -->|"registers routes"| node_api_router
node_api_router -->|"runs solve"| node_pipeline
node_api_router -->|"runs benchmark"| node_netlib
node_pipeline -->|"dispatches LP"| node_lp_parser
node_pipeline -->|"dispatches MPS"| node_mps_parser
node_lp_parser -->|"builds model"| node_cir
node_mps_parser -->|"builds model"| node_cir
node_pipeline -->|"validates model"| node_validator
node_mps_parser -->|"validates model"| node_validator
node_pipeline -->|"analyzes structure"| node_fingerprint
node_pipeline -->|"builds graph"| node_isg
node_pipeline -->|"checks numerics"| node_health
node_pipeline -->|"recommends strategy"| node_strategy
node_pipeline -->|"selects solver"| node_solver_registry
node_solver_registry -->|"registers backend"| node_highs
node_highs -->|"implements contract"| node_solver_contract
node_pipeline -->|"checks solution"| node_verifier
node_pipeline -->|"builds certificate"| node_certificate
node_netlib -.->|"uses shared pipeline"| node_pipeline
node_refinery -.->|"benchmark input"| node_pipeline

click node_dashboard "https://github.com/paultitus0702/saksham-/blob/master/frontend/src/App.tsx"
click node_api_client "https://github.com/paultitus0702/saksham-/blob/master/frontend/src/api/client.ts"
click node_pipeline_view "https://github.com/paultitus0702/saksham-/blob/master/frontend/src/components/PipelineModuleView.tsx"
click node_benchmark_view "https://github.com/paultitus0702/saksham-/blob/master/frontend/src/components/BenchmarkSuite.tsx"
click node_backend "https://github.com/paultitus0702/saksham-/blob/master/backend/app/main.py"
click node_api_router "https://github.com/paultitus0702/saksham-/blob/master/backend/app/api/api_router.py"
click node_pipeline "https://github.com/paultitus0702/saksham-/blob/master/engine/saksham/pipeline/runner.py"
click node_lp_parser "https://github.com/paultitus0702/saksham-/blob/master/engine/saksham/parser/lp_parser.py"
click node_mps_parser "https://github.com/paultitus0702/saksham-/blob/master/engine/saksham/parser/mps_parser.py"
click node_cir "https://github.com/paultitus0702/saksham-/blob/master/engine/saksham/canonical/model.py"
click node_validator "https://github.com/paultitus0702/saksham-/blob/master/engine/saksham/canonical/validator.py"
click node_fingerprint "https://github.com/paultitus0702/saksham-/blob/master/engine/saksham/fingerprint/analyzer.py"
click node_isg "https://github.com/paultitus0702/saksham-/blob/master/engine/saksham/isg/graph_builder.py"
click node_health "https://github.com/paultitus0702/saksham-/blob/master/engine/saksham/health/conditioner.py"
click node_strategy "https://github.com/paultitus0702/saksham-/blob/master/engine/saksham/strategy/recommender.py"
click node_solver_contract "https://github.com/paultitus0702/saksham-/blob/master/engine/saksham/solvers/base.py"
click node_solver_registry "https://github.com/paultitus0702/saksham-/blob/master/engine/saksham/solvers/registry.py"
click node_highs "https://github.com/paultitus0702/saksham-/blob/master/engine/saksham/solvers/highs_backend.py"
click node_verifier "https://github.com/paultitus0702/saksham-/blob/master/engine/saksham/sakshi/verifier.py"
click node_certificate "https://github.com/paultitus0702/saksham-/blob/master/engine/saksham/certificate/cert_builder.py"
click node_netlib "https://github.com/paultitus0702/saksham-/tree/master/engine/saksham"
click node_refinery "https://github.com/paultitus0702/saksham-/blob/master/engine/saksham/scenarios/refinery.py"

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_dashboard,node_api_client,node_pipeline_view,node_benchmark_view toneBlue
class node_backend,node_api_router toneAmber
class node_lp_parser,node_mps_parser,node_cir,node_validator,node_fingerprint,node_isg,node_health,node_strategy toneMint
class node_pipeline,node_solver_contract,node_solver_registry,node_highs,node_verifier,node_certificate toneRose
class node_netlib,node_refinery,node_user toneIndigo
```

## Components

### Dashboard

- [Dashboard App](https://github.com/paultitus0702/saksham-/blob/master/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API Client](https://github.com/paultitus0702/saksham-/blob/master/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Pipeline Views](https://github.com/paultitus0702/saksham-/blob/master/frontend/src/components/PipelineModuleView.tsx): `frontend/src/components/PipelineModuleView.tsx`
- [Benchmark View](https://github.com/paultitus0702/saksham-/blob/master/frontend/src/components/BenchmarkSuite.tsx): `frontend/src/components/BenchmarkSuite.tsx`

### API Service

- [FastAPI Service](https://github.com/paultitus0702/saksham-/blob/master/backend/app/main.py): `backend/app/main.py`
- [API Routes](https://github.com/paultitus0702/saksham-/blob/master/backend/app/api/api_router.py): `backend/app/api/api_router.py`

### Model Analysis

- [LP Parser](https://github.com/paultitus0702/saksham-/blob/master/engine/saksham/parser/lp_parser.py): `engine/saksham/parser/lp_parser.py`
- [MPS Parser](https://github.com/paultitus0702/saksham-/blob/master/engine/saksham/parser/mps_parser.py): `engine/saksham/parser/mps_parser.py`
- [Canonical Model](https://github.com/paultitus0702/saksham-/blob/master/engine/saksham/canonical/model.py): `engine/saksham/canonical/model.py`
- [Model Validator](https://github.com/paultitus0702/saksham-/blob/master/engine/saksham/canonical/validator.py): `engine/saksham/canonical/validator.py`
- [Structural Fingerprint](https://github.com/paultitus0702/saksham-/blob/master/engine/saksham/fingerprint/analyzer.py): `engine/saksham/fingerprint/analyzer.py`
- [Structure Graph](https://github.com/paultitus0702/saksham-/blob/master/engine/saksham/isg/graph_builder.py): `engine/saksham/isg/graph_builder.py`
- [Numerical Health](https://github.com/paultitus0702/saksham-/blob/master/engine/saksham/health/conditioner.py): `engine/saksham/health/conditioner.py`
- [Strategy Recommender](https://github.com/paultitus0702/saksham-/blob/master/engine/saksham/strategy/recommender.py): `engine/saksham/strategy/recommender.py`

### Solve and Assurance

- [Pipeline Runner](https://github.com/paultitus0702/saksham-/blob/master/engine/saksham/pipeline/runner.py): `engine/saksham/pipeline/runner.py`
- [Solver Contract](https://github.com/paultitus0702/saksham-/blob/master/engine/saksham/solvers/base.py): `engine/saksham/solvers/base.py`
- [Solver Registry](https://github.com/paultitus0702/saksham-/blob/master/engine/saksham/solvers/registry.py): `engine/saksham/solvers/registry.py`
- [HiGHS Backend](https://github.com/paultitus0702/saksham-/blob/master/engine/saksham/solvers/highs_backend.py): `engine/saksham/solvers/highs_backend.py`
- [SAKSHI Verifier](https://github.com/paultitus0702/saksham-/blob/master/engine/saksham/sakshi/verifier.py): `engine/saksham/sakshi/verifier.py`
- [Certificate Builder](https://github.com/paultitus0702/saksham-/blob/master/engine/saksham/certificate/cert_builder.py): `engine/saksham/certificate/cert_builder.py`

### Benchmark Inputs

- [Netlib Runner](https://github.com/paultitus0702/saksham-/tree/master/engine/saksham): `engine/saksham`
- [Refinery Scenarios](https://github.com/paultitus0702/saksham-/blob/master/engine/saksham/scenarios/refinery.py): `engine/saksham/scenarios/refinery.py`

### Other components

- **Engineer**

## Connections

- Engineer → Dashboard App: uses (evidence: `frontend/src/App.tsx`)
- Dashboard App → API Client: requests status (evidence: `frontend/src/App.tsx`)
- Dashboard App → Pipeline Views: renders results (evidence: `frontend/src/App.tsx`)
- Dashboard App → Benchmark View: renders benchmarks (evidence: `frontend/src/App.tsx`)
- API Client → API Routes: calls HTTP API (evidence: `frontend/src/api/client.ts`)
- FastAPI Service → API Routes: registers routes (evidence: `backend/app/main.py`)
- API Routes → Pipeline Runner: runs solve (evidence: `backend/app/api/api_router.py`)
- API Routes → Netlib Runner: runs benchmark (evidence: `backend/app/api/api_router.py`)
- Pipeline Runner → LP Parser: dispatches LP (evidence: `engine/saksham/pipeline/runner.py`)
- Pipeline Runner → MPS Parser: dispatches MPS (evidence: `engine/saksham/pipeline/runner.py`)
- LP Parser → Canonical Model: builds model (evidence: `engine/saksham/parser/lp_parser.py`)
- MPS Parser → Canonical Model: builds model (evidence: `engine/saksham/parser/mps_parser.py`)
- Pipeline Runner → Model Validator: validates model (evidence: `engine/saksham/pipeline/runner.py`)
- MPS Parser → Model Validator: validates model (evidence: `engine/saksham/parser/mps_parser.py`)
- Pipeline Runner → Structural Fingerprint: analyzes structure (evidence: `engine/saksham/pipeline/runner.py`)
- Pipeline Runner → Structure Graph: builds graph (evidence: `engine/saksham/pipeline/runner.py`)
- Pipeline Runner → Numerical Health: checks numerics (evidence: `engine/saksham/pipeline/runner.py`)
- Pipeline Runner → Strategy Recommender: recommends strategy (evidence: `engine/saksham/pipeline/runner.py`)
- Pipeline Runner → Solver Registry: selects solver (evidence: `engine/saksham/pipeline/runner.py`)
- Solver Registry → HiGHS Backend: registers backend (evidence: `engine/saksham/solvers/registry.py`)
- HiGHS Backend → Solver Contract: implements contract (evidence: `engine/saksham/solvers/highs_backend.py`)
- Pipeline Runner → SAKSHI Verifier: checks solution (evidence: `engine/saksham/pipeline/runner.py`)
- Pipeline Runner → Certificate Builder: builds certificate (evidence: `engine/saksham/pipeline/runner.py`)
- Netlib Runner → Pipeline Runner: uses shared pipeline (evidence: `engine/saksham/pipeline/__init__.py`)
- Refinery Scenarios → Pipeline Runner: benchmark input
