Address - Backend Documentation

1. Documentation Evidence

2. Backend Scope and Boundaries

Owns

• The customer address book (seven customer routes; no admin surface — the table holds names, phones and GPS coordinates, and a cross-customer read path should not exist until something concretely needs one).
• The default-address invariant and the archive/restore lifecycle.
• Phone normalization for recipient_phone via the shared phone utility.

Does Not Own

• Order addresses — and this is the single most important sentence in this module's docs: orders must SNAPSHOT the delivery address, never foreign-key to customer_address. fk_customer_address_customer_id is ON DELETE CASCADE (packages/db/src/schema/address/customer-address.ts). When a customer is genuinely erased, every address they own is erased with them — including archived ones. That is correct privacy behaviour (addresses are PII that must not outlive their owner) and the accepted reason this deviates from the usual no-cascade-onto-soft-deletable rule. An order referencing an address row would lose its shipping destination at that moment; an order's address must stay truthful for as long as the order does. Copy the resolved fields — recipient name, phone, province, district, municipality name, ward, street, landmark, postal code, coordinates, delivery instructions — onto the order at checkout time.
• The same applies to the shipping fee: the order must snapshot the quoted fee. An admin repricing a district must never change what an existing order was charged.
• Serviceability — computed on read from the live shipping configuration, never stored.

Source of Truth

3. Module Composition

4. File and Directory Map

apps/api/src/modules/address/
  customer/
    address-customer.controller.ts
    address-customer.service.ts
    dto/    create-address.dto.ts  update-address.dto.ts
            list-addresses.query.dto.ts  address-response.dto.ts
packages/db/src/schema/address/
  customer-address.ts
apps/api/src/utils/phone/phone.util.ts      # shared, NP default region

Key files:

5. Data Model

5.1 Schema Source

packages/db/src/schema/address/customer-address.ts

5.2 Tables

customer_address

Key CHECKs: chk_customer_address_ward_in_range, coordinate pair/range checks, recipient_phone E.164 normalization check. Active cap (20) is service-enforced; archived rows do not count.

5.3 Relationship Diagram

6. Services and Responsibilities

6.1 AddressCustomerService

Set-default concurrency: a per-customer pg_advisory_xact_lock serializes concurrent calls so two set-defaults cannot race past the partial unique index; the previous default is cleared in the same transaction. restore is idempotency-guarded (customer-address-restore); create too (customer-address-create).

Phone: recipient_phone goes through normalizeToE164 with NP as the default region — local 9812345678 becomes +9779812345678. Both customers.phone and customer_address.recipient_phone must produce byte-identical E.164, or the address CHECK accepts one and rejects the other for the same input.

7. Runtime Flows

7.1 Set default

7.2 Create with serviceability

8. Cache

No address rows are cached — they are per-customer PII and cheap to read. Serviceability rides the shipping cache domain (batched behind one key), so an admin editing a district refreshes every address list on the next read.

9. Jobs and Workers

None. The address book is synchronous.

10. Security and Authorization

• Every route is scoped to the authenticated customer inside the service's WHERE clauses — there is no admin surface over this table, deliberately.
• CUSTOMER_READ 60/min and CUSTOMER_WRITE 20/min, both keyed on the account (keyStrategy: "user"), so customers behind one carrier NAT do not exhaust each other's quota.
• Cross-customer reads return 404 CUSTOMER_ADDRESS_NOT_FOUND — never 403, which would be an existence oracle.
• Create and restore carry Idempotency-Key requirements (scopes customer-address-create, customer-address-restore).

11. Operational Notes

• The municipality reference ships empty — do not treat municipality.id: null as a bug; it is the designed state, and municipality.name is the truth.
• Restoring an archived address never restores its old default flag — the flag is recomputed, and the address becomes default only when the customer has no other active addresses.
• A customer with zero active addresses has no default — legal, not an error.