# n0ngxarm/aquacmd architecture

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

- Interactive diagram: https://gitdiagram.com/n0ngxarm/aquacmd
- Repository: https://github.com/n0ngxarm/aquacmd

## Overview

AQUA COMMAND is primarily a read-only industrial monitoring desktop: operators configure/enroll sources, collect OPC UA observations, evaluate tasks, retain evidence and outbox state, then authorize notification delivery. The repository also contains a separate PWA outage and water-quality notification CLI, plus a LAN service. Connections below follow README statements and SOURCE INDEX references; unsampled subsystem links are omitted where their callers are not shown.

Main entry points: [`aqua-command-desktop/desktop/app.py`](https://github.com/n0ngxarm/aquacmd/blob/main/aqua-command-desktop/desktop/app.py) (GTK desktop), [`aqua-command-desktop/desktop/opcua_polling_engine.py`](https://github.com/n0ngxarm/aquacmd/blob/main/aqua-command-desktop/desktop/opcua_polling_engine.py) (OPC UA polling), [`src/monitor_service.py`](https://github.com/n0ngxarm/aquacmd/blob/main/src/monitor_service.py) (Outage monitoring), [`aqua-command-desktop/backend/bin/aqua-service.js`](https://github.com/n0ngxarm/aquacmd/blob/main/aqua-command-desktop/backend/bin/aqua-service.js) (LAN service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Monitoring desktop"]
  node_desktop_app["GTK desktop<br/>[app.py]"]
  node_overview["Monitoring views<br/>[f1_overview.py]"]
  node_workspace["Operator workspace<br/>[workspace.py]"]
  node_observability["Observability service<br/>[service.py]"]
end

subgraph group_collection["Collection and evidence"]
  node_opcua_poll["OPC UA polling"]
  node_tag_mapping["Tag mapping<br/>[opcua_mapping.py]"]
  node_pki["OPC UA trust<br/>[opcua_pki.py]"]
  node_opcua_store[("Observable state<br/>[opcua_store.py]")]
  node_durable_storage[("Evidence and outbox<br/>[opcua_storage.py]")]
end

subgraph group_alerts["Tasks and notifications"]
  node_tasks["Task evaluation<br/>[task_engine.py]"]
  node_task_views["Task interface<br/>[f2_tasks.py]"]
  node_notification_worker["Notification delivery"]
end

subgraph group_lan["LAN service"]
  node_lan_service["LAN service<br/>[aqua-service.js]"]
  node_lan_services["LAN operations<br/>[services.js]"]
  node_lan_protocol["LAN protocol<br/>[protocol.js]"]
  node_lan_dashboard["LAN dashboard<br/>[dashboard.js]"]
  node_lan_store[("LAN event store<br/>[store.js]")]
end

subgraph group_pwa["PWA notifications"]
  node_pwa_cli["PWA CLI<br/>[main.py]"]
  node_monitor["Outage monitoring<br/>[monitor_service.py]"]
  node_pwa_client["PWA data client<br/>[pwa_client.py]"]
  node_pwa_db[("Alert database<br/>[database.py]")]
  node_telegram["Telegram delivery"]
  node_bridge["AQUA bridge<br/>[aqua_bridge.py]"]
end

node_operator(("Operator"))
node_external_channel(("Notification service"))

node_operator -->|"operates"| node_desktop_app
node_desktop_app -->|"starts polling"| node_opcua_poll
node_desktop_app -->|"configures tasks"| node_tasks
node_desktop_app -->|"uses storage"| node_durable_storage
node_desktop_app -->|"opens view"| node_overview
node_desktop_app -->|"opens view"| node_task_views
node_desktop_app -->|"uses workspace"| node_workspace
node_desktop_app -->|"uses service"| node_observability
node_opcua_poll -->|"uses mapping"| node_tag_mapping
node_opcua_poll -->|"checks trust"| node_pki
node_opcua_poll -->|"updates state"| node_opcua_store
node_opcua_poll -->|"persists observations"| node_durable_storage
node_opcua_poll -->|"evaluates readings"| node_tasks
node_tasks -->|"records events"| node_durable_storage
node_operator -->|"runs commands"| node_pwa_cli
node_pwa_cli -->|"starts monitor"| node_monitor
node_monitor -->|"fetches data"| node_pwa_client
node_monitor -->|"records alerts"| node_pwa_db
node_monitor -->|"dispatches alerts"| node_telegram
node_monitor -->|"pushes incidents"| node_bridge
node_pwa_client -.->|"queries source"| node_operator
node_telegram -.->|"sends messages"| node_external_channel
node_lan_service -->|"starts services"| node_lan_services
node_lan_service -->|"starts dashboard"| node_lan_dashboard
node_lan_service -->|"uses protocol"| node_lan_protocol
node_lan_services -->|"authenticates requests"| node_lan_protocol
node_lan_dashboard -->|"uses protocol"| node_lan_protocol
node_lan_dashboard -->|"reads and writes"| node_lan_store

click node_desktop_app "https://github.com/n0ngxarm/aquacmd/blob/main/aqua-command-desktop/desktop/app.py"
click node_overview "https://github.com/n0ngxarm/aquacmd/blob/main/aqua-command-desktop/desktop/f1_overview.py"
click node_workspace "https://github.com/n0ngxarm/aquacmd/blob/main/aqua-command-desktop/desktop/workspace.py"
click node_observability "https://github.com/n0ngxarm/aquacmd/blob/main/aqua-command-desktop/desktop/observability/service.py"
click node_opcua_poll "https://github.com/n0ngxarm/aquacmd/blob/main/aqua-command-desktop/desktop/opcua_polling_engine.py"
click node_tag_mapping "https://github.com/n0ngxarm/aquacmd/blob/main/aqua-command-desktop/desktop/opcua_mapping.py"
click node_pki "https://github.com/n0ngxarm/aquacmd/blob/main/aqua-command-desktop/desktop/opcua_pki.py"
click node_opcua_store "https://github.com/n0ngxarm/aquacmd/blob/main/aqua-command-desktop/desktop/opcua_store.py"
click node_durable_storage "https://github.com/n0ngxarm/aquacmd/blob/main/aqua-command-desktop/desktop/opcua_storage.py"
click node_tasks "https://github.com/n0ngxarm/aquacmd/blob/main/aqua-command-desktop/desktop/task_engine.py"
click node_task_views "https://github.com/n0ngxarm/aquacmd/blob/main/aqua-command-desktop/desktop/f2_tasks.py"
click node_notification_worker "https://github.com/n0ngxarm/aquacmd/blob/main/aqua-command-desktop/desktop/notification_worker.py"
click node_lan_service "https://github.com/n0ngxarm/aquacmd/blob/main/aqua-command-desktop/backend/bin/aqua-service.js"
click node_lan_services "https://github.com/n0ngxarm/aquacmd/blob/main/aqua-command-desktop/backend/src/lan/services.js"
click node_lan_protocol "https://github.com/n0ngxarm/aquacmd/blob/main/aqua-command-desktop/backend/src/lan/protocol.js"
click node_lan_dashboard "https://github.com/n0ngxarm/aquacmd/blob/main/aqua-command-desktop/backend/src/lan/dashboard.js"
click node_lan_store "https://github.com/n0ngxarm/aquacmd/blob/main/aqua-command-desktop/backend/src/lan/store.js"
click node_pwa_cli "https://github.com/n0ngxarm/aquacmd/blob/main/main.py"
click node_monitor "https://github.com/n0ngxarm/aquacmd/blob/main/src/monitor_service.py"
click node_pwa_client "https://github.com/n0ngxarm/aquacmd/blob/main/src/pwa_client.py"
click node_pwa_db "https://github.com/n0ngxarm/aquacmd/blob/main/src/database.py"
click node_telegram "https://github.com/n0ngxarm/aquacmd/blob/main/src/telegram_notifier.py"
click node_bridge "https://github.com/n0ngxarm/aquacmd/blob/main/src/aqua_bridge.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_desktop_app,node_overview,node_workspace,node_observability toneBlue
class node_opcua_poll,node_tag_mapping,node_pki,node_opcua_store,node_durable_storage toneAmber
class node_tasks,node_task_views,node_notification_worker toneMint
class node_lan_service,node_lan_services,node_lan_protocol,node_lan_dashboard,node_lan_store toneRose
class node_pwa_cli,node_monitor,node_pwa_client,node_pwa_db,node_telegram,node_bridge,node_operator,node_external_channel toneIndigo
```

## Components

### Monitoring desktop

- [GTK desktop](https://github.com/n0ngxarm/aquacmd/blob/main/aqua-command-desktop/desktop/app.py): `aqua-command-desktop/desktop/app.py`
- [Monitoring views](https://github.com/n0ngxarm/aquacmd/blob/main/aqua-command-desktop/desktop/f1_overview.py): `aqua-command-desktop/desktop/f1_overview.py`
- [Operator workspace](https://github.com/n0ngxarm/aquacmd/blob/main/aqua-command-desktop/desktop/workspace.py): `aqua-command-desktop/desktop/workspace.py`
- [Observability service](https://github.com/n0ngxarm/aquacmd/blob/main/aqua-command-desktop/desktop/observability/service.py): `aqua-command-desktop/desktop/observability/service.py`

### Collection and evidence

- [OPC UA polling](https://github.com/n0ngxarm/aquacmd/blob/main/aqua-command-desktop/desktop/opcua_polling_engine.py): `aqua-command-desktop/desktop/opcua_polling_engine.py`
- [Tag mapping](https://github.com/n0ngxarm/aquacmd/blob/main/aqua-command-desktop/desktop/opcua_mapping.py): `aqua-command-desktop/desktop/opcua_mapping.py`
- [OPC UA trust](https://github.com/n0ngxarm/aquacmd/blob/main/aqua-command-desktop/desktop/opcua_pki.py): `aqua-command-desktop/desktop/opcua_pki.py`
- [Observable state](https://github.com/n0ngxarm/aquacmd/blob/main/aqua-command-desktop/desktop/opcua_store.py): `aqua-command-desktop/desktop/opcua_store.py`
- [Evidence and outbox](https://github.com/n0ngxarm/aquacmd/blob/main/aqua-command-desktop/desktop/opcua_storage.py): `aqua-command-desktop/desktop/opcua_storage.py`

### Tasks and notifications

- [Task evaluation](https://github.com/n0ngxarm/aquacmd/blob/main/aqua-command-desktop/desktop/task_engine.py): `aqua-command-desktop/desktop/task_engine.py`
- [Task interface](https://github.com/n0ngxarm/aquacmd/blob/main/aqua-command-desktop/desktop/f2_tasks.py): `aqua-command-desktop/desktop/f2_tasks.py`
- [Notification delivery](https://github.com/n0ngxarm/aquacmd/blob/main/aqua-command-desktop/desktop/notification_worker.py): `aqua-command-desktop/desktop/notification_worker.py`

### LAN service

- [LAN service](https://github.com/n0ngxarm/aquacmd/blob/main/aqua-command-desktop/backend/bin/aqua-service.js): `aqua-command-desktop/backend/bin/aqua-service.js`
- [LAN operations](https://github.com/n0ngxarm/aquacmd/blob/main/aqua-command-desktop/backend/src/lan/services.js): `aqua-command-desktop/backend/src/lan/services.js`
- [LAN protocol](https://github.com/n0ngxarm/aquacmd/blob/main/aqua-command-desktop/backend/src/lan/protocol.js): `aqua-command-desktop/backend/src/lan/protocol.js`
- [LAN dashboard](https://github.com/n0ngxarm/aquacmd/blob/main/aqua-command-desktop/backend/src/lan/dashboard.js): `aqua-command-desktop/backend/src/lan/dashboard.js`
- [LAN event store](https://github.com/n0ngxarm/aquacmd/blob/main/aqua-command-desktop/backend/src/lan/store.js): `aqua-command-desktop/backend/src/lan/store.js`

### PWA notifications

- [PWA CLI](https://github.com/n0ngxarm/aquacmd/blob/main/main.py): `main.py`
- [Outage monitoring](https://github.com/n0ngxarm/aquacmd/blob/main/src/monitor_service.py): `src/monitor_service.py`
- [PWA data client](https://github.com/n0ngxarm/aquacmd/blob/main/src/pwa_client.py): `src/pwa_client.py`
- [Alert database](https://github.com/n0ngxarm/aquacmd/blob/main/src/database.py): `src/database.py`
- [Telegram delivery](https://github.com/n0ngxarm/aquacmd/blob/main/src/telegram_notifier.py): `src/telegram_notifier.py`
- [AQUA bridge](https://github.com/n0ngxarm/aquacmd/blob/main/src/aqua_bridge.py): `src/aqua_bridge.py`

### Other components

- **Operator**
- **Notification service**

## Connections

- Operator → GTK desktop: operates
- GTK desktop → OPC UA polling: starts polling (evidence: `aqua-command-desktop/desktop/app.py`)
- GTK desktop → Task evaluation: configures tasks (evidence: `aqua-command-desktop/desktop/app.py`)
- GTK desktop → Evidence and outbox: uses storage (evidence: `aqua-command-desktop/desktop/app.py`)
- GTK desktop → Monitoring views: opens view (evidence: `aqua-command-desktop/desktop/app.py`)
- GTK desktop → Task interface: opens view (evidence: `aqua-command-desktop/desktop/app.py`)
- GTK desktop → Operator workspace: uses workspace (evidence: `aqua-command-desktop/desktop/app.py`)
- GTK desktop → Observability service: uses service (evidence: `aqua-command-desktop/desktop/app.py`)
- OPC UA polling → Tag mapping: uses mapping (evidence: `aqua-command-desktop/desktop/opcua_polling_engine.py`)
- OPC UA polling → OPC UA trust: checks trust (evidence: `aqua-command-desktop/desktop/opcua_polling_engine.py`)
- OPC UA polling → Observable state: updates state (evidence: `aqua-command-desktop/desktop/opcua_polling_engine.py`)
- OPC UA polling → Evidence and outbox: persists observations (evidence: `aqua-command-desktop/desktop/opcua_polling_engine.py`)
- OPC UA polling → Task evaluation: evaluates readings (evidence: `aqua-command-desktop/desktop/opcua_polling_engine.py`)
- Task evaluation → Evidence and outbox: records events (evidence: `aqua-command-desktop/desktop/task_engine.py`)
- Operator → PWA CLI: runs commands
- PWA CLI → Outage monitoring: starts monitor (evidence: `main.py`)
- Outage monitoring → PWA data client: fetches data (evidence: `src/monitor_service.py`)
- Outage monitoring → Alert database: records alerts (evidence: `src/monitor_service.py`)
- Outage monitoring → Telegram delivery: dispatches alerts (evidence: `src/monitor_service.py`)
- Outage monitoring → AQUA bridge: pushes incidents (evidence: `src/monitor_service.py`)
- PWA data client → Operator: queries source (evidence: `src/pwa_client.py`)
- Telegram delivery → Notification service: sends messages (evidence: `src/telegram_notifier.py`)
- LAN service → LAN operations: starts services (evidence: `aqua-command-desktop/backend/bin/aqua-service.js`)
- LAN service → LAN dashboard: starts dashboard (evidence: `aqua-command-desktop/backend/bin/aqua-service.js`)
- LAN service → LAN protocol: uses protocol (evidence: `aqua-command-desktop/backend/bin/aqua-service.js`)
- LAN operations → LAN protocol: authenticates requests (evidence: `aqua-command-desktop/backend/src/lan/services.js`)
- LAN dashboard → LAN protocol: uses protocol (evidence: `aqua-command-desktop/backend/src/lan/dashboard.js`)
- LAN dashboard → LAN event store: reads and writes (evidence: `aqua-command-desktop/backend/src/lan/dashboard.js`)