# nadjibsalmi/quanta-nexus architecture

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

- Interactive diagram: https://gitdiagram.com/nadjibsalmi/quanta-nexus
- Repository: https://github.com/nadjibsalmi/quanta-nexus

## Overview

QuantaNexus is a research prototype for renewable-microgrid dispatch: it models energy scenarios, forms a constrained dispatch problem, compares classical and QUBO-based methods, and presents results through Python API and dashboard scaffolds. The README documents forecasting, uncertainty, resilience, explanations, and benchmarks as capabilities. Edges follow explicit excerpts, SOURCE INDEX references, or README statements; unsampled implementation details are not assumed, and the TypeScript server is documented only as a scaffold.

Main entry points: [`src/quantanexus/optimization/model.py`](https://github.com/nadjibsalmi/quanta-nexus/blob/main/src/quantanexus/optimization/model.py) (Dispatch formulation), [`src/quantanexus/api/service.py`](https://github.com/nadjibsalmi/quanta-nexus/blob/main/src/quantanexus/api/service.py) (Application services), [`src/quantanexus/core/engine.py`](https://github.com/nadjibsalmi/quanta-nexus/blob/main/src/quantanexus/core/engine.py) (Adaptive engine), [`src/quantanexus/api/app.py`](https://github.com/nadjibsalmi/quanta-nexus/blob/main/src/quantanexus/api/app.py) (Python HTTP API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_energy["Energy inputs"]
  node_twin["Digital twin<br/>[digital_twin.py]"]
  node_energy_model["Energy model<br/>[model.py]"]
  node_forecast["Load forecasting<br/>[load.py]"]
end

subgraph group_decision["Dispatch optimization"]
  node_dispatch_problem["Dispatch formulation<br/>[model.py]"]
  node_engine["Adaptive engine<br/>[engine.py]"]
  node_classical["Classical solvers<br/>[baselines.py]"]
  node_exact_solver["Exact solver<br/>[solver.py]"]
  node_qubo["QUBO encoder<br/>[qubo.py]"]
end

subgraph group_analysis["Evaluation and analytics"]
  node_uncertainty["Uncertainty analysis<br/>[uncertainty.py]"]
  node_resilience["Resilience analysis<br/>[resilience.py]"]
  node_explanations["Decision explanations<br/>[explanations.py]"]
  node_benchmarks["Benchmark suite<br/>[benchmarks.py]"]
end

subgraph group_presentation["API and dashboard"]
  node_api_service["Application services<br/>[service.py]"]
  node_api_adapter["Python HTTP API<br/>[app.py]"]
  node_api_contract["Request schemas<br/>[schemas.py]"]
  node_dashboard["Dashboard<br/>[App.tsx]"]
  node_api_scaffold["TypeScript API scaffold<br/>[app.ts]"]
end

node_planner(("Microgrid planner"))
node_user(("Microgrid planner"))

node_planner -->|"defines scenario"| node_twin
node_twin -->|"provides energy data"| node_energy_model
node_planner -->|"supplies load data"| node_forecast
node_forecast -->|"informs dispatch"| node_dispatch_problem
node_energy_model -->|"defines constraints"| node_dispatch_problem
node_dispatch_problem -->|"is planned by"| node_engine
node_engine -->|"runs exact solve"| node_exact_solver
node_engine -->|"encodes small cases"| node_qubo
node_dispatch_problem -->|"supports baselines"| node_classical
node_dispatch_problem -->|"evaluates forecast errors"| node_uncertainty
node_dispatch_problem -->|"supports resilience studies"| node_resilience
node_dispatch_problem -->|"explains decisions"| node_explanations
node_dispatch_problem -->|"benchmarks methods"| node_benchmarks
node_api_adapter -->|"routes requests"| node_api_service
node_api_adapter -->|"validates requests"| node_api_contract
node_api_service -->|"runs dispatch"| node_engine
node_api_service -->|"generates scenarios"| node_twin
node_api_service -->|"builds explanation"| node_explanations
node_api_service -->|"reads benchmark export"| node_benchmarks
node_user -->|"sends requests"| node_api_adapter
node_user -->|"views results"| node_dashboard
node_dashboard -->|"fetches summary"| node_api_adapter
node_api_scaffold -.->|"serves scaffold API"| node_user

click node_twin "https://github.com/nadjibsalmi/quanta-nexus/blob/main/src/quantanexus/simulation/digital_twin.py"
click node_energy_model "https://github.com/nadjibsalmi/quanta-nexus/blob/main/src/quantanexus/energy/model.py"
click node_forecast "https://github.com/nadjibsalmi/quanta-nexus/blob/main/src/quantanexus/forecasting/load.py"
click node_dispatch_problem "https://github.com/nadjibsalmi/quanta-nexus/blob/main/src/quantanexus/optimization/model.py"
click node_engine "https://github.com/nadjibsalmi/quanta-nexus/blob/main/src/quantanexus/core/engine.py"
click node_classical "https://github.com/nadjibsalmi/quanta-nexus/blob/main/src/quantanexus/optimization/baselines.py"
click node_exact_solver "https://github.com/nadjibsalmi/quanta-nexus/blob/main/src/quantanexus/optimization/solver.py"
click node_qubo "https://github.com/nadjibsalmi/quanta-nexus/blob/main/src/quantanexus/quantum/qubo.py"
click node_uncertainty "https://github.com/nadjibsalmi/quanta-nexus/blob/main/src/quantanexus/optimization/uncertainty.py"
click node_resilience "https://github.com/nadjibsalmi/quanta-nexus/blob/main/src/quantanexus/optimization/resilience.py"
click node_explanations "https://github.com/nadjibsalmi/quanta-nexus/blob/main/src/quantanexus/analytics/explanations.py"
click node_benchmarks "https://github.com/nadjibsalmi/quanta-nexus/blob/main/src/quantanexus/benchmarks.py"
click node_api_service "https://github.com/nadjibsalmi/quanta-nexus/blob/main/src/quantanexus/api/service.py"
click node_api_adapter "https://github.com/nadjibsalmi/quanta-nexus/blob/main/src/quantanexus/api/app.py"
click node_api_contract "https://github.com/nadjibsalmi/quanta-nexus/blob/main/src/quantanexus/api/schemas.py"
click node_dashboard "https://github.com/nadjibsalmi/quanta-nexus/blob/main/artifacts/dashboard/src/App.tsx"
click node_api_scaffold "https://github.com/nadjibsalmi/quanta-nexus/blob/main/artifacts/api-server/src/app.ts"

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_twin,node_energy_model,node_forecast toneBlue
class node_dispatch_problem,node_engine,node_classical,node_exact_solver,node_qubo toneAmber
class node_uncertainty,node_resilience,node_explanations,node_benchmarks toneMint
class node_api_service,node_api_adapter,node_api_contract,node_dashboard,node_api_scaffold toneRose
class node_planner,node_user toneIndigo
```

## Components

### Energy inputs

- [Digital twin](https://github.com/nadjibsalmi/quanta-nexus/blob/main/src/quantanexus/simulation/digital_twin.py): `src/quantanexus/simulation/digital_twin.py`
- [Energy model](https://github.com/nadjibsalmi/quanta-nexus/blob/main/src/quantanexus/energy/model.py): `src/quantanexus/energy/model.py`
- [Load forecasting](https://github.com/nadjibsalmi/quanta-nexus/blob/main/src/quantanexus/forecasting/load.py): `src/quantanexus/forecasting/load.py`

### Dispatch optimization

- [Dispatch formulation](https://github.com/nadjibsalmi/quanta-nexus/blob/main/src/quantanexus/optimization/model.py): `src/quantanexus/optimization/model.py`
- [Adaptive engine](https://github.com/nadjibsalmi/quanta-nexus/blob/main/src/quantanexus/core/engine.py): `src/quantanexus/core/engine.py`
- [Classical solvers](https://github.com/nadjibsalmi/quanta-nexus/blob/main/src/quantanexus/optimization/baselines.py): `src/quantanexus/optimization/baselines.py`
- [Exact solver](https://github.com/nadjibsalmi/quanta-nexus/blob/main/src/quantanexus/optimization/solver.py): `src/quantanexus/optimization/solver.py`
- [QUBO encoder](https://github.com/nadjibsalmi/quanta-nexus/blob/main/src/quantanexus/quantum/qubo.py): `src/quantanexus/quantum/qubo.py`

### Evaluation and analytics

- [Uncertainty analysis](https://github.com/nadjibsalmi/quanta-nexus/blob/main/src/quantanexus/optimization/uncertainty.py): `src/quantanexus/optimization/uncertainty.py`
- [Resilience analysis](https://github.com/nadjibsalmi/quanta-nexus/blob/main/src/quantanexus/optimization/resilience.py): `src/quantanexus/optimization/resilience.py`
- [Decision explanations](https://github.com/nadjibsalmi/quanta-nexus/blob/main/src/quantanexus/analytics/explanations.py): `src/quantanexus/analytics/explanations.py`
- [Benchmark suite](https://github.com/nadjibsalmi/quanta-nexus/blob/main/src/quantanexus/benchmarks.py): `src/quantanexus/benchmarks.py`

### API and dashboard

- [Application services](https://github.com/nadjibsalmi/quanta-nexus/blob/main/src/quantanexus/api/service.py): `src/quantanexus/api/service.py`
- [Python HTTP API](https://github.com/nadjibsalmi/quanta-nexus/blob/main/src/quantanexus/api/app.py): `src/quantanexus/api/app.py`
- [Request schemas](https://github.com/nadjibsalmi/quanta-nexus/blob/main/src/quantanexus/api/schemas.py): `src/quantanexus/api/schemas.py`
- [Dashboard](https://github.com/nadjibsalmi/quanta-nexus/blob/main/artifacts/dashboard/src/App.tsx): `artifacts/dashboard/src/App.tsx`
- [TypeScript API scaffold](https://github.com/nadjibsalmi/quanta-nexus/blob/main/artifacts/api-server/src/app.ts): `artifacts/api-server/src/app.ts`

### Other components

- **Microgrid planner**
- **Microgrid planner**

## Connections

- Microgrid planner → Digital twin: defines scenario (evidence: `README.md`)
- Digital twin → Energy model: provides energy data (evidence: `src/quantanexus/simulation/digital_twin.py`)
- Microgrid planner → Load forecasting: supplies load data (evidence: `README.md`)
- Load forecasting → Dispatch formulation: informs dispatch (evidence: `README.md`)
- Energy model → Dispatch formulation: defines constraints (evidence: `src/quantanexus/optimization/model.py`)
- Dispatch formulation → Adaptive engine: is planned by (evidence: `src/quantanexus/core/engine.py`)
- Adaptive engine → Exact solver: runs exact solve (evidence: `src/quantanexus/core/engine.py`)
- Adaptive engine → QUBO encoder: encodes small cases (evidence: `src/quantanexus/core/engine.py`)
- Dispatch formulation → Classical solvers: supports baselines (evidence: `src/quantanexus/optimization/baselines.py`)
- Dispatch formulation → Uncertainty analysis: evaluates forecast errors (evidence: `src/quantanexus/optimization/uncertainty.py`)
- Dispatch formulation → Resilience analysis: supports resilience studies (evidence: `README.md`)
- Dispatch formulation → Decision explanations: explains decisions (evidence: `src/quantanexus/analytics/explanations.py`)
- Dispatch formulation → Benchmark suite: benchmarks methods (evidence: `src/quantanexus/benchmarks.py`)
- Python HTTP API → Application services: routes requests (evidence: `src/quantanexus/api/app.py`)
- Python HTTP API → Request schemas: validates requests (evidence: `src/quantanexus/api/app.py`)
- Application services → Adaptive engine: runs dispatch (evidence: `src/quantanexus/api/service.py`)
- Application services → Digital twin: generates scenarios (evidence: `src/quantanexus/api/service.py`)
- Application services → Decision explanations: builds explanation (evidence: `src/quantanexus/api/service.py`)
- Application services → Benchmark suite: reads benchmark export (evidence: `src/quantanexus/api/service.py`)
- Microgrid planner → Python HTTP API: sends requests (evidence: `src/quantanexus/api/app.py`)
- Microgrid planner → Dashboard: views results (evidence: `README.md`)
- Dashboard → Python HTTP API: fetches summary (evidence: `artifacts/dashboard/src/App.tsx`)
- TypeScript API scaffold → Microgrid planner: serves scaffold API (evidence: `README.md`)
