MERIDIANPLATFORM
Sign inPHASE 11
Multi-tenant logistics trackingManifest MERIDIAN-P1

One platform.
Every fleet.
Strict boundaries.

Meridian operates many independent logistics companies from a single application and a single database — each with its own branded website, public package tracking, and admin console, enforced by server-side tenant isolation. This build ships Phase 11 — reliability, tested: a three-layer suite with a production-refusal guard, an IDOR matrix proving tenant isolation, HTTP hardening, and a release gate: 156 tests, all green, zero exceptions.

Read the architecturePhase roadmap
Hardened & verified
11 / 12
Package statuses — locked
05
Tests — all green
156
Customer accounts — by design
00
MRD-0017-KXLOS → ABVIN TRANSIT·MRD-8842-XDACC → LHRPROCESSED·MRD-2290-JANBO → DARPENDING·MRD-5518-QWDXB → BOMARRIVED AT FACILITY·MRD-7731-ZMJFK → YYZDELIVERED·MRD-3306-HBSIN → SYDIN TRANSIT·MRD-9154-PCCDG → AMSPROCESSED·MRD-4477-TVGRU → EZEPENDING·
MRD-0017-KXLOS → ABVIN TRANSIT·MRD-8842-XDACC → LHRPROCESSED·MRD-2290-JANBO → DARPENDING·MRD-5518-QWDXB → BOMARRIVED AT FACILITY·MRD-7731-ZMJFK → YYZDELIVERED·MRD-3306-HBSIN → SYDIN TRANSIT·MRD-9154-PCCDG → AMSPROCESSED·MRD-4477-TVGRU → EZEPENDING·

Live foundation telemetry — GET /api/health

CHECKING

API tier

CHECKING

awaiting first probe

Database

—

no live probe yet

Realtime tier

PLANNED

Socket.IO contracts pinned · Phase 06

Uptime

—

polling every 8s

01System architecture

Four layers, one direction.

Every request travels down the stack and back — no shortcuts. The realtime tier rides alongside the API tier and reuses its auth and tenant scoping.
01

Browser

Tenant websites, public tracking, admin consoles. Collects input, renders envelopes.

Never
Touches the database, holds secrets, enforces rules.

02

UI tier — Next.js

App Router pages, server components, the typed browser API client in src/services.

Never
Calls fetch outside services/ — or imports from src/server.

03

API tier — src/server

Route → middleware → controller → service. Auth, tenancy, validation, business logic.

Never
Renders UI or trusts client-supplied tenant identifiers.

04

MongoDB — source of truth

One shared database via Mongoose ODM; tenantId on every tenant-owned document; compound indexes.

Never
Exposed to the browser — only the API tier's Mongoose layer talks to it.

Sidecar — Phase 06

Realtime tier

Socket.IO attaches alongside the HTTP server. Phase 1 already pins the event names, payload types, and room topology in src/server/realtime/events.ts.

events tracking:status.updated

rooms tenant:{id} · tracking:{id}

writes HTTP only — sockets broadcast

Request flowRequest→Route→Middleware→Controller→Service→Model→MongoDB

02Multi-tenant model

Many companies. One truth. Zero leakage.

A tenant is one logistics company. One application and one shared database serve all of them — isolation is structural, not cosmetic.
Tenant resolution — concept, wired in Phase 04RESOLVE
01

HOST

swift.nttrack.com

02

SUBDOMAIN

"swift" → tenants.slug

03

CONTEXT

{ tenantId } attached server-side

04

SCOPE

every query filter: { tenantId }

Reserved: admin.nttrack.com — the platform owner control plane. V1 supports subdomains only.

  • Every tenant-owned record carries tenantId — no exceptions.

  • tenantId is resolved server-side from host or session, never trusted from the client.

  • Frontend filtering is not security. The backend enforces isolation on every request.

Platform Admin

account

Tenants · website configuration · branding · platform settings.

Tenant Admin

account

Packages · statuses · locations · tracking operations — own tenant only.

End Customer

NO account

Visits the tenant site, enters a tracking ID, views tracking. That is all.

Locked decision: there is deliberately no Customer entity. Customers are anonymous visitors with a tracking ID — no accounts, no customer table.

03Locked decisions

The charter beneath the code.

These decisions are not revisited casually during implementation. A change requires an explicit record, updated docs, and a reason.
01STACKNext.js + React + TypeScript everywhere — no competing UI framework.
02BACKEND TIERLayered Node API tier kept separate from UI: routes, middleware, controllers, services.
03ODMMongoose is the ODM — used directly. No second ODM or ORM, ever.
04DATABASEOne shared MongoDB database — the source of truth.
05ISOLATIONtenantId on every tenant-owned record, scoped server-side.
06REALTIMESocket.IO. Broadcast-only; writes stay on the HTTP API.
07CUSTOMERSNo Customer entity. Anonymous tracking by ID.
08TENANT ADMINPackage and tracking management only — nothing else.
09PLATFORM ADMINWebsite, branding, and tenant management.
10TENANT SITESConfiguration-driven rendering — no per-tenant code forks.
11UPLOADSNo tenant file-upload system in V1.
12DOMAINSSubdomains of the platform domain only in V1.
13AUTHSecure HTTP-only cookie sessions (Phase 3). No tokens in localStorage.

