Audience: Everyone — product owners, QA, frontend and backend developers Scope: The geo reference data module, its two public reads, and why every other module resolves districts through it

Geo Module - Overview

1. What the module is

Geo is Nepal's administrative reference data: 7 provinces and 77 districts, served read-only to anyone. The address form's province and district pickers come from here — the module exists so the same reference data is not re-copied into every surface that needs a location picker.

It is public by design: this is government-published data with nothing to protect, and the address form needs it before a customer has signed in. It is throttled for load, not for secrecy.

2. What it provides

Both are unpaginated by default; pass pagination=true for pages.

3. The two things every consumer must know

1. Key your logic on code, never on name. Provinces have been renamed before (Province No. 1 → Koshi in 2023, Province No. 2 → Madhesh in 2022) and will be again. code is stable; name is a label.
2. Four district codes are the ones third-party datasets merge wrongly, and each pair sits in a different province — do not merge them:

4. The lookup service

GeoLookupService is the single place a district uuid becomes a foreign key. Shipping, the address book and every future module resolve a district through it — never by reading the geo tables directly. That is what keeps "this uuid names a district" true in exactly one code path.

5. Seeding

The data is seeded by an idempotent script, packages/db/src/seed/seed-geo.ts:

• Runs automatically as part of the normal db:seed.
• Runnable alone: pnpm --filter @happy-shop/db db:seed:geo.
• Idempotent — safe to re-run.

Page guide