# service-areas — nurse coverage

> Client seam `client/src/services/serviceAreas/` · `USE_SERVICE_AREAS_MOCK = false` (**real**) · 3 server ops
> Last verified: 2026-07-30 against commit `d3ec723` and swagger.v1.json (2026-07-29).

Where a nurse will travel. Three endpoints, one rule that everything else depends on.

## Endpoints

| Method | Path | Verdict |
| --- | --- | --- |
| GET | `/api/v1/nurse_service_areas/list` | wired · paginated |
| POST | `/api/v1/nurse_service_areas/add` | wired |
| DELETE | `/api/v1/nurse_service_areas/remove/{id}` | wired |

All `[Authorize]`. No phantoms. The domain maps 1:1. There is no update — coverage is add/remove.

## `districtId = null` means whole-city

A service area is `(cityId, districtId?)`. **`districtId = null` is the affirmative claim "I cover this
entire city"** — not missing data, not "no district".

The consequences reach three other domains:

- **Search** must match a whole-city area against a district-filtered query, in both directions. A query
  that drops nulls silently hides every whole-city nurse. See [search.md](search.md).
- **`is_searchable`** requires at least one area covering the queried city — coverage is one of its four
  conditions. See [search.md](search.md).
- **Geography** owns the ids and the same null convention. See [geography.md](geography.md).

The client models this as a **single control**: the coverage editor offers "whole city" as a first-class
choice alongside individual districts, so a nurse can never accidentally express it as an empty district
list. Do not reintroduce a two-step "city, then optionally districts" flow — an empty selection is
ambiguous in a way `null` is not.

## Shape rules the JSON does not express

- **A duplicate area is a `409`.** Adding `(city, null)` when district rows for that city already exist —
  or the reverse — is a conflict the server resolves; the client surfaces it rather than pre-checking.
- **Removing the last area for a city removes the nurse from search in that city** in the same
  transaction, via `ISearchIndexMaintainer`. There is no lag and no reconciliation job.
- Coverage is independent of `isAcceptingBookings`: a nurse can keep coverage while pausing bookings, and
  both are conditions of `is_searchable`.
- `list` is paginated even though the practical row count is small — the platform paginates every
  unbounded list without exception.

## Enums

None. Both fields are geography ids; `districtId` is nullable and the null is meaningful.

## Open REQs

None. REQ-008/REQ-009 concern addresses, not coverage — see [addresses.md](addresses.md).