Data layer

The nxt-backend monorepo uses a mixed data architecture for operational and time-series workloads.

Data ownership model

Supabase/PostgreSQL is the transactional system of record (users, organizations, billing entities, operational state).
Supabase Auth owns authentication and identity concerns.
TimescaleDB owns high-volume telemetry, snapshots, and time-series analytics paths.

supabase/
- migrations/ for relational schema evolution.
- functions/ for edge/runtime functions such as customer/order/meter-consumption related handlers.
- config.toml for local Supabase runtime configuration.
libs/timeseries/
- TypeORM-backed Timescale connection and snapshot entities.
- Dedicated migration path under libs/timeseries/migration.
App-level ownership:
- tiamat: transactional business state and operational APIs.
- yeti: telemetry and snapshot generation.
- loch: async automation that reads/writes both planes as needed.

TypeORM is used intentionally for TimescaleDB access.
For the primary Supabase Postgres database, migration away from legacy TypeORM usage is in progress.

Classify the change as transactional, time-series, or both.
Apply schema evolution in the owning path (supabase/ vs time-series migration path).
Update app/service logic in owning components (tiamat, talos, loch, yeti).
Validate integration behavior where transactional state and telemetry-derived state intersect.

Keep transactional and telemetry access patterns separate unless a clear join strategy is defined.
Time-series changes should define retention/backfill implications before rollout.
Validate freshness expectations for snapshot tables that feed operator-facing diagnostics.
For Supabase function changes, confirm JWT requirements and function entrypoint wiring remain consistent with supabase/config.toml.