📝 Documenation

2026-10-06 07:08:03 +02:00
parent 08d44babbb
commit e1f51772da
12 changed files with 17511 additions and 9 deletions
@@ -0,0 +1,126 @@
+# AquaCom Integration Gateway
+
+The **AquaCom Integration Gateway** connects AquaCom-compatible field equipment (legacy MacTec-standard RTUs used in pump stations and similar water-utility installations) to modern OT/IT systems.
+
+The gateway:
+
+- communicates with AquaCom stations over TCP or serial transports;
+- acquires **current (live) process values**;
+- retrieves **historical process values** recorded in the field equipment;
+- normalizes everything into a protocol-independent canonical data model;
+- exposes current values through **OPC UA Data Access**;
+- exposes historical values through **OPC UA Historical Access**;
+- delivers history to one or more **independent, configurable storage destinations**;
+- recovers historical data automatically after communication interruptions (watermark-based backfill with store-and-forward buffering);
+- provides operational and protocol **diagnostics**.
+
+It is deliberately an *integration gateway*, not merely an OPC UA server: the long-term asset is the normalized information layer and the historical recovery mechanism, so OPC UA, the storage technology, and the AquaCom equipment can each evolve or be replaced independently.
+
+> **Status: specification & planning phase.**
+> This repository currently contains the complete documentation set, the verified protocol evidence, and the implementation roadmap. Runtime code does not exist yet — implementation begins with Phase 0 of the [implementation roadmap](docs/exec-plans/active/001-implementation-roadmap.md).
+
+---
+
+## Architecture
+
+```mermaid
+graph TB
+    RTU[AquaCom stations / RTUs] --> TR[AquaCom Transport]
+    TR --> PE[AquaCom Protocol Engine]
+    PE --> SM[Station / Session Manager]
+    SM --> CM[Canonical data model]
+
+    CM --> CS[Current-State Service]
+    CM --> HAM[Historical Acquisition Manager]
+    HAM --> HP[Historical pipeline: validate → deduplicate → durable spool]
+    HP --> REPO[(History repository)]
+    HP --> SINKS[(Storage sinks A…N)]
+
+    CS --> SRV[OPC UA server: Data Access + Historical Access + diagnostics]
+    REPO --> SRV
+    SRV --> CLIENTS[SCADA / historian / analytics clients]
+```
+
+Core architectural rules (normative in [`ARCHITECTURE.md`](ARCHITECTURE.md)):
+
+- AquaCom protocol parsing lives only in the AquaCom modules; no OPC UA, history or storage code touches a telegram.
+- Data crosses subsystem boundaries only through the canonical model.
+- A historical sample describes the process **at its SourceTimestamp** — it never becomes a current value merely because it was recently received.
+- OPC UA Historical Access queries the gateway's history repository; a client `HistoryRead` never triggers AquaCom traffic.
+- `StationId`, `PointId` and OPC UA NodeIds remain stable across restart, upgrade, renaming and transport-address changes.
+- Live acquisition takes priority over bulk historical backfill.
+
+## Documentation
+
+| Document | Role |
+|---|---|
+| [`AGENTS.md`](AGENTS.md) | Entry point for coding agents and contributors — pointers and non-negotiable rules |
+| [`ARCHITECTURE.md`](ARCHITECTURE.md) | System structure, boundaries, interfaces, invariants — also defines document precedence (§1) |
+| [`docs/product/software-specification.md`](docs/product/software-specification.md) | Functional requirements — what the gateway shall do |
+| [`docs/product/codex-implementation-specification.md`](docs/product/codex-implementation-specification.md) | Implementation process: phases, task sizing, testing strategy, completion criteria |
+| [`docs/configuration/configuration-reference.md`](docs/configuration/configuration-reference.md) | Configuration model, fields, defaults, validation rules |
+| [`docs/protocol/`](docs/protocol) | AquaCom protocol knowledge: evidence, operation registry, gap registry, test vectors |
+| [`docs/exec-plans/active/001-implementation-roadmap.md`](docs/exec-plans/active/001-implementation-roadmap.md) | Implementation roadmap (ExecPlan 001): phases 0–14, gates, decisions |
+| [`missing_docs.md`](missing_docs.md) | Planned documents that do not exist yet |
+
+When documents overlap, the precedence defined in `ARCHITECTURE.md` §1 applies: the software specification for *requirements*, `ARCHITECTURE.md` for *structure*, the implementation specification for *process*, the configuration reference for *configuration semantics*. No other document overrides them.
+
+## Protocol evidence
+
+The AquaCom implementation is strictly **evidence-based**: telegram framing, checksums, operations, addressing, timestamp encoding and historical-data semantics may only be implemented from verified evidence (the authoritative vendor protocol description, validated traffic captures, or known-good implementations). Unknown protocol behavior is recorded in the [gap registry](docs/protocol/protocol-gaps.md) — never guessed.
+
+| Document | Content |
+|---|---|
+| [`docs/protocol/AquaCom_RTU_1_6_eng.pdf`](docs/protocol/AquaCom_RTU_1_6_eng.pdf) | Authoritative source: *Technical description – AquaCom – RTU level*, Rev 1.6, ITT Flygt AB, July 2004 |
+| [`docs/protocol/known-operations.md`](docs/protocol/known-operations.md) | Registry of implementable operations, each with evidence and scope status |
+| [`docs/protocol/protocol-gaps.md`](docs/protocol/protocol-gaps.md) | Open protocol questions with working hypotheses and workarounds |
+| [`docs/protocol/test-vectors.md`](docs/protocol/test-vectors.md) | Checksum-verified test vectors for the codec (35 source vectors recomputed and confirmed) |
+
+## Repository layout
+
+```text
+.
+├── AGENTS.md                     # entry point for agents / contributors
+├── ARCHITECTURE.md               # system structure, boundaries, invariants
+├── README.md                     # this file
+├── missing_docs.md               # planned documents not yet created
+└── docs/
+    ├── architecture/             # detailed subsystem architecture (planned)
+    ├── configuration/
+    │   └── configuration-reference.md
+    ├── exec-plans/
+    │   └── active/
+    │       └── 001-implementation-roadmap.md
+    ├── product/
+    │   ├── software-specification.md
+    │   └── codex-implementation-specification.md
+    └── protocol/
+        ├── AquaCom_RTU_1_6_eng.pdf          # authoritative protocol source
+        ├── AquaCom_RTU_1_6_eng_markdown/    # markdown conversion (lossy — see gap registry)
+        ├── known-operations.md
+        ├── protocol-gaps.md
+        └── test-vectors.md
+```
+
+## Current status and next steps
+
+- [x] Complete, consistent specification and architecture documentation
+- [x] Protocol evidence acquired and catalogued; 35 checksum vectors verified by recomputation
+- [x] Implementation roadmap (ExecPlan 001) with phase gates and decision log
+- [ ] **Technology selection** (decision D-001): implementation language + OPC UA server stack — server-side Historical Access support is the make-or-break capability to verify per candidate
+- [ ] Phase 0: repository skeleton, CI, configuration schema
+- [ ] Phases 1–14 per the [roadmap](docs/exec-plans/active/001-implementation-roadmap.md)
+
+## Getting started
+
+**Reading the project** (suggested order): this file → [`ARCHITECTURE.md`](ARCHITECTURE.md) → [`docs/product/software-specification.md`](docs/product/software-specification.md) → the [roadmap](docs/exec-plans/active/001-implementation-roadmap.md).
+
+**Contributing / implementing**: read [`AGENTS.md`](AGENTS.md) first — it defines the evidence rules, architectural boundaries, testing requirements and the ExecPlan process that all substantial work must follow.
+
+## Third-party material
+
+The AquaCom protocol description under `docs/protocol/` is a third-party copyrighted document (© 2004 ITT Flygt AB). It is kept in this repository for internal engineering reference; do not redistribute it outside your organization without the copyright holder's permission.
+
+## License
+
+Not yet chosen. Licensing will be decided before the first public release of implementation code.