# srivardhxn/harmonysense-scheinder architecture

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

- Interactive diagram: https://gitdiagram.com/srivardhxn/harmonysense-scheinder
- Repository: https://github.com/srivardhxn/harmonysense-scheinder

## Overview

HarmonySense is an offline industrial HMI copilot. Operators inject or encounter alarm bursts; the backend correlates alarms, retrieves grounded SOP guidance, generates a local explanation, and applies a deterministic safety guardrail before presenting advice. Separate workflows cover live PLC-tag streaming, what-if safety checks, and shift handover summaries. The excerpts show the core correlation, retrieval, LLM, guardrail, and sandbox responsibilities; some endpoint wiring and data-flow details are documented only in the README, so uncertain links are omitted or marked unverified.

Main entry points: [`copilot_app/backend/main.py`](https://github.com/srivardhxn/harmonysense-scheinder/blob/main/copilot_app/backend/main.py) (FastAPI Runtime), [`copilot_app/backend/retrieval.py`](https://github.com/srivardhxn/harmonysense-scheinder/blob/main/copilot_app/backend/retrieval.py) (SOP Retrieval), [`copilot_app/backend/guardrail.py`](https://github.com/srivardhxn/harmonysense-scheinder/blob/main/copilot_app/backend/guardrail.py) (Safety Guardrail), [`copilot_app/frontend`](https://github.com/srivardhxn/harmonysense-scheinder/tree/main/copilot_app/frontend) (HMI Copilot)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Operator Experience"]
  node_hmi["HMI Copilot"]
end

subgraph group_runtime["Backend Runtime"]
  node_api["FastAPI Runtime<br/>[main.py]"]
  node_live["Live Tag Stream<br/>[main.py]"]
  node_alarm_storm["Alarm Storm<br/>[main.py]"]
  node_explanation["SOP Explanation<br/>[main.py]"]
  node_edge_llm["Local Edge SLM<br/>[llm_service.py]"]
  node_handover["Shift Handover<br/>[main.py]"]
end

subgraph group_safety["Safety and Analysis"]
  node_correlation["Alarm Correlator<br/>[correlation.py]"]
  node_guardrail["Safety Guardrail<br/>[guardrail.py]"]
  node_whatif["What-If Checks<br/>[main.py]"]
  node_sandbox["Trajectory Sandbox<br/>[chaos_sandbox.py]"]
end

subgraph group_knowledge["Plant Knowledge"]
  node_retrieval["SOP Retrieval<br/>[retrieval.py]"]
  node_knowledge_db[("Knowledge Database<br/>[knowledge_base.db]")]
  node_sops["SOP Procedures<br/>[sops.json]"]
  node_machine_context["Machine Context"]
  node_shift_logs["Shift Event Logs"]
end

node_operator(("Operator"))
node_ollama["Local Ollama"]

node_operator -->|"uses"| node_hmi
node_hmi -.->|"requests"| node_api
node_api -->|"streams tags"| node_live
node_operator -->|"injects alarms"| node_alarm_storm
node_api -->|"serves endpoints"| node_alarm_storm
node_api -->|"correlates alarms"| node_correlation
node_alarm_storm -.->|"submits alarms"| node_correlation
node_api -->|"serves explanation"| node_explanation
node_explanation -.->|"retrieves SOPs"| node_retrieval
node_retrieval -->|"queries"| node_knowledge_db
node_retrieval -->|"indexes procedures"| node_sops
node_retrieval -->|"indexes tags"| node_machine_context
node_explanation -.->|"generates guidance"| node_edge_llm
node_edge_llm -->|"calls locally"| node_ollama
node_api -->|"filters responses"| node_guardrail
node_guardrail -->|"checks identifiers"| node_machine_context
node_operator -->|"proposes action"| node_whatif
node_api -->|"serves checks"| node_whatif
node_whatif -.->|"checks restrictions"| node_guardrail
node_operator -->|"tests scenario"| node_sandbox
node_api -->|"registers router"| node_sandbox
node_operator -->|"requests report"| node_handover
node_api -->|"serves report"| node_handover
node_handover -.->|"reconciles events"| node_shift_logs

click node_hmi "https://github.com/srivardhxn/harmonysense-scheinder/tree/main/copilot_app/frontend"
click node_api "https://github.com/srivardhxn/harmonysense-scheinder/blob/main/copilot_app/backend/main.py"
click node_live "https://github.com/srivardhxn/harmonysense-scheinder/blob/main/copilot_app/backend/main.py"
click node_alarm_storm "https://github.com/srivardhxn/harmonysense-scheinder/blob/main/copilot_app/backend/main.py"
click node_correlation "https://github.com/srivardhxn/harmonysense-scheinder/blob/main/copilot_app/backend/correlation.py"
click node_explanation "https://github.com/srivardhxn/harmonysense-scheinder/blob/main/copilot_app/backend/main.py"
click node_retrieval "https://github.com/srivardhxn/harmonysense-scheinder/blob/main/copilot_app/backend/retrieval.py"
click node_knowledge_db "https://github.com/srivardhxn/harmonysense-scheinder/blob/main/copilot_app/data/knowledge_base.db"
click node_sops "https://github.com/srivardhxn/harmonysense-scheinder/blob/main/copilot_app/data/sops.json"
click node_machine_context "https://github.com/srivardhxn/harmonysense-scheinder/blob/main/copilot_app/data/machine_context.json"
click node_edge_llm "https://github.com/srivardhxn/harmonysense-scheinder/blob/main/copilot_app/backend/llm_service.py"
click node_guardrail "https://github.com/srivardhxn/harmonysense-scheinder/blob/main/copilot_app/backend/guardrail.py"
click node_whatif "https://github.com/srivardhxn/harmonysense-scheinder/blob/main/copilot_app/backend/main.py"
click node_sandbox "https://github.com/srivardhxn/harmonysense-scheinder/blob/main/copilot_app/backend/chaos_sandbox.py"
click node_handover "https://github.com/srivardhxn/harmonysense-scheinder/blob/main/copilot_app/backend/main.py"
click node_shift_logs "https://github.com/srivardhxn/harmonysense-scheinder/blob/main/copilot_app/data/synthetic_logs.json"

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_hmi toneBlue
class node_api,node_live,node_alarm_storm,node_explanation,node_edge_llm,node_handover toneAmber
class node_correlation,node_guardrail,node_whatif,node_sandbox toneMint
class node_retrieval,node_knowledge_db,node_sops,node_machine_context,node_shift_logs toneRose
class node_operator,node_ollama toneIndigo
```

## Components

### Operator Experience

- [HMI Copilot](https://github.com/srivardhxn/harmonysense-scheinder/tree/main/copilot_app/frontend): `copilot_app/frontend`

### Backend Runtime

- [FastAPI Runtime](https://github.com/srivardhxn/harmonysense-scheinder/blob/main/copilot_app/backend/main.py): `copilot_app/backend/main.py`
- [Live Tag Stream](https://github.com/srivardhxn/harmonysense-scheinder/blob/main/copilot_app/backend/main.py): `copilot_app/backend/main.py`
- [Alarm Storm](https://github.com/srivardhxn/harmonysense-scheinder/blob/main/copilot_app/backend/main.py): `copilot_app/backend/main.py`
- [SOP Explanation](https://github.com/srivardhxn/harmonysense-scheinder/blob/main/copilot_app/backend/main.py): `copilot_app/backend/main.py`
- [Local Edge SLM](https://github.com/srivardhxn/harmonysense-scheinder/blob/main/copilot_app/backend/llm_service.py): `copilot_app/backend/llm_service.py`
- [Shift Handover](https://github.com/srivardhxn/harmonysense-scheinder/blob/main/copilot_app/backend/main.py): `copilot_app/backend/main.py`

### Safety and Analysis

- [Alarm Correlator](https://github.com/srivardhxn/harmonysense-scheinder/blob/main/copilot_app/backend/correlation.py): `copilot_app/backend/correlation.py`
- [Safety Guardrail](https://github.com/srivardhxn/harmonysense-scheinder/blob/main/copilot_app/backend/guardrail.py): `copilot_app/backend/guardrail.py`
- [What-If Checks](https://github.com/srivardhxn/harmonysense-scheinder/blob/main/copilot_app/backend/main.py): `copilot_app/backend/main.py`
- [Trajectory Sandbox](https://github.com/srivardhxn/harmonysense-scheinder/blob/main/copilot_app/backend/chaos_sandbox.py): `copilot_app/backend/chaos_sandbox.py`

### Plant Knowledge

- [SOP Retrieval](https://github.com/srivardhxn/harmonysense-scheinder/blob/main/copilot_app/backend/retrieval.py): `copilot_app/backend/retrieval.py`
- [Knowledge Database](https://github.com/srivardhxn/harmonysense-scheinder/blob/main/copilot_app/data/knowledge_base.db): `copilot_app/data/knowledge_base.db`
- [SOP Procedures](https://github.com/srivardhxn/harmonysense-scheinder/blob/main/copilot_app/data/sops.json): `copilot_app/data/sops.json`
- [Machine Context](https://github.com/srivardhxn/harmonysense-scheinder/blob/main/copilot_app/data/machine_context.json): `copilot_app/data/machine_context.json`
- [Shift Event Logs](https://github.com/srivardhxn/harmonysense-scheinder/blob/main/copilot_app/data/synthetic_logs.json): `copilot_app/data/synthetic_logs.json`

### Other components

- **Operator**
- **Local Ollama**

## Connections

- Operator → HMI Copilot: uses (evidence: `README.md`)
- HMI Copilot → FastAPI Runtime: requests
- FastAPI Runtime → Live Tag Stream: streams tags (evidence: `README.md`)
- Operator → Alarm Storm: injects alarms (evidence: `README.md`)
- FastAPI Runtime → Alarm Storm: serves endpoints (evidence: `copilot_app/backend/main.py`)
- FastAPI Runtime → Alarm Correlator: correlates alarms (evidence: `copilot_app/backend/main.py`)
- Alarm Storm → Alarm Correlator: submits alarms (evidence: `copilot_app/backend/main.py`)
- FastAPI Runtime → SOP Explanation: serves explanation (evidence: `copilot_app/backend/main.py`)
- SOP Explanation → SOP Retrieval: retrieves SOPs (evidence: `copilot_app/backend/main.py`)
- SOP Retrieval → Knowledge Database: queries (evidence: `copilot_app/backend/retrieval.py`)
- SOP Retrieval → SOP Procedures: indexes procedures (evidence: `copilot_app/backend/retrieval.py`)
- SOP Retrieval → Machine Context: indexes tags (evidence: `copilot_app/backend/retrieval.py`)
- SOP Explanation → Local Edge SLM: generates guidance (evidence: `copilot_app/backend/main.py`)
- Local Edge SLM → Local Ollama: calls locally (evidence: `copilot_app/backend/llm_service.py`)
- FastAPI Runtime → Safety Guardrail: filters responses (evidence: `copilot_app/backend/main.py`)
- Safety Guardrail → Machine Context: checks identifiers (evidence: `copilot_app/backend/guardrail.py`)
- Operator → What-If Checks: proposes action (evidence: `README.md`)
- FastAPI Runtime → What-If Checks: serves checks (evidence: `copilot_app/backend/main.py`)
- What-If Checks → Safety Guardrail: checks restrictions (evidence: `copilot_app/backend/main.py`)
- Operator → Trajectory Sandbox: tests scenario (evidence: `README.md`)
- FastAPI Runtime → Trajectory Sandbox: registers router (evidence: `copilot_app/backend/main.py`)
- Operator → Shift Handover: requests report (evidence: `README.md`)
- FastAPI Runtime → Shift Handover: serves report (evidence: `copilot_app/backend/main.py`)
- Shift Handover → Shift Event Logs: reconciles events