Database

MongoDB is the project's database and Mongoose is the ODM. V1 uses one shared MongoDB database with strict tenant isolation enforced by the backend.

Mongoose is used directly — no repository/abstraction layer on top, and no second ORM/ODM in the stack.

1 · Phase state

2 · The shared-database model

one MongoDB deployment · one database ("meridian")
 ├── tenants
 ├── users
 ├── packages
 ├── status_events
 ├── location_history
 └── website_configs
        tenant-owned collections carry tenantId on every document

Isolation contract (unchanged, locked): the backend resolves tenantId from host/session and injects it into every query filter; client-supplied tenant identifiers are never trusted; the frontend is not a security boundary. tenantId on documents is the enabler — services enforce the scoping (Phase 4/5).

3 · Collections — IMPLEMENTED IN PHASE 2

tenants — TenantModel (src/db/models/tenant.model.ts)

One logistics company. Identity only — website/branding lives separately in website_configs (locked separation).

Indexes: { slug: 1 } unique (subdomain resolution) · { status: 1 } (platform admin lifecycle lists).

users — UserModel (src/db/models/user.model.ts)

The only account-holders. Every user is one of exactly two roles.

Indexes: { email: 1 } unique (login) · { tenantId: 1 } (tenant membership) · { role: 1 } (role filtering) · partial unique { role: 1 } where role=PLATFORM_ADMIN (exactly one platform admin account) · partial unique { tenantId: 1 } where role=TENANT_ADMIN (exactly one tenant admin per tenant). The two partial uniques encode the locked cardinality at the database level.

Passwords exist ONLY as passwordHash. Authentication (hashing, sessions) is Phase 3 — this phase defines the data model only.

packages — PackageModel (src/db/models/package.model.ts)

One shipment, tenant-owned, with embedded operational detail.

Indexes: { trackingId: 1 } unique (global lookup) · { tenantId: 1, trackingId: 1 } (tenant-scoped tracking fetch) · { tenantId: 1, status: 1 } (admin work queues) · { tenantId: 1, createdAt: -1 } (newest-first lists) · { tenantId: 1, archived: 1 } (archive filtering).

status_events — StatusEventModel

Append-only audit trail. Rows are facts; packages.status is merely the cached projection of the latest event.

Indexes: { packageId: 1, createdAt: 1 } (timeline) · { tenantId: 1, packageId: 1 } (tenant-scoped event reads).

location_history — LocationHistoryModel

Append-only geographic trail. Current location lives on the package; history is never overwritten.

Indexes: { packageId: 1, createdAt: -1 } (trail + latest position) · { tenantId: 1, packageId: 1 } (tenant-scoped reads). Not exposed to customers — public projection is a later phase.

website_configs — WebsiteConfigModel

Configuration-driven tenant website definition — Platform Admin controlled (Tenant Admins have no website editing). One per tenant.

4 · There is NO Customer collection

Explicit, locked decision — and now structurally true: sender/receiver are embedded subdocuments inside Package, not references. No customers collection exists in the model registry (src/db/models/index.ts), and no role beside PLATFORM_ADMIN / TENANT_ADMIN exists.

5 · Tracking ID strategy

The database guarantee exists in Phase 2; the generation algorithm is a Phase 5 decision.

6 · Why status events and location history are separate collections

packages.currentLocation is a third thing again: a cached latest fix for cheap reads, updated whenever a history row is appended (Phase 6).

7 · Index strategy — why each exists

Indexes are the minimum set serving the known query shapes; nothing is indexed "just in case":

8 · The five locked statuses (mirrored everywhere)

PENDING · PROCESSED · IN_TRANSIT · ARRIVED_AT_FACILITY · DELIVERED

Canonical definition: src/types/domain.ts → consumed identically by the Mongoose enums, the zod validators, the realtime contracts, and the UI. No sixth status in V1.

9 · Tenant provisioning transactions (Phase 4)

Tenant creation is a multi-document write (tenant → one tenant admin → website config). It runs inside a real MongoDB transaction (withTransaction) — transactions require a replica set or mongos: Atlas tiers and a local single-node replica set (mongod --replSet rs0 + rs.initiate()) qualify; a bare standalone mongod does not. For standalone dev, the service detects the unsupported-transaction error and falls back to sequential creation with compensating deletes on failure — the invariant (no tenant without admin, no orphan configs) holds in both paths and is test-verified against a single-node replica set.

Lifecycle persistence: suspension/archival touch only tenants.status plus sessions cleanup; no tenant-owned document is ever deleted for lifecycle reasons (there is no hard-delete anywhere).

10 · Connection architecture (Phase 1 behaviour, extended in Phase 2)

src/db/index.ts: lazy connectToDatabase() cached on globalThis; MONGODB_URI from env; serverSelectionTimeoutMS: 2500 and bufferCommands: false (fail fast); pino lifecycle logs; pingDatabase() behind /api/health and /api/ready; graceful SIGINT/SIGTERM close.

Phase 2 addition — index management: autoIndex: false at connection time (implicit per-boot index builds are a production anti-pattern). In development, ensureAllIndexes() (src/db/ensure-indexes.ts) runs once after connect and calls createIndexes() for every registered model. In production, the same function is executed as an explicit deployment step (Phase 12) rather than implicitly at boot.