terra-view/docs/adr/0001-device-data-ownership.md

ADR 0001 — Device data ownership: modules own raw data, Terra-View owns fleet context

• Status: Accepted (SLMM grandfathered as a known exception — see Consequences)
• Date: 2026-06-16
• Deciders: Brian
• Applies to: Terra-View core and all device modules (SFM, SLMM, and future modules)

Context

Terra-View is a fleet-management / UI layer that talks to specialized device modules, each of which speaks one device's protocol (see the architecture note in CLAUDE.md). Two modules exist today, and they store their data differently:

• SFM (seismograph / seismo-relay). Owns its own database and waveform store. Terra-View holds no seismic event or waveform data — it reads through live, e.g. GET {SFM_BASE_URL}/db/events (backend/routers/activity.py, backend/routers/admin_modules.py). Terra-View renders; SFM persists.
• SLMM (sound level meters). A thin device-control shim. The sound measurement data is stored in Terra-View — MonitoringSession + DataFile rows in data/seismo_fleet.db, and the .rnh + Leq .rnd files under data/Projects/{project_id}/{session_id}/ (backend/routers/project_locations.py:_ingest_file_entries). SLMM only keeps device config + a live-status cache (slmm.db) and a transient download staging area (data/downloads/{unit_id}/).

This inconsistency is real, not cosmetic. It raises an obvious question every time we add a feature or a module: where does this device's data live? Without a stated rule, the answer drifts per-module, which is exactly how conceptual integrity erodes.

Why the asymmetry exists (history, not sloppiness)

1. Path dependence. seismo-relay pre-existed as a complete data system; Terra-View integrated with it. SLMM was built fresh as a control shim, so persistence drifted up into Terra-View.
2. Coupling. A seismic event is largely self-contained — Terra-View just tags it to a unit. A Leq interval is only meaningful against an NRL location + baseline + report config, which are Terra-View concepts. Sound data has stronger natural gravity toward Terra-View ownership than seismic events do.

Decision

Adopt one explicit ownership rule for all device data:

The device module owns the raw device data (waveforms, events, Leq files, raw telemetry). Terra-View owns the fleet/project/location/session/report context that gives that data meaning.

Note this is not "Terra-View stores nothing" — Terra-View remains the system of record for roster, projects, locations, deployments, history, schedules, and the associations between fleet entities and module-owned data. What it should not own is a second copy of raw device telemetry.

Litmus test for any "where does this live?" call: whose question does this data answer?

• "What did the sensor record?" (raw waveform / Leq rows) → the module.
• "Which NRL, which night, versus which baseline?" (context) → Terra-View.

Application

• New device modules MUST follow the SFM pattern: the module owns its data and exposes a read API (/db/* or equivalent); Terra-View references it and reads through, rather than ingesting a copy.
• SFM already conforms. No change.
• SLMM does not conform and is explicitly grandfathered (see Consequences).

Consequences

Positive

• Consistent module boundaries → lower cognitive load, fewer "which copy is authoritative?" bugs.
• Terra-View stays thin; "add a device type = add a module" stays true (the CLAUDE.md north star).
• Single source of truth for raw data; no silent duplication.

Negative / costs

• Realigning SLMM to this rule is a non-trivial refactor: move ingest + file storage into SLMM, build a SLMM read API, repoint the report engine and the Data Files UI to read through it, handle the session↔location association across the module boundary, and migrate existing MonitoringSession/DataFile data. The FTP night-report pipeline currently assumes Terra-View ownership.

SLMM grandfather clause

• SLMM stays as-is for now. Realignment is a deliberate future project, not a background cleanup, and should be triggered by a real signal — e.g. a 3rd device type arriving, or the duplication/coupling actually causing pain. Until then, Terra-View remains the system of record for sound data, and that is an accepted, documented exception rather than an aspiration.
• The current sound data flow (for reference): NL-43 SD card → (FTP) → SLMM data/downloads/ → (proxy ZIP) → Terra-View ingest → data/Projects/ + seismo_fleet.db. The 1-second _Lp_ files are dropped at ingest and never land in Terra-View.

Related

• CLAUDE.md — module architecture ("Terra-View does NOT communicate directly with physical devices").
• FTP night-report pipeline (feat/ftp-report-pipeline) — built on the current SLMM/Terra-View-ownership model; a future SLMM realignment would need to repoint it.