# ismexar/flex-engine-smartems architecture

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

- Interactive diagram: https://gitdiagram.com/ismexar/flex-engine-smartems
- Repository: https://github.com/ismexar/flex-engine-smartems

## Overview

Flex Engine · SmartEMS is a React/Flask study tool for comparing renewable generation, batteries, grid supply and industrial-load flexibility. Users upload demand and resource data, configure process limits and study dates, choose technology scenarios, then run an optimization and inspect dispatch, KPIs, allocations and exports. The documented backend adapts uploaded files, queues work for an isolated worker, applies the preserved notebook engine and serves result views; the frontend guides configuration and requests those views. Some backend wiring and several frontend capabilities are documented but their implementation excerpts were not supplied.

Main entry points: [`frontend/src/pages`](https://github.com/ismexar/flex-engine-smartems/tree/main/frontend/src/pages) (Workflow screens), [`backend/app/routes/simulations.py`](https://github.com/ismexar/flex-engine-smartems/blob/main/backend/app/routes/simulations.py) (Simulation endpoints), [`backend/app/worker.py`](https://github.com/ismexar/flex-engine-smartems/blob/main/backend/app/worker.py) (Simulation worker), [`backend/app/services/result_service.py`](https://github.com/ismexar/flex-engine-smartems/blob/main/backend/app/services/result_service.py) (Result views and KPIs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Study workflow"]
  node_workflow_ui["Workflow screens"]
  node_upload_parse["Upload parsing<br/>[fileService.js]"]
  node_workflow_state["Workflow state"]
  node_scenario_catalog["Scenario choices<br/>[scenarios.js]"]
  node_simulation_client["Simulation API client"]
end

subgraph group_backend["Simulation backend"]
  node_flask_api["Simulation endpoints<br/>[simulations.py]"]
  node_input_adapter["Input adaptation<br/>[input_service.py]"]
  node_job_queue["Job coordination<br/>[job_service.py]"]
  node_worker["Simulation worker<br/>[worker.py]"]
  node_simulation_store[("Local study files")]
end

subgraph group_engine["Model and results"]
  node_notebook_engine["Optimization engine<br/>[notebook_engine.py]"]
  node_result_service["Result views and KPIs<br/>[result_service.py]"]
  node_notebook_views["Notebook chart helpers<br/>[notebook_views.py]"]
  node_view_cache["View cache<br/>[view_cache.py]"]
end

subgraph group_frontend_results["Results interface"]
  node_results_ui["Results pages<br/>[ResultsPage.jsx]"]
  node_result_fetch["Result view state<br/>[useResultData.js]"]
  node_result_panels["Charts and tables<br/>[ResultPanels.jsx]"]
  node_result_metrics["KPI definitions<br/>[resultMetrics.js]"]
end

node_analyst(("Study analyst"))

node_analyst -->|"configures study"| node_workflow_ui
node_workflow_ui -->|"parses uploads"| node_upload_parse
node_workflow_ui -->|"updates state"| node_workflow_state
node_workflow_ui -->|"selects scenarios"| node_scenario_catalog
node_workflow_ui -->|"starts run"| node_simulation_client
node_simulation_client -->|"sends requests"| node_flask_api
node_flask_api -->|"adapts inputs"| node_input_adapter
node_flask_api -.->|"coordinates jobs"| node_job_queue
node_job_queue -.->|"dispatches work"| node_worker
node_worker -->|"prepares inputs"| node_input_adapter
node_worker -->|"runs optimization"| node_notebook_engine
node_worker -->|"prepares results"| node_result_service
node_worker -.->|"stores artifacts"| node_simulation_store
node_input_adapter -->|"validates config"| node_notebook_engine
node_result_service -->|"computes metrics"| node_notebook_engine
node_result_service -->|"executes chart helpers"| node_notebook_views
node_flask_api -->|"serves result views"| node_result_service
node_flask_api -->|"uses view cache"| node_view_cache
node_view_cache -->|"builds cached view"| node_result_service
node_results_ui -->|"requests data"| node_result_fetch
node_result_fetch -->|"fetches view"| node_simulation_client
node_result_fetch -->|"supplies results"| node_result_panels
node_result_panels -->|"renders KPIs"| node_result_metrics
node_result_panels -->|"shows analysis"| node_analyst

click node_workflow_ui "https://github.com/ismexar/flex-engine-smartems/tree/main/frontend/src/pages"
click node_upload_parse "https://github.com/ismexar/flex-engine-smartems/blob/main/frontend/src/services/fileService.js"
click node_workflow_state "https://github.com/ismexar/flex-engine-smartems/blob/main/frontend/src/state/WorkflowContext.jsx"
click node_scenario_catalog "https://github.com/ismexar/flex-engine-smartems/blob/main/frontend/src/data/scenarios.js"
click node_simulation_client "https://github.com/ismexar/flex-engine-smartems/blob/main/frontend/src/services/simulationService.js"
click node_flask_api "https://github.com/ismexar/flex-engine-smartems/blob/main/backend/app/routes/simulations.py"
click node_input_adapter "https://github.com/ismexar/flex-engine-smartems/blob/main/backend/app/services/input_service.py"
click node_job_queue "https://github.com/ismexar/flex-engine-smartems/blob/main/backend/app/services/job_service.py"
click node_worker "https://github.com/ismexar/flex-engine-smartems/blob/main/backend/app/worker.py"
click node_notebook_engine "https://github.com/ismexar/flex-engine-smartems/blob/main/backend/app/engine/notebook_engine.py"
click node_result_service "https://github.com/ismexar/flex-engine-smartems/blob/main/backend/app/services/result_service.py"
click node_notebook_views "https://github.com/ismexar/flex-engine-smartems/blob/main/backend/app/engine/notebook_views.py"
click node_view_cache "https://github.com/ismexar/flex-engine-smartems/blob/main/backend/app/services/view_cache.py"
click node_results_ui "https://github.com/ismexar/flex-engine-smartems/blob/main/frontend/src/pages/ResultsPage.jsx"
click node_result_fetch "https://github.com/ismexar/flex-engine-smartems/blob/main/frontend/src/state/useResultData.js"
click node_result_panels "https://github.com/ismexar/flex-engine-smartems/blob/main/frontend/src/components/results/ResultPanels.jsx"
click node_result_metrics "https://github.com/ismexar/flex-engine-smartems/blob/main/frontend/src/data/resultMetrics.js"

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_workflow_ui,node_upload_parse,node_workflow_state,node_scenario_catalog,node_simulation_client toneBlue
class node_flask_api,node_input_adapter,node_job_queue,node_worker,node_simulation_store toneAmber
class node_notebook_engine,node_result_service,node_notebook_views,node_view_cache toneMint
class node_results_ui,node_result_fetch,node_result_panels,node_result_metrics toneRose
class node_analyst toneIndigo
```

## Components

### Study workflow

- [Workflow screens](https://github.com/ismexar/flex-engine-smartems/tree/main/frontend/src/pages): `frontend/src/pages`
- [Upload parsing](https://github.com/ismexar/flex-engine-smartems/blob/main/frontend/src/services/fileService.js): `frontend/src/services/fileService.js`
- [Workflow state](https://github.com/ismexar/flex-engine-smartems/blob/main/frontend/src/state/WorkflowContext.jsx): `frontend/src/state/WorkflowContext.jsx`
- [Scenario choices](https://github.com/ismexar/flex-engine-smartems/blob/main/frontend/src/data/scenarios.js): `frontend/src/data/scenarios.js`
- [Simulation API client](https://github.com/ismexar/flex-engine-smartems/blob/main/frontend/src/services/simulationService.js): `frontend/src/services/simulationService.js`

### Simulation backend

- [Simulation endpoints](https://github.com/ismexar/flex-engine-smartems/blob/main/backend/app/routes/simulations.py): `backend/app/routes/simulations.py`
- [Input adaptation](https://github.com/ismexar/flex-engine-smartems/blob/main/backend/app/services/input_service.py): `backend/app/services/input_service.py`
- [Job coordination](https://github.com/ismexar/flex-engine-smartems/blob/main/backend/app/services/job_service.py): `backend/app/services/job_service.py`
- [Simulation worker](https://github.com/ismexar/flex-engine-smartems/blob/main/backend/app/worker.py): `backend/app/worker.py`
- **Local study files**

### Model and results

- [Optimization engine](https://github.com/ismexar/flex-engine-smartems/blob/main/backend/app/engine/notebook_engine.py): `backend/app/engine/notebook_engine.py`
- [Result views and KPIs](https://github.com/ismexar/flex-engine-smartems/blob/main/backend/app/services/result_service.py): `backend/app/services/result_service.py`
- [Notebook chart helpers](https://github.com/ismexar/flex-engine-smartems/blob/main/backend/app/engine/notebook_views.py): `backend/app/engine/notebook_views.py`
- [View cache](https://github.com/ismexar/flex-engine-smartems/blob/main/backend/app/services/view_cache.py): `backend/app/services/view_cache.py`

### Results interface

- [Results pages](https://github.com/ismexar/flex-engine-smartems/blob/main/frontend/src/pages/ResultsPage.jsx): `frontend/src/pages/ResultsPage.jsx`
- [Result view state](https://github.com/ismexar/flex-engine-smartems/blob/main/frontend/src/state/useResultData.js): `frontend/src/state/useResultData.js`
- [Charts and tables](https://github.com/ismexar/flex-engine-smartems/blob/main/frontend/src/components/results/ResultPanels.jsx): `frontend/src/components/results/ResultPanels.jsx`
- [KPI definitions](https://github.com/ismexar/flex-engine-smartems/blob/main/frontend/src/data/resultMetrics.js): `frontend/src/data/resultMetrics.js`

### Other components

- **Study analyst**

## Connections

- Study analyst → Workflow screens: configures study (evidence: `README.md`)
- Workflow screens → Upload parsing: parses uploads (evidence: `frontend/src/pages/InputDataPage.jsx`)
- Workflow screens → Workflow state: updates state (evidence: `frontend/src/state/WorkflowContext.jsx`)
- Workflow screens → Scenario choices: selects scenarios (evidence: `frontend/src/pages/ScenariosPage.jsx`)
- Workflow screens → Simulation API client: starts run (evidence: `frontend/src/pages/FlexibilityPage.jsx`)
- Simulation API client → Simulation endpoints: sends requests (evidence: `frontend/src/services/simulationService.js`)
- Simulation endpoints → Input adaptation: adapts inputs (evidence: `backend/app/routes/simulations.py`)
- Simulation endpoints → Job coordination: coordinates jobs
- Job coordination → Simulation worker: dispatches work (evidence: `backend/app/worker.py`)
- Simulation worker → Input adaptation: prepares inputs (evidence: `backend/app/worker.py`)
- Simulation worker → Optimization engine: runs optimization (evidence: `backend/app/worker.py`)
- Simulation worker → Result views and KPIs: prepares results (evidence: `backend/app/worker.py`)
- Simulation worker → Local study files: stores artifacts
- Input adaptation → Optimization engine: validates config (evidence: `backend/app/services/input_service.py`)
- Result views and KPIs → Optimization engine: computes metrics (evidence: `backend/app/services/result_service.py`)
- Result views and KPIs → Notebook chart helpers: executes chart helpers (evidence: `backend/app/services/result_service.py`)
- Simulation endpoints → Result views and KPIs: serves result views (evidence: `backend/app/routes/simulations.py`)
- Simulation endpoints → View cache: uses view cache (evidence: `backend/app/routes/simulations.py`)
- View cache → Result views and KPIs: builds cached view (evidence: `backend/app/services/view_cache.py`)
- Results pages → Result view state: requests data (evidence: `frontend/src/pages/ResultsPage.jsx`)
- Result view state → Simulation API client: fetches view (evidence: `frontend/src/state/useResultData.js`)
- Result view state → Charts and tables: supplies results (evidence: `frontend/src/pages/ResultsPage.jsx`)
- Charts and tables → KPI definitions: renders KPIs (evidence: `frontend/src/components/results/ResultPanels.jsx`)
- Charts and tables → Study analyst: shows analysis (evidence: `README.md`)
