Add company service area overlay to Dispatch address search

Objective

• Give operational teams clear visibility into whether a searched address falls inside company service coverage — without comparing Settings maps to Google Maps or guessing which inspectors to select first.
• Add a read-only, address-first way to view all company service areas against a property pin.
• Reduce boundary confusion (e.g. subdivisions split by hand-drawn polygons) when judging in vs out of area.

Background

• Client care, growth, and field teams need to know if an address is in coverage, but Settings → Service Areas requires settings-areas edit access and is built for polygon authoring, not quick lookups.
• Teams currently compare the settings map on one screen with Google Maps on another and manually judge street-level boundaries.
• Tools → Dispatch already supports address search and drops a pin, but service-area polygons shown today are only for selected inspectors after running dispatch context — not the full company coverage set.
• Staff must pick inspectors who might serve the area before they can see relevant boundaries; that is the wrong workflow for a simple “is this address in our service area?” question.
• Recording walkthrough (product): Issue Overview Video — proposes a toggle under the Dispatch address search bar (e.g. “Display service areas”) to overlay all service areas while viewing a property pin. Written transcript: Issue Overview Transcript.
• Backend support exists: GET /service-area/find-containing?lat=&lng= returns containing areas for a point; company areas are stored as polygons in servicearea (area coordinate rings).

Product Decisions

Locked

1. Primary user outcome — Search an address, see a map pin, and optionally overlay service boundaries to judge in vs out of coverage.
2. Company-wide view — When service areas are displayed, show entire company coverage (all configured service areas), not only areas tied to currently selected inspectors.
3. Read-only — No polygon editing in this flow; visibility/lookup only.
4. Preferred surface (from recording) — Extend Dispatch address mode with a “Display service areas” (or equivalent) control under the address search — not only a separate Settings screen.

Open (Remaining product clarifying decisions)

1. Dispatch-only vs additional surface — Is Dispatch enhancement sufficient for v1, or is a separate Tools page still required for users without calendar permission (client care)?
2. Answer: Dispatch is the only surface for v1
3. Permission model — Should viewing company service areas require only calendar, a new lighter permission, or be available more broadly than Dispatch today?
4. Answer: Only the existing permision required to currently view Dispatch
5. Layer content — Show all areas at once, or toggles per area / main vs expanded service areas separately?
6. Answer: All service areas combined as one
7. In-area signal — Map overlay only, or also explicit copy (e.g. “Inside {area name}” / “Outside all service areas”) using find-containing?
8. Answer: Map overlay only
9. Inspector selection coupling — When “display service areas” is on, should per-inspector area shading (today’s behavior) hide, dim, or layer with company-wide boundaries?
10. Answer: layer on top of company wide service area
11. Relation to ATT-1926 — If ZIP-based area authoring ships later, should this viewer consume the same polygon source with no UX change?
12. Answer: regardless of how the service area is created this viewer should see the entire company service area

Scope

Frontend — Dispatch (primary surface from recording)

• attik-frontend/src/app/tools/dispatch/page.tsx — gated by calendar permission via loginCheck.
• attik-frontend/src/app/tools/dispatch/AddressSearchForm.tsx — address search; inspector dropdown uses checkPointWithinServiceAreas against selected inspectors’ areas only.
• attik-frontend/src/app/tools/dispatch/MapItems.tsx — renders combineServiceAreaBoundries(data.inspector.serviceAreas) per inspector after dispatch data loads — not all company areas.
• attik-frontend/src/app/tools/dispatch/DispatchMap.tsx — map host for pin + overlays.
• attik-frontend/src/util/functions/mapbox/checkPointWithinServiceAreas.ts and combineServiceAreaBoundries.ts — polygon point-in-polygon helpers to reuse.

Frontend — Settings (current full map, edit-only)

• attik-frontend/src/app/tools/settings/service-areas/ — ServiceAreaMap.tsx with Mapbox DrawControl for authoring; requires settings-areas.

Backend

• attik-backend/src/routes/serviceArea.ts — list areas and /find-containing for lat/lng lookup.
• attik-backend/src/models/serviceAreaSchema.ts — name, area, expanded, expandedFee, _companyId.

Out of scope (unless product expands)

• Redefining how service areas are authored (see ATT-1926 ZIP-based configuration).
• Editing polygons from the new visibility flow.
• Replacing Dispatch routing, slot scheduling, or inspector selection behavior beyond what’s needed to show company-wide boundaries.

References

• Issue Overview Video
• Issue Overview Transcript
• Dispatch entry: attik-frontend/src/app/tools/dispatch/page.tsx
• attik-backend/src/routes/serviceArea.ts
• attik-frontend/src/app/tools/settings/service-areas/page.tsx