| 1 | <!-- English translation of adr/0102-data-acquisition-layer-boundary-and-contract.md. Canonical Russian: ../../adr/0102-data-acquisition-layer-boundary-and-contract.md --> |
| 2 | |
| 3 | # ADR 0102: Data Acquisition Layer - boundary of external interfaces and adapters |
| 4 | |
| 5 | **Status:** Accepted |
| 6 | **Date:** 2026-04-26 |
| 7 | |
| 8 | ## Related ADRs |
| 9 | |
| 10 | | ADR | Role | |
| 11 | |-----|------| |
| 12 | | [0006](0006-presentation-layers-and-feature-slices.md) | linked ADR | |
| 13 | | [0008](0008-mcp-contracts-and-testable-infrastructure.md) | linked ADR | |
| 14 | | [0009](0009-strangler-migration-and-exceptions.md) | linked ADR | |
| 15 | | [0094](0094-ingestion-bus-afdx-analogy-and-threading-channels.md) | linked ADR | |
| 16 | | [0095](0095-workspace-solution-ide-health-stratification.md) | linked ADR | |
| 17 | | [0097](0097-cockpit-compute-units-transport-to-channel-dto.md) | linked ADR | |
| 18 | | [0099](0099-ide-databus-typed-events-and-projections.md) | linked ADR | |
| 19 | |
| 20 | |
| 21 | ## Summary |
| 22 | |
| 23 | - **DAL** is an explicit boundary for the extraction of external data. |
| 24 | - Contract DAL ↔ CCU ↔ UI; raw I/O is not in the VM. |
| 25 | |
| 26 | |
| 27 | --- |
| 28 | |
| 29 | <a id="adr0102-context"></a> |
| 30 | |
| 31 | ## 1. Context |
| 32 | |
| 33 | The code base contains computational units (CCUs), an orchestration in the `MainWindowViewModel` and a set of services/adapters that read external sources (files, processes, configs, wire payload). |
| 34 | Without a separate canonical term and boundary, this outer layer “spreads” across `Services`, `ViewModels`, and sometimes ends up in `ComputingUnits`. |
| 35 | |
| 36 | This creates drift: |
| 37 | |
| 38 | - CCUs begin to mix with IO; |
| 39 | - it is difficult to automatically check boundaries with analyzers; |
| 40 | - the connectivity and cost of refactoring increases. |
| 41 | |
| 42 | --- |
| 43 | |
| 44 | <a id="adr0102-decision"></a> |
| 45 | |
| 46 | ## 2. Solution |
| 47 | |
| 48 | Introduce and consolidate a single term: **Data Acquisition Layer (DAL)**. |
| 49 | |
| 50 | `DAL` - a layer of external interfaces for the computing circuit: incoming collection/reading and outgoing data transfer to the outside. |
| 51 | |
| 52 | <a id="adr0102-dal-in-scope"></a> |
| 53 | |
| 54 | ### DAL includes |
| 55 | |
| 56 | - `fs` operations (`File`, `Directory`, existence check, paths); |
| 57 | - launching external processes and collecting their output; |
| 58 | - parse/serialize external formats (`json`, `toml`, wireload); |
| 59 | - integration resolvers and source adapters. |
| 60 | - outgoing transmission to the outside (recording, sending, external calls), where required by the feature. |
| 61 | |
| 62 | <a id="adr0102-dal-out-of-scope"></a> |
| 63 | |
| 64 | ### Not included in DAL |
| 65 | |
| 66 | - calculation of semantic snapshot/DTO of the channel; |
| 67 | - UI rendering and UI composition; |
| 68 | - slot/surface routing. |
| 69 | |
| 70 | --- |
| 71 | |
| 72 | <a id="adr0102-ccu-ui-boundary"></a> |
| 73 | |
| 74 | ## 3. Border with CCU and UI |
| 75 | |
| 76 | - **DAL**: Mines and normalizes external data. |
| 77 | - **CCU** (`Cockpit/ComputingUnits/*`): Counts semantic snapshot/DTO from an already prepared input. |
| 78 | - **CDS/UI**: displays completed images. |
| 79 | |
| 80 | Invariant: |
| 81 | |
| 82 | 1. CCU does not make direct external calls (neither inbound nor outbound). |
| 83 | 2. DAL does not replace the CCU channel composition. |
| 84 | 3. `MainWindowViewModel` does not become a place for mass data extraction from the outside world. |
| 85 | |
| 86 | --- |
| 87 | |
| 88 | <a id="adr0102-code-layout"></a> |
| 89 | |
| 90 | ## 4. Code placement (strangler) |
| 91 | |
| 92 | Basic DAL placement: |
| 93 | |
| 94 | - `Features/<Feature>/DataAcquisition/*` |
| 95 | |
| 96 | Adjacent layer for orchestration/use-case logic: |
| 97 | |
| 98 | - `Features/<Feature>/Application/*` |
| 99 | |
| 100 | Division of responsibility: |
| 101 | |
| 102 | - `DataAcquisition` - external world adapters (I/O, process, wire, API). |
| 103 | - `Application` - preparation of use-case payload/script rules without direct external calls. |
| 104 | For orchestration classes, explicit naming `*Orchestrator` is recommended. |
| 105 | - `CCU` - calculation of semantic snapshot/DTO of the channel. |
| 106 | |
| 107 | During the transition phase, narrow adapters in `Services/*` are allowed if: |
| 108 | |
| 109 | - there is an explicit interface; |
| 110 | - the layer does not support the UI; |
| 111 | - there is a plan for transferring to the feature infrastructure. |
| 112 | |
| 113 | --- |
| 114 | |
| 115 | <a id="adr0102-first-slice-example"></a> |
| 116 | |
| 117 | ## 5. Example of the first cut |
| 118 | |
| 119 | Launch circuit: |
| 120 | |
| 121 | - `LaunchProfilesStore` and `LaunchSettingsJsonImport` refer to DAL; |
| 122 | - `LaunchReadinessUnit`, `LaunchPreResolvePipelineUnit`, `LaunchProfileProjectResolveUnit` remain in the CCU; |
| 123 | - `MainWindowViewModel` performs orchestration. |
| 124 | |
| 125 | --- |
| 126 | |
| 127 | <a id="adr0102-guardrails"></a> |
| 128 | |
| 129 | ## 6. Bounds checking |
| 130 | |
| 131 | Architectural guardrails (CASCOPE*) are introduced for DAL/CCU: |
| 132 | |
| 133 | - prohibition of IO/process/wire parse in `Cockpit/ComputingUnits/*`; |
| 134 | - prohibit CCU dependencies on `ViewModels/Views/Ui*`; |
| 135 | - step-by-step rollout: warning -> baseline cleanup -> error. |
| 136 | |
| 137 | --- |
| 138 | |
| 139 | <a id="adr0102-consequences"></a> |
| 140 | |
| 141 | ## 7. Consequences |
| 142 | |
| 143 | - The boundary between “data mining vs meaning calculation” becomes clear. |
| 144 | - Refactoring `Services` into feature slices becomes deterministic. |
| 145 | - Analyzers get a clear target for the rules. |
| 146 | |
| 147 | --- |
| 148 | |
| 149 | <a id="adr0102-non-goals"></a> |
| 150 | |
| 151 | ## 8. Not goals |
| 152 | |
| 153 | - Big-bang moving all `Services/*` into one commit. |
| 154 | - Forced rename of all existing namespaces in one step. |
| 155 | - Changing the DataBus contract with this ADR. |