ADM Demo Seed Design

Date: 2026-05-12
Status: Draft for review

Goal

Extend the backend demo seed so it creates a second demo organization named ADM with usable accounts and baseline operational data. The new seed must allow immediate login and role-based usage for:

  • admin
  • owner
  • staff

The change must preserve the existing bun run seed:demo workflow and keep seed execution idempotent through deterministic IDs.

Context

The current demo seed in backend/src/database/seeds/demo-data.seed.ts is a single large scenario for the Bến Tre organization. It creates one organization plus users, area and pond assignments, devices, telemetry, alerts, notifications, and aquaculture data.

Adding ADM by duplicating another large hardcoded block would work, but it would make the file harder to maintain and more error-prone. The preferred change is to keep one demo seed entrypoint while refactoring the seed into reusable organization-scenario helpers.

Scope

In scope:

  • Refactor the demo seed to support more than one organization scenario.
  • Add a fully usable ADM organization scenario.
  • Seed ADM users for admin, owner, and staff.
  • Seed enough related data for those roles to use the product immediately after login.
  • Add tests first for the new organization-scenario behavior.

Out of scope:

  • Changing auth, RBAC, controller, or service behavior outside seed support.
  • Creating a separate seed command for ADM.
  • Expanding the ADM scenario to match the full richness of the Bến Tre scenario unless needed by role usability.

Requirements

Functional Requirements

The seed must create:

  • one active organization named ADM
  • one admin account in ADM
  • one owner account in ADM
  • one staff account in ADM
  • at least one area in ADM
  • at least two active ponds in ADM
  • owner assignments for the area and ponds
  • assigned_resources for the owner and staff user-role records
  • minimal device, telemetry, alert, and notification data so key role-facing pages are not empty

The seed must also:

  • keep deterministic IDs via seedId(...)
  • keep the existing demo seed command and transaction behavior
  • remain safe to re-run without generating identity drift

Non-Functional Requirements

  • Follow existing entity creation patterns in the seed file.
  • Keep the refactor focused and avoid introducing a large abstraction layer.
  • Keep TypeScript strict and avoid any.

Proposed Approach

Refactor seedDemoData() into a small set of internal helpers that can seed an organization-specific scenario from explicit configuration and related derived data.

The helper boundaries should be practical rather than overly generic:

  • create or define organization data
  • create users and their primary roles
  • create areas and ponds
  • apply area and pond ownership assignments
  • populate assigned_resources in user_roles
  • create minimal operational data for the scenario

The existing Bến Tre scenario remains in the same file and keeps its current dataset. The ADM scenario is added as a second organization configuration using the same helper flow.

ADM Scenario Design

Organization

ADM will be seeded as a standalone active organization with deterministic ID, stable code, and the same basic settings structure used by the existing demo organization.

Accounts

ADM will include these role-bearing users:

  • admin
  • owner
  • staff

Each account will have:

  • deterministic ID
  • email in an adm namespace
  • shared demo password matching the current seed convention
  • active status
  • organizationId pointing to ADM

Farm Structure

ADM will include:

  • one area
  • two active ponds inside that area

This is the minimum structure that supports owner assignment, staff resource assignment, and device attachment while staying smaller than the Bến Tre scenario.

Role Assignment Rules

  • admin receives the ADMIN role in ADM
  • owner receives the OWNER role in ADM
  • staff receives the STAFF role in ADM
  • owner is assigned to the ADM area and both ponds
  • owner user-role assigned_resources contains both pond IDs
  • staff user-role assigned_resources contains the active pond IDs they should operate on

This mirrors the existing seed pattern where resource assignments are stored in user_roles.assigned_resources.

Minimal Operational Data

ADM will get a thin but usable operational dataset:

  • at least one sensor attached to a pond
  • at least one additional device if needed to reflect common device pages
  • recent telemetry for the online device set
  • at least one alert
  • at least one notification targeting the owner or admin

The objective is not full parity with Bến Tre. The objective is to ensure ADM users can log in and see realistic data on core role-facing surfaces without landing in an empty-state-only experience.

Testing Strategy

Tests will be written before production changes and will verify the seeded outcome for ADM.

The test coverage should validate:

  • ADM organization is created
  • three ADM users are created
  • each user is linked to the expected role
  • area and pond ownership assignments are present
  • assigned_resources values are populated for owner and staff
  • the seed remains deterministic for seeded identities

The tests should target the refactored seed behavior at the smallest practical integration level, using the existing backend test patterns where possible.

Risks and Mitigations

Risk: seed file complexity increases during refactor

Mitigation:

  • refactor only the parts needed to support multi-organization scenarios
  • keep helper scope local to the seed module

Risk: ADM dataset is too thin for some pages

Mitigation:

  • include the smallest set of device and telemetry data that still makes dashboard and operations flows usable
  • preserve room to expand the ADM scenario later without altering the seed structure again

Risk: role assignments diverge from existing filtering logic

Mitigation:

  • reuse the same assignment tables and assigned_resources pattern already used in the Bến Tre seed
  • validate seeded relationships in tests

Implementation Notes

  • Keep backend/src/database/seeds/run-seed.ts unchanged except for any import or invocation adjustments required by the refactor.
  • Prefer helper extraction inside backend/src/database/seeds/demo-data.seed.ts over creating many new files.
  • Keep logs and summary output updated so the seed reports the new ADM organization and accounts clearly.

Success Criteria

The work is successful when:

  • bun run seed:demo seeds both the existing demo organization and ADM
  • ADM includes working admin, owner, and staff accounts
  • those accounts have enough associated data to use role-based flows immediately
  • the code remains maintainable and deterministic