AquaCom Integration Gateway

This repository implements the AquaCom Integration Gateway: it communicates with AquaCom-compatible field equipment, normalizes live and historical process data, exposes data through OPC UA (Data Access and Historical Access), and delivers history to one or more configurable storage destinations.

Read the authoritative documentation before changing implementation behavior:

Document	Role
`ARCHITECTURE.md`	System structure, boundaries, interfaces, invariants. Also defines document precedence (§1).
`docs/product/software-specification.md`	Functional requirements — what the gateway shall do.
`docs/product/codex-implementation-specification.md`	Implementation process: phases, task sizing, testing strategy, completion criteria.
`docs/configuration/configuration-reference.md`	Configuration model, validation rules, examples.
`docs/architecture/`	Detailed subsystem architecture.
`docs/protocol/`	AquaCom protocol knowledge, evidence, test vectors, and the protocol-gap registry.

When documents overlap, the precedence defined in ARCHITECTURE.md §1 applies: software-specification for requirements, ARCHITECTURE for structure, the implementation specification for process, the configuration reference for configuration semantics. This file never overrides them.

For substantial work (new AquaCom operations, history synchronization, persistence, storage architecture, OPC UA namespace changes, security, configuration format changes, cross-module refactoring, data migration, significant recovery behavior), create or update an ExecPlan under:


docs/exec-plans/active/

Move completed plans to docs/exec-plans/completed/.

Non-negotiable architecture rules

AquaCom protocol parsing, encoding, framing, checksums and addressing belong only in the AquaCom modules. No OPC UA, history or storage code shall parse AquaCom telegrams.
The OPC UA implementation consumes canonical gateway data only. It shall never construct AquaCom requests, decode AquaCom responses, or depend on AquaCom telegram structures.
Storage implementations consume canonical historical records only. They shall not depend on AquaCom telegrams, addressing, command structures, or OPC UA node internals.
Data crosses subsystem boundaries only through the canonical model.
Historical samples shall never be replayed as current values merely because they were recently received. A historical value describes the process at its SourceTimestamp, not at gateway receipt time.
Preserve SourceTimestamp separately from ReceivedTimestamp (and ServerTimestamp/UpdatedTimestamp where applicable). Never silently replace a valid AquaCom source timestamp with gateway receipt time.
StationId, PointId and OPC UA NodeIds must remain stable across restart, upgrade, display-name changes, and transport-address changes. Display names are not stable identifiers.
Live acquisition takes priority over bulk historical backfill where both compete for limited AquaCom communication capacity.

AquaCom protocol evidence

Never invent AquaCom protocol behavior. Telegram fields, byte positions, framing rules, checksums, command/response codes, addressing, scaling, timestamp encoding, alarm semantics and historical-data semantics may only be implemented when supported by evidence:

authoritative AquaCom documentation;
validated traffic captures;
validated behavior from a known-good implementation;
approved protocol test vectors.

If required protocol information is unavailable: do not guess, leave the feature unimplemented, record the gap in docs/protocol/protocol-gaps.md, and build the interfaces, fixtures and simulation support around the missing area. Compilation success is not evidence that an AquaCom implementation is correct.

Every implemented AquaCom operation shall be traceable to its evidence, and every implemented telegram type shall have automated test vectors.

Testing

Every functional change shall have applicable automated tests; every bug fix should include a regression test where practical. Do not weaken or remove tests merely to make a change pass. Protocol tests must run without external network access, and the AquaCom simulator shall not share parsing code with the production decoder in ways that make protocol tests self-validating.

Security

Never commit production secrets, passwords, API tokens, private keys, OPC UA private keys, database credentials, or secret connection strings. Example configuration shall use placeholders. Production OPC UA configuration shall use secure endpoints by default; insecure modes must not become the production default. If uncertain between a permissive and restrictive security behavior, prefer the restrictive behavior and document the decision.

Handling uncertainty

Local implementation detail — choose the simplest solution consistent with the architecture.
Architectural decision — record the decision and reasoning in the current ExecPlan.
AquaCom protocol uncertainty — do not guess; record it in docs/protocol/protocol-gaps.md.
Security or safety uncertainty — prefer the safer behavior and document the decision.

Task completion

Do not consider a task complete until: implementation is complete; relevant tests exist and pass; lint/static checks and configuration validation pass; relevant documentation is updated; architecture boundaries remain intact; new AquaCom behavior has evidence; new failure modes have diagnostics; no secrets were introduced.

A list of documentation referenced by this repository but not yet created is maintained in missing_docs.md.

5.6 KiB Raw Permalink Blame History