# AquaCom Integration Gateway – Architecture ## 1. Purpose This document defines the high-level software architecture of the **AquaCom Integration Gateway**. It describes: - major system components; - dependency direction; - data flows; - architectural boundaries; - live-data handling; - historical-data handling; - OPC UA integration; - storage integration; - diagnostics; - security boundaries; - extension points. Detailed functional requirements are defined in: ```text docs/product/software-specification.md ``` Implementation requirements and Codex-specific development rules are defined in: ```text docs/product/codex-implementation-specification.md AGENTS.md ``` **Document roles and precedence.** When documents overlap or conflict, the following precedence applies: 1. `docs/product/software-specification.md` — the authoritative statement of **what** the gateway shall do (requirements). 2. This document — the authoritative statement of **how the system is structured** to meet those requirements (architecture, boundaries, interfaces). 3. `docs/product/codex-implementation-specification.md` — the authoritative statement of **how implementation work proceeds** (phases, task sizing, test strategy, completion criteria). It restates architectural rules for implementer convenience but does not redefine them. 4. `docs/configuration/configuration-reference.md` — the authoritative reference for **configuration semantics** (field names, defaults, validation rules). 5. `AGENTS.md` — the entry-point summary for coding agents; it points to the documents above and never overrides them. A data contract or interface is defined **once** in the authoritative document for its role; other documents link to it rather than restating it with different names. Where a contract is currently restated (for historical reasons), the definition in the role-authoritative document wins. Detailed subsystem architecture is documented under: ```text docs/architecture/ ``` AquaCom-specific protocol knowledge is documented under: ```text docs/protocol/ ``` --- # 2. System purpose The AquaCom Integration Gateway provides a modern integration boundary between AquaCom-compatible field equipment and higher-level systems. The gateway shall: - communicate with AquaCom field devices; - acquire current process values; - retrieve historical process values; - normalize AquaCom-specific information into a protocol-independent model; - expose current values using OPC UA; - expose historical values using OPC UA Historical Access; - store historical data in one or more configurable destinations; - recover historical information following communication interruptions; - provide operational and protocol diagnostics. The gateway shall not make higher-level systems dependent on AquaCom-specific behavior. --- # 3. Architectural principle The central architecture is: ```text AquaCom field device │ ▼ AquaCom Transport │ ▼ AquaCom Protocol Engine │ ▼ Station / Session Manager │ ▼ Canonical Data Model │ ├─────────────────────► Current-State Service │ │ │ ▼ │ OPC UA Data Access │ └─────────────────────► Historical Pipeline │ ┌───────────┼────────────┐ │ │ │ ▼ ▼ ▼ Repository Storage A Storage B │ ▼ OPC UA Historical Access ``` The canonical data model forms the boundary between AquaCom-specific functionality and all northbound integrations. --- # 4. Architectural goals The architecture shall support: - protocol isolation; - storage independence; - stable internal identifiers; - stable OPC UA NodeIds; - correct handling of source timestamps; - reliable history recovery; - multiple historical storage destinations; - store-and-forward; - independent subsystem testing; - restart recovery; - future replacement of individual technologies; - future addition of other northbound interfaces. The architecture shall avoid tight coupling between: ```text AquaCom OPC UA Database technology Historian technology SCADA platform ``` --- # 5. Architectural boundaries The following boundaries are mandatory. ## 5.1 AquaCom boundary Only the AquaCom subsystem may: - encode AquaCom telegrams; - decode AquaCom telegrams; - calculate or verify AquaCom checksums; - interpret AquaCom operation codes; - interpret AquaCom addressing; - interpret AquaCom-specific value formats. No OPC UA or storage module shall perform AquaCom protocol processing. --- ## 5.2 Canonical model boundary AquaCom data shall be converted into canonical gateway objects before being forwarded to: - current-state handling; - history handling; - OPC UA; - storage systems; - diagnostics where appropriate. The canonical model shall remain independent of AquaCom and OPC UA. --- ## 5.3 OPC UA boundary The OPC UA subsystem shall consume canonical gateway information. It shall not: - communicate directly with AquaCom stations; - decode telegrams; - synchronously request historical data from an RTU; - depend upon a particular storage technology. --- ## 5.4 Storage boundary Storage destinations shall receive canonical historical records. Storage implementations shall not depend upon: - AquaCom telegrams; - AquaCom transport; - OPC UA server internals. --- # 6. Source tree The logical source structure is: ```text src/ ├── core/ ├── aquacom/ ├── history/ ├── storage/ ├── opcua/ ├── diagnostics/ └── host/ ``` The exact language-specific package or project structure may differ, but the architectural responsibilities shall remain equivalent. --- # 7. Dependency direction Allowed dependencies shall broadly follow: ```text host │ ┌───────────┼─────────────┐ │ │ │ ▼ ▼ ▼ opcua history diagnostics │ │ │ storage │ │ └──────┬────┘ ▼ core ▲ │ aquacom ``` The most important rule is: ```text core ``` shall not depend upon: ```text aquacom opcua storage technology ``` --- # 8. Core subsystem The `core` subsystem contains protocol-independent domain concepts. Examples include: ```text StationId PointId CurrentValue HistoricalSample DataQuality AcquisitionSource CommunicationState StationState HistorySynchronizationState ``` The core subsystem defines shared contracts used between other modules. It shall contain no AquaCom protocol logic. It shall contain no OPC UA-specific types. It shall contain no database-specific types. --- # 9. AquaCom subsystem The AquaCom subsystem contains: ```text Transport Protocol codec Telegram validation Station/session handling Live acquisition Historical acquisition Protocol diagnostics ``` Logical structure: ```text AquaCom Transport │ ▼ Protocol Codec │ ▼ Protocol Operations │ ▼ Station Session │ ├── Live Acquisition └── Historical Acquisition ``` Protocol implementation shall be evidence-based. Undocumented AquaCom behavior shall not be guessed. --- # 10. AquaCom transport The transport layer is responsible for communication only. It may support implementations such as: ```text TCP Serial Serial-over-IP Other supported AquaCom transport ``` The transport layer shall not interpret process values. Conceptual interface: ```text open close send receive health ``` --- # 11. AquaCom protocol engine The protocol engine is responsible for: - framing; - telegram validation; - checksum handling; - request encoding; - response decoding; - protocol error interpretation. Conceptual transformation: ```text raw bytes │ ▼ AquaCom message │ ▼ logical protocol result ``` The codec shall be independently testable without a physical AquaCom device. --- # 12. Station/session manager Each AquaCom station has an independent logical session. Conceptual station states: ```text DISABLED INITIALIZING CONNECTING ONLINE DEGRADED OFFLINE RECOVERING ``` One failing station shall not stop communication with unrelated stations. The Station Manager owns: - station lifecycle; - communication status; - retries; - scheduling; - station diagnostics; - history recovery coordination. --- # 13. Canonical data model The gateway uses a protocol-independent canonical model. ## 13.1 CurrentValue Conceptually: ```text CurrentValue StationId PointId Value DataType Quality SourceTimestamp ReceivedTimestamp UpdatedTimestamp AcquisitionSource ``` --- ## 13.2 HistoricalSample Conceptually: ```text HistoricalSample StationId PointId Value DataType Quality SourceTimestamp ReceivedTimestamp AcquisitionSource AcquisitionId ``` Historical samples shall retain the timestamp associated with the process state. --- # 14. Timestamp model The gateway shall distinguish at least: ```text SourceTimestamp ReceivedTimestamp ``` Where applicable also: ```text UpdatedTimestamp ServerTimestamp ``` Their meanings are: | Timestamp | Meaning | |---|---| | SourceTimestamp | Time associated with the value at the source | | ReceivedTimestamp | Time the gateway received the information | | UpdatedTimestamp | Time current gateway state was changed | | ServerTimestamp | Timestamp used by the OPC UA server | The following must never be assumed: ```text ReceivedTimestamp = SourceTimestamp ``` --- # 15. Fundamental historical rule The fundamental historical-data rule is: > A historical sample represents the process at its SourceTimestamp, not at the time the gateway receives the sample. Example: ```text Historical value: SourceTimestamp = 14:05 ReceivedTimestamp = 18:30 ``` The value belongs to history at: ```text 14:05 ``` It shall not become a new current process value at: ```text 18:30 ``` --- # 16. Live-data architecture Live AquaCom values follow: ```text AquaCom response │ ▼ Protocol decode │ ▼ Point mapping │ ▼ Canonical CurrentValue │ ▼ Current-State Service │ ├────────► OPC UA │ └────────► Historical pipeline if live historization is enabled ``` The Current-State Service maintains the latest accepted value for each configured point. --- # 17. Current-State Service Responsibilities: - maintain the latest current value; - reject obsolete current-state updates where applicable; - expose current values to OPC UA; - notify subscribers of valid changes; - preserve quality and timestamps. Conceptual interface: ```text update(CurrentValue) get(PointId) getAll(StationId) subscribe(PointId) ``` Historical backfill shall not directly call `update(CurrentValue)`. --- # 18. Historical-data architecture Historical AquaCom data follows: ```text AquaCom history │ ▼ Historical Acquisition Manager │ ▼ Canonical HistoricalSample │ ▼ Historical Pipeline │ ├────────► History Repository ├────────► Storage Sink A ├────────► Storage Sink B └────────► Other configured destinations ``` The historical pipeline is independent from OPC UA. --- # 19. Historical Acquisition Manager The Historical Acquisition Manager is responsible for: - determining missing intervals; - requesting AquaCom history; - processing historical responses; - maintaining synchronization state; - managing watermarks; - performing reconnect/backfill; - throttling history retrieval; - avoiding interference with live polling. Live acquisition shall normally have higher communication priority than bulk history recovery. --- # 20. Historical synchronization Each station may maintain persistent synchronization state. Conceptually: ```text StationId HistoryStreamId LastCompleteTimestamp LastAttemptTimestamp LastSuccessfulTimestamp SynchronizationState ``` Example: ```text 12:00 history synchronized 12:03 communication lost 17:24 communication restored 12:00 → 17:24 identified as recovery interval ``` The gateway then retrieves available AquaCom history for that interval. --- # 21. Watermark rule A history synchronization watermark shall only advance after the corresponding interval has been successfully handled according to the configured persistence policy. "Successfully handled" is defined precisely as: **the samples of the interval have been durably spooled**, meaning the records have been committed to persistent spool storage and would be re-delivered after a restart. Delivery to the final storage destinations is tracked independently through the per-destination acknowledgements described in §24 and does not gate the watermark. This distinction matters for restart behavior: if the watermark required final delivery, a gateway restart during a storage outage would force re-retrieval of the entire interval from the AquaCom station (or loss of it, if the station has since overwritten its own history). Advancing the watermark on durable spool, combined with at-least-once idempotent delivery, keeps recovery bounded to the spool rather than the field device. The following is prohibited: ```text receive historical packet │ ▼ advance watermark │ ▼ storage fails ``` Preferred behavior is: ```text receive ↓ validate ↓ persist/durably queue ↓ advance synchronization state ``` --- # 22. Historical pipeline The historical pipeline shall conceptually perform: ```text HistoricalSample │ ▼ Validation │ ▼ Normalization │ ▼ Deduplication │ ▼ Durable Spool │ ▼ Distribution ``` This pipeline provides a stable boundary between acquisition and storage. **Arrival order is not chronological.** Live historization produces samples at the current time while backfill delivers older intervals afterwards, so the pipeline must accept samples in arbitrary order relative to `SourceTimestamp`. Storage adapters shall therefore support out-of-order writes, and historical queries shall order results by `SourceTimestamp`, never by storage arrival order. --- # 23. Deduplication The default historical logical identity is: ```text StationId + PointId + SourceTimestamp ``` A stronger AquaCom-provided identifier may be used where verified. Identical samples shall not create unintended duplicate history. Conflicting samples sharing the same logical identity shall generate diagnostics. The default conflict strategy should favor explicit conflict detection rather than silent overwrite. Deduplication state shall survive gateway restart, at least for the interval of any in-progress synchronization. Otherwise a restart during backfill would cause the already-received portion of the interval to be stored twice. Two implementation options satisfy this: persisting deduplication state alongside the synchronization watermark, or relying on idempotent storage (the at-least-once delivery described in §24) and treating deduplication as an efficiency measure for steady-state operation. The chosen option shall be documented in the relevant ExecPlan. The deduplication window shall be bounded; an unbounded identity cache violates §51 (resource boundaries). Deduplication operates on samples in **arrival order**, which during backfill is generally not chronological order (see §22 ordering note). The implementation shall not assume chronological input. --- # 24. Durable spool The historical spool provides restart-safe delivery. Conceptually: ```text HistoricalSample │ ▼ Persistent spool │ ├────► Repository ├────► Sink A └────► Sink B ``` Each destination maintains independent acknowledgement. Example: ```text Record 4711 Repository ACK CentralHistorian ACK Archive PENDING ``` The record remains until configured delivery requirements have been fulfilled. --- # 25. History Repository A History Repository is a queryable historical source. It provides operations conceptually equivalent to: ```text store storeBatch readRaw readAtTime getBounds health ``` The repository used by OPC UA Historical Access is selected by configuration. The OPC UA implementation shall not know whether the repository is: ```text relational database time-series database embedded historian industrial historian other queryable implementation ``` --- # 26. Storage Sink A Storage Sink is a destination receiving historical records. Conceptual interface: ```text initialize write writeBatch flush health shutdown ``` A sink does not need to support historical queries. Examples: ```text SQL database time-series database enterprise historian file archive message broker data lake connector ``` --- # 27. Repository versus sink These shall remain separate concepts: ```text Repository = query historical data Sink = receive historical data ``` One implementation may support both. Example: ```text Local historian Repository: yes Sink: yes Archive export Repository: no Sink: yes ``` --- # 28. Multiple storage destinations A historical record may be delivered to multiple independent destinations. Example: ```text Historical Pipeline │ ┌───────────────┼────────────────┐ │ │ │ ▼ ▼ ▼ Local Repository Central DB Archive ``` Failure of one destination shall not unnecessarily block successful destinations. --- # 29. OPC UA architecture The OPC UA subsystem provides northbound access to normalized gateway information. Logical components: ```text OPC UA Server │ ├── Namespace Manager ├── Current Value Provider ├── Historical Provider ├── Quality Mapper ├── Diagnostics Provider └── Security ``` --- # 30. OPC UA current data Current values are exposed through normal OPC UA Data Access. Mapping: ```text CurrentValue.Value ↓ OPC UA Value CurrentValue.SourceTimestamp ↓ OPC UA SourceTimestamp Gateway server time ↓ OPC UA ServerTimestamp CurrentValue.Quality ↓ OPC UA StatusCode ``` --- # 31. OPC UA Historical Access Historical Access shall query the configured History Repository. Correct flow: ```text OPC UA Client │ │ HistoryRead ▼ OPC UA Server │ ▼ Historical Provider │ ▼ History Repository │ ▼ HistoricalSample[] │ ▼ OPC UA DataValue[] ``` --- # 32. Prohibited HistoryRead architecture The following architecture is prohibited: ```text OPC UA HistoryRead │ ▼ AquaCom request │ ▼ wait for RTU │ ▼ OPC UA response ``` Historical synchronization and historical client access must be decoupled. --- # 33. OPC UA namespace The default logical namespace shall resemble: ```text AquaCom │ ├── Gateway │ ├── Status │ ├── Version │ ├── StartTime │ ├── ConfigurationVersion │ ├── HistoricalQueueDepth │ └── Storage │ └── Stations │ ├── PS001 │ ├── Process │ │ ├── Level │ │ ├── Pump01Running │ │ └── Pump02Running │ │ │ └── Diagnostics │ ├── CommunicationState │ ├── LastCommunication │ ├── HistoryState │ └── HistoryWatermark │ └── PS002 ``` Exact organization may be configurable. --- # 34. Stable OPC UA NodeIds OPC UA NodeIds shall derive from stable engineering identifiers. Example: ```text station/PS001/point/LEVEL ``` Changing: ```text Wet well level ``` to: ```text Inlet sump level ``` shall not normally change the NodeId. Stable NodeIds are required to preserve client configuration. --- # 35. Diagnostics architecture Diagnostics are separate from process data. Conceptually: ```text Diagnostics │ ├── Gateway │ ├── Station │ ├── AquaCom Protocol │ ├── History │ ├── Storage └── OPC UA ``` Diagnostics may be exposed through: - logs; - metrics; - OPC UA diagnostic nodes; - future management interfaces. --- # 36. Gateway diagnostics Examples: ```text GatewayState Version ConfigurationVersion StartTime Uptime StationCount OnlineStationCount HistoricalQueueDepth SpoolDiskUsage OPCUAState ``` --- # 37. Station diagnostics Examples: ```text CommunicationState LastRequest LastResponse LastSuccessfulCommunication ConsecutiveFailures ProtocolErrors HistorySynchronizationState HistoryWatermark HistoricalBacklog ``` --- # 38. Storage diagnostics Per destination: ```text State LastSuccessfulWrite LastFailure PendingRecords RetryCount Latency ``` A storage failure shall be identifiable independently from an AquaCom communication failure. --- # 39. Logging Structured logging is preferred. Useful context includes: ```text timestamp severity component stationId pointId operation correlationId message error ``` Raw AquaCom telegram logging shall be separately configurable. --- # 40. Configuration architecture Configuration shall be external and machine-readable. Conceptual structure: ```text Gateway Configuration │ ├── Gateway ├── AquaCom ├── Stations ├── Points ├── History ├── Storage ├── OPC UA ├── Security ├── Diagnostics └── Logging ``` Configuration validation occurs before activation. --- # 41. Station configuration A station definition contains concepts equivalent to: ```text StationId Enabled Transport AquaComAddress ProtocolProfile LiveAcquisition HistoricalAcquisition PointDefinitionSource Timezone ``` Station configuration shall not be embedded directly in protocol source code. --- # 42. Point configuration A point contains concepts equivalent to: ```text PointId DisplayName Description SourceReference DataType EngineeringUnit Scaling LiveEnabled HistoryEnabled OPCUAEnabled Historizing StoragePolicy ``` `PointId` shall remain stable even if presentation metadata changes. --- # 43. Security boundaries The architecture assumes AquaCom is a legacy field protocol. Security shall therefore be applied around the AquaCom communication environment. Conceptually: ```text SCADA / client network │ ▼ Firewall / segmentation │ ▼ AquaCom Gateway │ ▼ OT communication network │ ▼ Site firewall/router/VPN │ ▼ AquaCom RTU ``` The gateway shall not assume that AquaCom itself provides modern confidentiality, authentication or authorization. --- # 44. OPC UA security OPC UA security is handled within the OPC UA subsystem. Production architecture shall support: ```text application certificates trusted client management secure channels authentication authorization encrypted communication ``` Insecure endpoints shall not be the normal production default. --- # 45. Secrets boundary Secrets shall not form part of normal version-controlled configuration. Examples: ```text database passwords API tokens private keys certificate private keys ``` These shall be injected through an external secret mechanism. --- # 46. Host subsystem The `host` subsystem composes the application. Responsibilities include: - configuration loading; - dependency construction; - subsystem startup; - lifecycle management; - shutdown; - top-level health state. The host shall not become a location for protocol or business logic. --- # 47. Startup architecture Conceptual startup sequence: ```text Load configuration │ ▼ Validate configuration │ ▼ Load persistent state │ ▼ Initialize storage │ ▼ Initialize historical services │ ▼ Initialize OPC UA │ ▼ Initialize AquaCom stations │ ▼ Start live acquisition │ ▼ Start historical synchronization ``` A temporary failure of a non-critical secondary storage destination should not necessarily prevent the gateway from starting. --- # 48. Shutdown architecture Conceptual controlled shutdown: ```text Stop accepting administrative changes │ ▼ Stop scheduling new acquisition │ ▼ Complete/cancel active transactions safely │ ▼ Persist synchronization state │ ▼ Flush durable state │ ▼ Stop OPC UA │ ▼ Close storage │ ▼ Terminate ``` --- # 49. Restart recovery After an unclean restart: ```text Load configuration │ ▼ Recover persistent spool │ ▼ Restore synchronization watermarks │ ▼ Reconnect AquaCom stations │ ▼ Resume live acquisition │ ▼ Resume historical recovery ``` Live acquisition should resume before large backlog processing. --- # 50. Scheduling priorities Where AquaCom communication capacity is limited, scheduling shall conceptually prioritize: ```text 1. communication/session health 2. current/live acquisition 3. alarms/events when implemented 4. explicit configuration operations 5. historical backfill 6. low-priority maintenance ``` Historical synchronization shall be throttleable. --- # 51. Resource boundaries All queues and caches shall be bounded. This applies to: ```text AquaCom request queues history queues storage retry queues OPC UA historical result sets continuation state logging buffers spool storage ``` Overflow behavior shall be explicit and observable. --- # 52. Testing architecture The system shall support independent testing of each architectural boundary. Conceptually: ```text Protocol Fixtures │ ▼ AquaCom Codec Tests Simulator │ ▼ Session / Acquisition Tests Historical Fixtures │ ▼ History Pipeline Tests Repository │ ▼ OPC UA HA Tests Current-State Service │ ▼ OPC UA DA Tests ``` --- # 53. AquaCom simulator The simulator shall permit development without operational AquaCom equipment. Supported scenarios shall eventually include: ```text normal live values normal history timeouts disconnects delayed response malformed telegram bad checksum duplicate history conflicting history clock error reconnect backfill ``` The simulator is part of the architecture, not merely a temporary development tool. --- # 54. Protocol evidence architecture AquaCom implementation is linked to documented evidence. Relevant repository area: ```text docs/protocol/ ``` Recommended structure: ```text aquacom.md known-operations.md protocol-gaps.md test-vectors.md ``` Every implemented AquaCom behavior should be traceable to: ```text Specification Capture Known-good implementation Approved test vector ``` Unknown behavior remains explicitly unresolved. --- # 55. Error isolation Failures shall remain contained where possible. Examples: | Failure | Expected isolation | |---|---| | Station A offline | Station B continues | | Storage A offline | Storage B continues | | OPC UA client disconnect | Acquisition continues | | OPC UA server problem | AquaCom acquisition should continue where possible | | Historical backfill fails | Live acquisition continues | | Malformed AquaCom telegram | Telegram rejected, station diagnostics updated | | Secondary storage failure | Durable spool retains pending delivery | --- # 56. Future extension points The architecture shall permit future addition of: ```text OPC UA Alarms & Conditions AquaCom alarms/events AquaCom commands setpoint changes MQTT REST API external analytics central configuration redundant gateways high availability additional history repositories additional storage sinks ``` These shall be added behind explicit subsystem interfaces. --- # 57. Future process-control architecture If control functionality is introduced later, it shall use a separate command pipeline: ```text Northbound request │ ▼ Authentication │ ▼ Authorization │ ▼ Command validation │ ▼ Command service │ ▼ AquaCom command │ ▼ Confirmation / readback │ ▼ Audit ``` A direct mapping from arbitrary OPC UA writes to raw AquaCom telegrams is not an acceptable control architecture. --- # 58. Architectural invariants The following invariants shall hold throughout implementation. ## INV-001 AquaCom-specific logic exists only behind the AquaCom abstraction. ## INV-002 The canonical model contains no AquaCom telegram representation. ## INV-003 The canonical model contains no OPC UA-specific representation. ## INV-004 Historical samples do not update current state solely because they were recently retrieved. ## INV-005 Historical SourceTimestamp is preserved. ## INV-006 OPC UA HistoryRead queries a repository, not an AquaCom device. ## INV-007 A storage failure does not directly stop unrelated live AquaCom acquisition. ## INV-008 Point identity remains stable across display-name changes. ## INV-009 OPC UA NodeIds remain stable across restart and normal upgrades. ## INV-010 Unverified AquaCom protocol details are not implemented as guesses. ## INV-011 Synchronization state required for recovery is persistent. ## INV-012 Historical delivery supports bounded persistent buffering. ## INV-013 Historical samples may arrive out of chronological order; storage adapters support out-of-order writes and queries order by SourceTimestamp. ## INV-014 The history synchronization watermark advances only on durable spool commit, and restart recovery of undelivered samples is bounded to the spool rather than the field device. ## INV-015 Deduplication remains correct across restart; a restart during synchronization does not silently introduce duplicate historical records. ## INV-016 A historical record without a usable SourceTimestamp is quarantined with diagnostics, never silently stored as process history. --- # 59. Primary end-to-end data flows ## 59.1 Live data ```text AquaCom RTU │ ▼ Transport │ ▼ Protocol Engine │ ▼ Station Manager │ ▼ CurrentValue │ ▼ Current-State Service │ ├────► OPC UA │ └────► Historical Pipeline when live historization is enabled ``` --- ## 59.2 AquaCom historical recovery ```text AquaCom RTU │ ▼ Historical Acquisition │ ▼ HistoricalSample │ ▼ Validation │ ▼ Deduplication │ ▼ Durable Spool │ ├────► Repository ├────► Storage A └────► Storage B ``` --- ## 59.3 OPC UA historical request ```text OPC UA Client │ ▼ HistoryRead │ ▼ OPC UA Historical Provider │ ▼ History Repository │ ▼ HistoricalSample[] │ ▼ OPC UA DataValue[] ``` --- # 60. Reference architecture The complete reference architecture is: ```text FIELD / AQUACOM │ ▼ ┌─────────────────────┐ │ AquaCom Transport │ └──────────┬──────────┘ │ ▼ ┌─────────────────────┐ │ Protocol Engine │ └──────────┬──────────┘ │ ▼ ┌─────────────────────┐ │ Station Manager │ └──────────┬──────────┘ │ ▼ ┌─────────────────────┐ │ Canonical Model │ └───────┬───────┬─────┘ │ │ LIVE HISTORY │ │ ▼ ▼ ┌──────────────┐ ┌──────────────────┐ │Current-State │ │Historical │ │Service │ │Acquisition │ └──────┬───────┘ └────────┬─────────┘ │ │ │ ▼ │ ┌──────────────────┐ │ │Historical │ │ │Pipeline │ │ └────────┬─────────┘ │ │ │ ┌──────────┼───────────┐ │ │ │ │ │ ▼ ▼ ▼ │ Repository Sink A Sink B │ │ │ │ ▼ ▼ ┌────────────────────────────┐ │ OPC UA Server │ │ │ │ Data Access │ │ Historical Access │ │ Diagnostics │ └──────────────┬─────────────┘ │ ▼ SCADA / Clients ``` --- # 61. Architecture decision summary The gateway is intentionally designed as an: ```text AquaCom Integration Gateway ``` rather than merely an: ```text AquaCom OPC UA Server ``` This allows: - OPC UA to be replaced or supplemented; - storage technology to change; - multiple historians to coexist; - AquaCom equipment to be gradually retired; - other northbound interfaces to be added; - historical acquisition to continue independently of OPC UA clients. The long-term architectural asset is therefore the normalized integration layer and historical recovery mechanism, not any single external interface. --- # 62. Final architectural rule The most important data rule is: > Historical data is stored and exposed according to when the process value was valid, not when the gateway happened to retrieve it. The most important protocol rule is: > AquaCom behavior must be based on verified protocol knowledge and must never be invented merely to complete an implementation. The most important software rule is: > AquaCom, canonical data handling, historical persistence and OPC UA shall remain separate architectural concerns.