# shat0nge/stark-monitor architecture

> Architecture diagram of the GitHub repository shat0nge/stark-monitor, 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/shat0nge/stark-monitor
- Repository: https://github.com/shat0nge/stark-monitor

## Overview

This repository implements a STARK inverter monitor: it polls inverter telemetry, parses QPIGS responses, publishes live status and history graphs, and retains measurements in SQLite. The configurable v2 runtime adds optional SSH-based database synchronization. The graph includes both the legacy root implementation and v2; source excerpts show the polling and persistence flow, but omit portions of web routing and database API handling, so those connections are marked unverified where necessary. No README text was supplied.

Main entry points: [`v2/monitor.py`](https://github.com/shat0nge/stark-monitor/blob/main/v2/monitor.py) (Poll coordinator), [`monitor.py`](https://github.com/shat0nge/stark-monitor/blob/main/monitor.py) (Poll coordinator), [`v2/config.py`](https://github.com/shat0nge/stark-monitor/blob/main/v2/config.py) (Runtime configuration), [`v2/database.py`](https://github.com/shat0nge/stark-monitor/blob/main/v2/database.py) (Measurement database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_legacy["Legacy monitor"]
  node_legacy_monitor["Poll coordinator<br/>[monitor.py]"]
  node_legacy_serial["Serial protocol<br/>[inverter.py]"]
  node_legacy_parser["QPIGS parser<br/>[parser.py]"]
  node_legacy_db[("Measurement database<br/>[database.py]")]
end

subgraph group_v2runtime["Configurable monitor"]
  node_config["Runtime configuration<br/>[config.py]"]
  node_v2_monitor["Poll coordinator<br/>[monitor.py]"]
  node_v2_serial["Serial protocol<br/>[inverter.py]"]
  node_v2_parser["QPIGS parser<br/>[parser.py]"]
end

subgraph group_web["Web dashboard"]
  node_legacy_web["Dashboard and API<br/>[web.py]"]
  node_v2_web["Dashboard and API<br/>[web.py]"]
end

subgraph group_storage["Measurement storage"]
  node_v2_db[("Measurement database<br/>[database.py]")]
end

subgraph group_sync["Database sync"]
  node_sync_worker["Sync worker<br/>[db_sync.py]"]
end

node_operator(("Monitor user"))
node_inverter_device{{"STARK inverter"}}
node_browser(("Web browser"))
node_remote_host[("Remote SQLite host")]

node_operator -->|"views dashboard"| node_browser
node_browser -->|"requests pages"| node_legacy_web
node_browser -->|"requests pages"| node_v2_web
node_legacy_monitor -->|"queries inverter"| node_legacy_serial
node_legacy_monitor -->|"parses response"| node_legacy_parser
node_inverter_device -.->|"returns telemetry"| node_legacy_serial
node_legacy_monitor -->|"saves measurements"| node_legacy_db
node_legacy_monitor -->|"cleans old data"| node_legacy_db
node_legacy_monitor -->|"publishes state"| node_legacy_web
node_legacy_web -.->|"reads history"| node_legacy_db
node_config -->|"configures polling"| node_v2_monitor
node_config -->|"configures serial"| node_v2_serial
node_config -->|"configures storage"| node_v2_db
node_config -.->|"configures server"| node_v2_web
node_config -->|"configures sync"| node_sync_worker
node_v2_monitor -->|"queries inverter"| node_v2_serial
node_v2_monitor -->|"parses response"| node_v2_parser
node_inverter_device -.->|"returns telemetry"| node_v2_serial
node_v2_monitor -->|"saves measurements"| node_v2_db
node_v2_monitor -->|"cleans old data"| node_v2_db
node_v2_monitor -->|"publishes state"| node_v2_web
node_v2_web -.->|"reads history"| node_v2_db
node_sync_worker -->|"reads new rows"| node_v2_db
node_sync_worker -->|"sends rows by SSH"| node_remote_host
node_remote_host -->|"returns latest ID"| node_sync_worker

click node_legacy_monitor "https://github.com/shat0nge/stark-monitor/blob/main/monitor.py"
click node_legacy_serial "https://github.com/shat0nge/stark-monitor/blob/main/inverter.py"
click node_legacy_parser "https://github.com/shat0nge/stark-monitor/blob/main/parser.py"
click node_legacy_db "https://github.com/shat0nge/stark-monitor/blob/main/database.py"
click node_legacy_web "https://github.com/shat0nge/stark-monitor/blob/main/web.py"
click node_config "https://github.com/shat0nge/stark-monitor/blob/main/v2/config.py"
click node_v2_monitor "https://github.com/shat0nge/stark-monitor/blob/main/v2/monitor.py"
click node_v2_serial "https://github.com/shat0nge/stark-monitor/blob/main/v2/inverter.py"
click node_v2_parser "https://github.com/shat0nge/stark-monitor/blob/main/v2/parser.py"
click node_v2_db "https://github.com/shat0nge/stark-monitor/blob/main/v2/database.py"
click node_v2_web "https://github.com/shat0nge/stark-monitor/blob/main/v2/web.py"
click node_sync_worker "https://github.com/shat0nge/stark-monitor/blob/main/v2/db_sync.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_legacy_monitor,node_legacy_serial,node_legacy_parser,node_legacy_db,node_operator,node_browser toneBlue
class node_config,node_v2_monitor,node_v2_serial,node_v2_parser,node_remote_host toneAmber
class node_legacy_web,node_v2_web toneMint
class node_v2_db toneRose
class node_sync_worker,node_inverter_device toneIndigo
```

## Components

### Legacy monitor

- [Poll coordinator](https://github.com/shat0nge/stark-monitor/blob/main/monitor.py): `monitor.py`
- [Serial protocol](https://github.com/shat0nge/stark-monitor/blob/main/inverter.py): `inverter.py`
- [QPIGS parser](https://github.com/shat0nge/stark-monitor/blob/main/parser.py): `parser.py`
- [Measurement database](https://github.com/shat0nge/stark-monitor/blob/main/database.py): `database.py`

### Configurable monitor

- [Runtime configuration](https://github.com/shat0nge/stark-monitor/blob/main/v2/config.py): `v2/config.py`
- [Poll coordinator](https://github.com/shat0nge/stark-monitor/blob/main/v2/monitor.py): `v2/monitor.py`
- [Serial protocol](https://github.com/shat0nge/stark-monitor/blob/main/v2/inverter.py): `v2/inverter.py`
- [QPIGS parser](https://github.com/shat0nge/stark-monitor/blob/main/v2/parser.py): `v2/parser.py`

### Web dashboard

- [Dashboard and API](https://github.com/shat0nge/stark-monitor/blob/main/web.py): `web.py`
- [Dashboard and API](https://github.com/shat0nge/stark-monitor/blob/main/v2/web.py): `v2/web.py`

### Measurement storage

- [Measurement database](https://github.com/shat0nge/stark-monitor/blob/main/v2/database.py): `v2/database.py`

### Database sync

- [Sync worker](https://github.com/shat0nge/stark-monitor/blob/main/v2/db_sync.py): `v2/db_sync.py`

### Other components

- **Monitor user**
- **STARK inverter**
- **Web browser**
- **Remote SQLite host**

## Connections

- Monitor user → Web browser: views dashboard
- Web browser → Dashboard and API: requests pages (evidence: `web.py`)
- Web browser → Dashboard and API: requests pages (evidence: `v2/web.py`)
- Poll coordinator → Serial protocol: queries inverter (evidence: `monitor.py`)
- Poll coordinator → QPIGS parser: parses response (evidence: `monitor.py`)
- STARK inverter → Serial protocol: returns telemetry
- Poll coordinator → Measurement database: saves measurements (evidence: `monitor.py`)
- Poll coordinator → Measurement database: cleans old data (evidence: `monitor.py`)
- Poll coordinator → Dashboard and API: publishes state (evidence: `monitor.py`)
- Dashboard and API → Measurement database: reads history (evidence: `web.py`)
- Runtime configuration → Poll coordinator: configures polling (evidence: `v2/monitor.py`)
- Runtime configuration → Serial protocol: configures serial (evidence: `v2/inverter.py`)
- Runtime configuration → Measurement database: configures storage (evidence: `v2/database.py`)
- Runtime configuration → Dashboard and API: configures server (evidence: `v2/web.py`)
- Runtime configuration → Sync worker: configures sync (evidence: `v2/db_sync.py`)
- Poll coordinator → Serial protocol: queries inverter (evidence: `v2/monitor.py`)
- Poll coordinator → QPIGS parser: parses response (evidence: `v2/monitor.py`)
- STARK inverter → Serial protocol: returns telemetry
- Poll coordinator → Measurement database: saves measurements (evidence: `v2/monitor.py`)
- Poll coordinator → Measurement database: cleans old data (evidence: `v2/monitor.py`)
- Poll coordinator → Dashboard and API: publishes state (evidence: `v2/monitor.py`)
- Dashboard and API → Measurement database: reads history
- Sync worker → Measurement database: reads new rows (evidence: `v2/db_sync.py`)
- Sync worker → Remote SQLite host: sends rows by SSH (evidence: `v2/db_sync.py`)
- Remote SQLite host → Sync worker: returns latest ID (evidence: `v2/db_sync.py`)