Locked decision #14 — exactly five package statuses, in order

  1. 1PENDING
  2. 2PROCESSED
  3. 3IN_TRANSIT
  4. 4ARRIVED_AT_FACILITY
  5. 5DELIVERED

Pinned in code at src/types/domain.ts — database, API payloads, realtime events, and UI all derive from that single definition. No sixth status in V1.

04Implementation roadmap

Twelve phases. Foundations first.

Each phase builds strictly on the previous one. Future phases are documented, not implemented — nothing business-shaped ships before its phase.
  1. PHASE 01COMPLETEProject FoundationRepo, config, layered backend tier, DB connection architecture, realtime contracts, health probe, full documentation.
  2. PHASE 02COMPLETEBackend + DatabasePlanned tables, constraints, indexes, migrations, seed data, service-layer patterns.
  3. PHASE 03COMPLETEAuthenticationHTTP-only cookie sessions, password hashing, role guards for /admin and /platform.
  4. PHASE 04COMPLETETenant ManagementTenant CRUD, slug/subdomain host resolution, request-scoped tenant context.
  5. PHASE 05COMPLETEPackages + TrackingPackage CRUD, global tracking IDs, the five-status state machine, public tracking endpoint.
  6. PHASE 06COMPLETETenant Websites + Public TrackingHostname tenant resolution, configuration-driven sites, /track and the allowlisted public API.
  7. PHASE 07COMPLETEMaps & Realtime TrackingLeaflet/OSM location UX + one-server Socket.IO: rooms, DB-first broadcasts.
  8. PHASE 08COMPLETEPlatform Admin & Website ManagementControl plane: tenant detail tabs, website + branding editors, preview, metrics.
  9. PHASE 09COMPLETENotifications & Customer SharingCopy ID/link flows, WhatsApp share URLs, live-update indicators — no providers.
  10. PHASE 10COMPLETESecurity HardeningRate limits, security headers, CORS allowlist, CSRF checks — full audit pass.
  11. PHASE 11COMPLETETesting & QAService unit tests, API integration tests, tenant-isolation suite, E2E smoke flows.
  12. PHASE 12UP NEXTProduction DeploymentDeployment config, secrets wiring, monitoring baseline, launch checklist.

Standing rule — docs update in the same change as the code.

05Documentation

The contracts every phase obeys.

Documentation is a core deliverable, not an afterthought. Written for the next developer, for the operator learning this stack, and for the tools that build on it — always in sync with the code.
01

Architecture

System diagram, multi-tenant model, the three user layers, boundaries, and the locked decisions.

02

Frontend

App Router structure, components, the layered API client, hooks, types, and future tenant-aware areas.

03

Backend

The Express-style layered API tier: routes, middleware, controllers, services, models, realtime foundation.

04

Database

Shared MongoDB model, the six implemented collections, tenantId isolation, indexes, and tracking ID strategy.

05

API

The /api/v1 groups, the implemented auth endpoints, envelopes, and the error code registry.

06

Authentication

Sessions, cookies, Argon2id, enumeration defenses, role and tenant authorization, CSRF/CORS posture.

07

Tenant Management

Atomic provisioning, slug rules, lifecycle matrix, list querying, password reset, and admin console.

08

Package Management

Tracking IDs, the five-status workflows, status/location history, atomic transactions, isolation, and console.

09

Platform Admin

Control-plane permissions, tenant list, detail tabs, password reset, and server-authorized tenant dashboard access.

10

Website Configuration

The WebsiteConfig model, branding, sections, visibility and ordering, URL images, SEO, defaults, preview.

11

Tenant Websites

Hostname resolution, configuration-driven rendering, branding, sections, SEO, status behavior, local dev.

12

Public Tracking

The allowlisted tracking endpoint, safe errors, rate limiting, timelines, and integration boundaries.

13

Maps

Leaflet + OSM ecosystem, geocoding abstraction, admin location picker, customer map, licensing duties.

14

Realtime

One HTTP server hosting Socket.IO, room authorization, DB-first events, reconnection, lifecycle.

15

Notifications

V1 realtime-only notifications, connection feedback, and the documented future provider architecture.

16

Customer Sharing

Tracking link generation, copy flows, WhatsApp share URL, clipboard resilience, and privacy bounds.

17

Deployment

VPS, PM2, Nginx, Cloudflare, environment values, build flow, Git releases, rollback, onboarding.

18

Security

Server-side isolation, authN/Z, session security, validation, headers, safe public payloads, socket authorization.

19

Environment

Every environment variable, public vs secret, local vs production principles.

20

Backup & Restore

Atlas backups, mongodump/mongorestore, retention, and the mandatory restore drill.

21

Troubleshooting

WebSocket, host resolution, cookies, database, deploy, SSL — symptom to fix maps.

22

Production Checklist

Pre-flight infrastructure list, the 22-step live smoke test, ops cadence.

23

Testing

Layered suite (unit/integration/e2e), production-safety guard, coverage matrix, release gate.

24

Development

Prerequisites, setup, quality gates, seeding, manual verification, troubleshooting, workflow.

25

Implementation Roadmap

Phases 1–12 with scope, dependencies, and the standing rules for every phase.

Sources of truth live in /docs — rendered here for reading.