# alertxsto/scentinel architecture

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

- Interactive diagram: https://gitdiagram.com/alertxsto/scentinel
- Repository: https://github.com/alertxsto/scentinel

## Overview

Scentinel is a desktop waste-load assessment and RDF-suitability screening application. Operators enter batch composition, moisture, tonnage and age; the assessment pipeline derives gas generation, material balance, route suitability and a recommendation. A separate project workflow configures bin geometry and gas sources, meshes and generates an OpenFOAM case, runs it in Podman, samples concentrations and presents results; projects and immutable run records preserve provenance, while virtual sensors replay simulated readings. Relationships for unsampled subsystems are limited to README statements and SOURCE INDEX references; physical sensor acquisition is not implemented.

Main entry points: [`src/scentinel/ui/main_window.py`](https://github.com/alertxsto/scentinel/blob/master/src/scentinel/ui/main_window.py) (Project editor), [`src/scentinel/core/pipeline.py`](https://github.com/alertxsto/scentinel/blob/master/src/scentinel/core/pipeline.py) (Assessment pipeline), [`src/scentinel/ui/solver_worker.py`](https://github.com/alertxsto/scentinel/blob/master/src/scentinel/ui/solver_worker.py) (Solver worker), [`src/scentinel/core/casegen.py`](https://github.com/alertxsto/scentinel/blob/master/src/scentinel/core/casegen.py) (OpenFOAM case)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop workspace"]
  node_app["App startup<br/>[app.py]"]
  node_home["Home window<br/>[home_window.py]"]
  node_workspace["Docked workspace<br/>[workspace.py]"]
  node_main["Project editor<br/>[main_window.py]"]
  node_setup["Setup panel<br/>[setup_panel.py]"]
  node_translator["Runtime language<br/>[i18n.py]"]
  node_results["Results panel<br/>[results_panel.py]"]
  node_field["Field view<br/>[field_view.py]"]
  node_sensorlab["Virtual sensors<br/>[sensor_lab.py]"]
end

subgraph group_assessment["Waste assessment"]
  node_batch["Batch panel<br/>[batch_panel.py]"]
  node_composition["Waste composition<br/>[composition.py]"]
  node_scenario["Scenario inputs<br/>[scenario.py]"]
  node_gasdata["Gas catalogue<br/>[gas_data.py]"]
  node_generation["Gas generation<br/>[generation.py]"]
  node_pipeline["Assessment pipeline<br/>[pipeline.py]"]
  node_massbalance["Material balance<br/>[massbalance.py]"]
  node_suitability["Route suitability<br/>[suitability.py]"]
  node_recommend["Recommendation<br/>[recommend.py]"]
end

subgraph group_simulation["CFD simulation"]
  node_geometry["Bin geometry<br/>[geometry.py]"]
  node_mesh["Gmsh meshing<br/>[mesh.py]"]
  node_casegen["OpenFOAM case<br/>[casegen.py]"]
  node_worker["Solver worker<br/>[solver_worker.py]"]
  node_runner["Container runner<br/>[runner.py]"]
  node_container["Podman execution<br/>[container.py]"]
  node_post["Probe postprocessing<br/>[post.py]"]
end

subgraph group_persistence["Projects and records"]
  node_project["Project files<br/>[project.py]"]
  node_history[("Run history<br/>[history.py]")]
end

node_operator(("Operator"))

node_operator -->|"opens app"| node_home
node_home -->|"opens workspace"| node_main
node_app -->|"starts"| node_home
node_app -->|"initializes"| node_translator
node_main -->|"edits inputs"| node_setup
node_main -->|"shows panel"| node_batch
node_main -->|"switches language"| node_translator
node_setup -->|"configures"| node_scenario
node_setup -->|"configures"| node_geometry
node_setup -->|"selects gases"| node_gasdata
node_batch -->|"assesses batch"| node_pipeline
node_pipeline -->|"calculates gas"| node_generation
node_pipeline -->|"balances material"| node_massbalance
node_pipeline -->|"scores routes"| node_suitability
node_pipeline -->|"forms recommendation"| node_recommend
node_pipeline -->|"uses composition"| node_composition
node_generation -->|"uses composition"| node_composition
node_main -->|"starts simulation"| node_worker
node_worker -->|"generates mesh"| node_mesh
node_worker -->|"writes case"| node_casegen
node_worker -->|"runs solver"| node_runner
node_worker -->|"samples results"| node_post
node_mesh -->|"meshes geometry"| node_geometry
node_casegen -->|"reads inputs"| node_scenario
node_casegen -->|"reads geometry"| node_geometry
node_casegen -->|"uses gas rates"| node_generation
node_casegen -->|"resolves gases"| node_gasdata
node_runner -->|"executes in"| node_container
node_main -->|"updates results"| node_results
node_results -->|"renders field"| node_field
node_results -->|"reads runs"| node_history
node_main -->|"opens lab"| node_sensorlab
node_sensorlab -->|"reads configuration"| node_project
node_main -->|"saves and loads"| node_project
node_main -->|"records attempts"| node_history
node_worker -.->|"finalizes record"| node_history

click node_app "https://github.com/alertxsto/scentinel/blob/master/src/scentinel/app.py"
click node_home "https://github.com/alertxsto/scentinel/blob/master/src/scentinel/ui/home_window.py"
click node_workspace "https://github.com/alertxsto/scentinel/blob/master/src/scentinel/ui/workspace.py"
click node_main "https://github.com/alertxsto/scentinel/blob/master/src/scentinel/ui/main_window.py"
click node_setup "https://github.com/alertxsto/scentinel/blob/master/src/scentinel/ui/setup_panel.py"
click node_batch "https://github.com/alertxsto/scentinel/blob/master/src/scentinel/ui/batch_panel.py"
click node_translator "https://github.com/alertxsto/scentinel/blob/master/src/scentinel/ui/i18n.py"
click node_composition "https://github.com/alertxsto/scentinel/blob/master/src/scentinel/core/composition.py"
click node_scenario "https://github.com/alertxsto/scentinel/blob/master/src/scentinel/core/scenario.py"
click node_gasdata "https://github.com/alertxsto/scentinel/blob/master/src/scentinel/core/gas_data.py"
click node_generation "https://github.com/alertxsto/scentinel/blob/master/src/scentinel/core/generation.py"
click node_pipeline "https://github.com/alertxsto/scentinel/blob/master/src/scentinel/core/pipeline.py"
click node_massbalance "https://github.com/alertxsto/scentinel/blob/master/src/scentinel/core/massbalance.py"
click node_suitability "https://github.com/alertxsto/scentinel/blob/master/src/scentinel/core/suitability.py"
click node_recommend "https://github.com/alertxsto/scentinel/blob/master/src/scentinel/core/recommend.py"
click node_geometry "https://github.com/alertxsto/scentinel/blob/master/src/scentinel/core/geometry.py"
click node_mesh "https://github.com/alertxsto/scentinel/blob/master/src/scentinel/core/mesh.py"
click node_casegen "https://github.com/alertxsto/scentinel/blob/master/src/scentinel/core/casegen.py"
click node_worker "https://github.com/alertxsto/scentinel/blob/master/src/scentinel/ui/solver_worker.py"
click node_runner "https://github.com/alertxsto/scentinel/blob/master/src/scentinel/core/runner.py"
click node_container "https://github.com/alertxsto/scentinel/blob/master/src/scentinel/core/container.py"
click node_post "https://github.com/alertxsto/scentinel/blob/master/src/scentinel/core/post.py"
click node_results "https://github.com/alertxsto/scentinel/blob/master/src/scentinel/ui/results_panel.py"
click node_field "https://github.com/alertxsto/scentinel/blob/master/src/scentinel/ui/field_view.py"
click node_sensorlab "https://github.com/alertxsto/scentinel/blob/master/src/scentinel/ui/sensor_lab.py"
click node_project "https://github.com/alertxsto/scentinel/blob/master/src/scentinel/core/project.py"
click node_history "https://github.com/alertxsto/scentinel/blob/master/src/scentinel/core/history.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_app,node_home,node_workspace,node_main,node_setup,node_translator,node_results,node_field,node_sensorlab toneBlue
class node_batch,node_composition,node_scenario,node_gasdata,node_generation,node_pipeline,node_massbalance,node_suitability,node_recommend toneAmber
class node_geometry,node_mesh,node_casegen,node_worker,node_runner,node_container,node_post toneMint
class node_project,node_history toneRose
class node_operator toneIndigo
```

## Components

### Desktop workspace

- [App startup](https://github.com/alertxsto/scentinel/blob/master/src/scentinel/app.py): `src/scentinel/app.py`
- [Home window](https://github.com/alertxsto/scentinel/blob/master/src/scentinel/ui/home_window.py): `src/scentinel/ui/home_window.py`
- [Docked workspace](https://github.com/alertxsto/scentinel/blob/master/src/scentinel/ui/workspace.py): `src/scentinel/ui/workspace.py`
- [Project editor](https://github.com/alertxsto/scentinel/blob/master/src/scentinel/ui/main_window.py): `src/scentinel/ui/main_window.py`
- [Setup panel](https://github.com/alertxsto/scentinel/blob/master/src/scentinel/ui/setup_panel.py): `src/scentinel/ui/setup_panel.py`
- [Runtime language](https://github.com/alertxsto/scentinel/blob/master/src/scentinel/ui/i18n.py): `src/scentinel/ui/i18n.py`
- [Results panel](https://github.com/alertxsto/scentinel/blob/master/src/scentinel/ui/results_panel.py): `src/scentinel/ui/results_panel.py`
- [Field view](https://github.com/alertxsto/scentinel/blob/master/src/scentinel/ui/field_view.py): `src/scentinel/ui/field_view.py`
- [Virtual sensors](https://github.com/alertxsto/scentinel/blob/master/src/scentinel/ui/sensor_lab.py): `src/scentinel/ui/sensor_lab.py`

### Waste assessment

- [Batch panel](https://github.com/alertxsto/scentinel/blob/master/src/scentinel/ui/batch_panel.py): `src/scentinel/ui/batch_panel.py`
- [Waste composition](https://github.com/alertxsto/scentinel/blob/master/src/scentinel/core/composition.py): `src/scentinel/core/composition.py`
- [Scenario inputs](https://github.com/alertxsto/scentinel/blob/master/src/scentinel/core/scenario.py): `src/scentinel/core/scenario.py`
- [Gas catalogue](https://github.com/alertxsto/scentinel/blob/master/src/scentinel/core/gas_data.py): `src/scentinel/core/gas_data.py`
- [Gas generation](https://github.com/alertxsto/scentinel/blob/master/src/scentinel/core/generation.py): `src/scentinel/core/generation.py`
- [Assessment pipeline](https://github.com/alertxsto/scentinel/blob/master/src/scentinel/core/pipeline.py): `src/scentinel/core/pipeline.py`
- [Material balance](https://github.com/alertxsto/scentinel/blob/master/src/scentinel/core/massbalance.py): `src/scentinel/core/massbalance.py`
- [Route suitability](https://github.com/alertxsto/scentinel/blob/master/src/scentinel/core/suitability.py): `src/scentinel/core/suitability.py`
- [Recommendation](https://github.com/alertxsto/scentinel/blob/master/src/scentinel/core/recommend.py): `src/scentinel/core/recommend.py`

### CFD simulation

- [Bin geometry](https://github.com/alertxsto/scentinel/blob/master/src/scentinel/core/geometry.py): `src/scentinel/core/geometry.py`
- [Gmsh meshing](https://github.com/alertxsto/scentinel/blob/master/src/scentinel/core/mesh.py): `src/scentinel/core/mesh.py`
- [OpenFOAM case](https://github.com/alertxsto/scentinel/blob/master/src/scentinel/core/casegen.py): `src/scentinel/core/casegen.py`
- [Solver worker](https://github.com/alertxsto/scentinel/blob/master/src/scentinel/ui/solver_worker.py): `src/scentinel/ui/solver_worker.py`
- [Container runner](https://github.com/alertxsto/scentinel/blob/master/src/scentinel/core/runner.py): `src/scentinel/core/runner.py`
- [Podman execution](https://github.com/alertxsto/scentinel/blob/master/src/scentinel/core/container.py): `src/scentinel/core/container.py`
- [Probe postprocessing](https://github.com/alertxsto/scentinel/blob/master/src/scentinel/core/post.py): `src/scentinel/core/post.py`

### Projects and records

- [Project files](https://github.com/alertxsto/scentinel/blob/master/src/scentinel/core/project.py): `src/scentinel/core/project.py`
- [Run history](https://github.com/alertxsto/scentinel/blob/master/src/scentinel/core/history.py): `src/scentinel/core/history.py`

### Other components

- **Operator**

## Connections

- Operator → Home window: opens app (evidence: `README.md`)
- Home window → Project editor: opens workspace (evidence: `src/scentinel/ui/home_window.py`)
- App startup → Home window: starts (evidence: `src/scentinel/app.py`)
- App startup → Runtime language: initializes (evidence: `src/scentinel/app.py`)
- Project editor → Setup panel: edits inputs (evidence: `src/scentinel/ui/main_window.py`)
- Project editor → Batch panel: shows panel (evidence: `src/scentinel/ui/main_window.py`)
- Project editor → Runtime language: switches language (evidence: `src/scentinel/ui/main_window.py`)
- Setup panel → Scenario inputs: configures (evidence: `src/scentinel/ui/setup_panel.py`)
- Setup panel → Bin geometry: configures (evidence: `src/scentinel/ui/setup_panel.py`)
- Setup panel → Gas catalogue: selects gases (evidence: `src/scentinel/ui/setup_panel.py`)
- Batch panel → Assessment pipeline: assesses batch (evidence: `src/scentinel/ui/batch_panel.py`)
- Assessment pipeline → Gas generation: calculates gas (evidence: `src/scentinel/core/pipeline.py`)
- Assessment pipeline → Material balance: balances material (evidence: `src/scentinel/core/pipeline.py`)
- Assessment pipeline → Route suitability: scores routes (evidence: `src/scentinel/core/pipeline.py`)
- Assessment pipeline → Recommendation: forms recommendation (evidence: `src/scentinel/core/pipeline.py`)
- Assessment pipeline → Waste composition: uses composition (evidence: `src/scentinel/core/pipeline.py`)
- Gas generation → Waste composition: uses composition (evidence: `src/scentinel/core/generation.py`)
- Project editor → Solver worker: starts simulation (evidence: `src/scentinel/ui/main_window.py`)
- Solver worker → Gmsh meshing: generates mesh (evidence: `src/scentinel/ui/solver_worker.py`)
- Solver worker → OpenFOAM case: writes case (evidence: `src/scentinel/ui/solver_worker.py`)
- Solver worker → Container runner: runs solver (evidence: `src/scentinel/ui/solver_worker.py`)
- Solver worker → Probe postprocessing: samples results (evidence: `src/scentinel/ui/solver_worker.py`)
- Gmsh meshing → Bin geometry: meshes geometry (evidence: `src/scentinel/core/mesh.py`)
- OpenFOAM case → Scenario inputs: reads inputs (evidence: `src/scentinel/core/casegen.py`)
- OpenFOAM case → Bin geometry: reads geometry (evidence: `src/scentinel/core/casegen.py`)
- OpenFOAM case → Gas generation: uses gas rates (evidence: `src/scentinel/core/casegen.py`)
- OpenFOAM case → Gas catalogue: resolves gases (evidence: `src/scentinel/core/casegen.py`)
- Container runner → Podman execution: executes in (evidence: `src/scentinel/core/runner.py`)
- Project editor → Results panel: updates results (evidence: `src/scentinel/ui/main_window.py`)
- Results panel → Field view: renders field (evidence: `src/scentinel/ui/results_panel.py`)
- Results panel → Run history: reads runs (evidence: `src/scentinel/ui/results_panel.py`)
- Project editor → Virtual sensors: opens lab (evidence: `src/scentinel/ui/main_window.py`)
- Virtual sensors → Project files: reads configuration (evidence: `src/scentinel/ui/sensor_lab.py`)
- Project editor → Project files: saves and loads (evidence: `src/scentinel/core/project.py`)
- Project editor → Run history: records attempts (evidence: `src/scentinel/ui/main_window.py`)
- Solver worker → Run history: finalizes record
