Audience: Product owners, QA, frontend and backend developers Scope: A customer's own delivery addresses, default handling, and the rule orders must follow

Address Module - Overview

1. What the module is

The customer address book: a customer's own delivery addresses, with at most one default and a soft-delete/restore lifecycle. Seven routes, all scoped to the authenticated customer — there is no admin surface over this table, deliberately, because it holds names, phone numbers and GPS coordinates.

2. The rules that matter

1. Orders must SNAPSHOT the delivery address — never foreign-key to customer_address. The FK from customers is ON DELETE CASCADE, so erasing a customer erases their addresses (they are PII that must not outlive their owner). An order that referenced 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 onto the order at checkout.
2. The first address becomes the default automatically. isDefault only matters from the second address onward.
3. A customer with zero active addresses has no default. That is a legal state — never assume a default always exists.
4. Restoring an archived address does NOT restore its old default flag. It becomes the default only if the customer has no other active addresses.
5. municipality.id is null on every address — the reference table ships empty by design. municipality.name is free text the customer types; render the name, never wait for an id.
6. Serviceability is computed on every read from the live shipping configuration. It is never stored, so an admin editing a district immediately changes what every address reports.

3. The lifecycle

• Archiving the default promotes the newest remaining active address.
• PATCH, DELETE and PUT /default on an archived address return 409 — restore first.
• The active set is capped at 20; archived addresses do not count.

4. The phone rule

recipientPhone accepts a local number — 9812345678 is normalized to +9779812345678 on the way in, and responses always return E.164. Do not pre-format it client-side.

Page guide