Backend architecture, data model, services, cache, and operational behavior for the Shipping module.

Shipping - Backend Documentation

1. Documentation Evidence

Area	Files Inspected	Verified Details
Module wiring	`apps/api/src/modules/shipping/` module files	Admin + customer leaves, mobile registration
Controllers	`admin/shipping-admin.controller.ts`, `customer/shipping-quote-customer.controller.ts`	Routes, permissions, rate limits
Services	`shipping-admin.service.ts`, `shipping-admin-bulk.service.ts`, `shipping-quote-customer.service.ts`, `shipping-serviceability.service.ts`	Upsert, bulk transaction, availability flags
Schema	`packages/db/src/schema/shipping/shipping-rate.ts`	`district_id` unique, fee bigint
Cache	`cache-invalidation.tags.ts`	`shipping` domain

2. Backend Scope and Boundaries

Owns

The flat per-district delivery fee (shipping_rate).
Admin coverage, upsert, delete and bulk pricing.
The customer quote and the batched ShippingServiceabilityService.

Does Not Own

The address table. Shipping takes a districtId and never reads customer_address — that is a module boundary, not an implementation detail.
Order snapshots. An order must snapshot the quoted fee; repricing a district never changes what an existing order was charged (see address/backend §2).

Source of Truth

Concern	Source of Truth	Notes
Rate	`shipping_rate.district_id` unique row
Serviceability	`configured && active`	Computed; cached behind one key
Fee truth for orders	Order snapshot	Never the live rate

3. Module Composition

Module	Type	Path	Controllers	Providers	Exports	Responsibility
`ShippingAdminModule`	Leaf	`admin/`	`ShippingAdminController`	Admin + bulk services	—	Coverage/upsert/delete/bulk
`ShippingQuoteCustomerModule`	Leaf	`customer/`	`ShippingQuoteCustomerController`	Quote + serviceability	Serviceability	Quote
Mobile composition	—	`mobile.module.ts`	—	—	—	Quote mounted under `/api/mobile/shipping`

4. File and Directory Map

apps/api/src/modules/shipping/
  admin/
    shipping-admin.controller.ts
    shipping-admin.service.ts
    shipping-admin-bulk.service.ts
    dto/
  customer/
    shipping-quote-customer.controller.ts
    shipping-quote-customer.service.ts
    shipping-serviceability.service.ts   # batched, one cache key
    dto/
packages/db/src/schema/shipping/
  shipping-rate.ts

Key files:

File	Purpose	Key Exports	Notes
`admin/shipping-admin-bulk.service.ts`	Bulk pricing	`ShippingAdminBulkService`	One transaction; skipped-district report
`customer/shipping-serviceability.service.ts`	Availability for many districts	`ShippingServiceabilityService`	Batched, one cache key

5. Data Model

5.1 Schema Source

packages/db/src/schema/shipping/shipping-rate.ts

5.2 Tables

`shipping_rate`

Column	Type	Nullable	Default	Index/Constraint	Relation	Notes
`id`	serial	No	—	PK	—	Internal
`public_id`	uuid v7	No	generated	UNIQUE	—	Exposed id
`district_id`	integer	No	—	UNIQUE	`district.id`	One rate per district — this is what makes `PUT` an upsert
`fee`	bigint	No	—	CHECK `>= 0`	—	Minor units; `0` = free
`is_active`	boolean	No	—	—	—	Pause keeps the fee
`created_at` / `updated_at`	timestamptz	No	now()	—	—

There is deliberately no currency column — the system is single-currency (NPR), and a per-district currency would be dead weight.

6. Services and Responsibilities

6.1 `ShippingAdminService`

Method	Called By	Reads	Writes	Side Effects	Errors
`listDistricts()`	`GET /districts`	district + rate (left join)	—	—	—
`getDistrictRate()`	`GET /:districtId/rate`	district + rate	—	—	`SHIPPING_DISTRICT_NOT_FOUND`
`upsertRate()`	`PUT`	district	`shipping_rate`	activity, cache	`SHIPPING_DISTRICT_NOT_FOUND`, `SHIPPING_FEE_NEGATIVE`
`deleteRate()`	`DELETE`	rate	rate row removed	activity, cache	`SHIPPING_RATE_NOT_FOUND`

6.2 `ShippingAdminBulkService`

Method	Called By	Reads	Writes	Side Effects	Errors
`bulkUpsertRates()`	`POST /rates/bulk`	districts by scope union	many rate rows, one transaction	activity, cache	`SHIPPING_BULK_SCOPE_EMPTY`, `SHIPPING_BULK_NO_CHANGE_REQUESTED`, `SHIPPING_BULK_LIMIT_EXCEEDED`, district/province not-found

Bulk semantics: scopes union and de-duplicate; a status-only bulk is a plain UPDATE (never an upsert) so it cannot write a stale fee over a concurrent price change; districts without a fee under a status-only call are skipped and named in the report.

6.3 `ShippingQuoteCustomerService` / `ShippingServiceabilityService`

Quote resolves one district and answers { fee, serviceable }. Serviceability is batched for many districts (the address book's list reads) and sits behind one cache key in the shipping cache domain — a single admin edit invalidates all of it, so no address list can serve a stale availability.

Domain	Revalidation tags	Redis patterns
`shipping`	`shipping:*` tags	`shipping:*`

Every admin write (upsert, delete, bulk) invalidates the domain after commit; the quote and the address book's serviceability read sit behind the same key, so one edit refreshes every surface.

9. Jobs and Workers

None — shipping is synchronous. No queue, no outbox involvement.

10. Security and Authorization

Admin: JwtAuthGuard + RoleGuard; permissions Shipping_READ / Shipping_UPDATE / Shipping_DELETE.
Permissions come from one list: packages/db/src/authorization/permission-catalog.ts. The API's PermissionCode union and the seed's role grants both derive from it, and permissions-catalog.spec.ts fails the build if they diverge. Adding a module means adding it there, then running permissions:sync and db:seed — never a manual grant. The seed grants every module's permissions to admin except System_*; superadmin bypasses the check.
Customer quote: JwtAuthGuard (not @Public()) — quoting is a signed-in step, and the account-keyed throttle is only meaningful for an authenticated caller.
Rate limits: ADMIN_READ 30/min, ADMIN_WRITE 10/min, ADMIN_BULK_WRITE 5/min (one request can reprice all 77 districts), CUSTOMER_READ 60/min keyed on the account.

Shipping Backend Documentation