# 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.