design

Location Acquisition Manager — flow

Atlas’s UI for the Location Acquisition Manager (Expansion) persona. This is the design a Location Acquisition Manager sees when they log into Atlas Facilities. They are one of the companion personas the Facilities PM depends on (see the PM PRD §12), and they report to the Facilities PM and the VP of Facilities only.

Naming note. The persona was originally specced as Location Scout. The remit now covers sourcing and development (an accepted location becomes a Project the Location Acquisition Manager runs to handover), so the name was widened to Location Acquisition Manager. The flow slug, folder and published URL deliberately stay facilities-location-scout so existing links keep working.

Live interactive prototype: /products/atlas/flows/facilities-location-scout/ — the canonical Location Acquisition Manager flow as a single-file HTML demo.

Persona summary


Name	Location Acquisition Manager (Expansion) · prototype persona Yusuf Idris
Audience	The field owner who sources candidate sites and runs accepted ones to handover
Surface	Atlas (web, desktop-first 1440px)
Auth context	Internal employee SSO; region-scoped (South-West) — files reports, reads requirement SOPs, monitors projects, owns the lease record; no admin/config, no design or process ownership
Reports to	Facilities PM and VP of Facilities only
Access level	View: requirement SOPs. Edit: case reports, and the lease/landlord record on projects in their region (PRD §1.1)
North star	Strong candidate areas handed to the PM — surveyed areas that clear their requirement criteria, and projects that commission on time

Primary jobs to be done

Read the live estate and the expansion pipeline on one map (live / earmarked / surveyed / in-review)
Open the PM’s requirement SOPs and assess an area against their site-selection criteria
File SOP-tied case reports with photo/video evidence, as a draft or submitted to the PM
Track each report through Draft → Submitted → Reviewed
Monitor accepted locations as Projects through to handover, flagging slippage early
Keep the lease, landlord and agreement record current, and set renewal reminders
Keep map region, distance units and field notifications tuned for the job

The estate lifecycle

The three nouns are deliberately distinct, and the Location Acquisition Manager owns the first two:

Stage	Noun	What it means
Sourcing	Location	A candidate area on the map. Earmarked, surveyed, or in review with the PM. Not yet committed to.
Development	Project	The PM or VP has accepted the location (PRD FR-8). It is not a location any more, and not yet a facility: it is a construction effort with a lease, a landlord, a contractor and a stage.
Operations	Facility	Handed over. It leaves this flow and appears as a live site to the Facilities PM and the region.

Project is the entity name because at that stage what exists is the work, not an operable place — which is also why it carries a lease, a landlord, a handover date and a stage rather than health or equipment.

The project stages prepend an Approved entry state — a location the PM/VP has accepted into Projects but whose lease is not yet filed — to the PRD’s four (FR-10): Approved → Leased → Design → Construction → Handover. Approved renders grey (a neutral, not-yet-started state); the PRD’s four keep the 3+1 colour rule. The same five-stage STAGES is mirrored verbatim by the Facilities PM and VP flows so one project reads identically at every tier.

What this persona does and does not own

The PRD sets §1.1 Design ownership: N/A and Process ownership: N/A, and the Projects user story is to “monitor them through the lifecycle”. PRD FR-11 now states it outright: only the PM or VP can advance a project’s stage, and this persona’s view of stage is read-only. So the flow gives the Location Acquisition Manager no advance and no handover sign-off action. What it owns on a project is the lease and landlord record (FR-9), a renewal reminder, and reporting upward. The project details page’s .pg-actions reflect exactly that: Flag a delay and Send update, or Add lease details when the lease has not been filed. An earlier draft of this surface let the persona advance stages and request handover sign-off; that was removed as unowned authority, and FR-11 was added to the PRD so it cannot creep back.

Access is likewise narrow (PRD §1.1): View on SOPs and stage, Edit on case reports and the lease record. There is deliberately no Issues queue and no Requests surface — the data model treats Issue / Case Report as one entity, and Locations is its only surface.

Surfaces

The five sidebar surfaces are Overview, Requirements, Locations, Projects and Facilities — grouped Scouting (the first three) and Development (the last two). Settings and Notifications are topbar inner pages: they carry a .pg-back and, having no .sb-item of their own, deliberately leave the sidebar highlight where it was.

Surface	What it does
Overview	The Lagos-cluster dashboard (page heading “Cluster”). It is a single-cluster lens over the real data: KPIs (live facilities / in development / in pipeline / with the PM/VP), an interactive Leaflet map centred on Lagos, and a pipeline table — all derived in `overviewItems()` from the real `LOCATIONS` / `PROJECTS` / `FACILITIES` filtered to the Lagos cluster, so the Overview always agrees with those tabs’ Lagos rows. Map pins are colour-coded by phase (green Facility · blue In development · amber Pipeline) and a pin or row opens the real record in its own tab’s details page (`#pg-report` / `#pg-project` / `#pg-facility`). Filing a location with a Lagos address drops a distinct highlighted purple pin (`.sp-hi`) here — the flow switches to Overview on save, pans to it and pops open its address; the address is geocoded through a small built-in Lagos gazetteer (`geocodeLagos()` — no live geocoder is loaded, so an unknown area falls back near Lagos centre). The other tabs stay multi-cluster; only this dashboard is scoped.
Requirements	Read-only library of the siting standards the PM publishes, filterable by location type; the requirement details page `#pg-requirement` shows each standard’s version, site-selection criteria and the areas assessed against it.
Locations	The pre-approval pipeline: every location the scout is working, filterable Draft/Surveyed/In review/Rejected. File location opens a create dialog (name · cluster · address · target type) and adds a Draft; the cluster picker is generated from the acquisition-cluster registry the VP / PM open (seeded `Lagos` / `Ogun`), so the scout only files within clusters an exec has opened — the field notes “Clusters are opened by the VP / PM.” A Lagos address is geocoded and dropped as a highlighted pin on the Overview map (see above); a non-Lagos address is stored but not mapped, since the Overview is the Lagos lens. A row opens the location details page `#pg-report` (cluster, address, target type, requirement SOP, status, the attached case report’s notes + photo/video + the site assessment). Its footer is status-driven: a Draft offers Attach case report (requirement SOP select, case notes, a Site assessment checklist — the SOP’s 29 criteria across 7 categories, each ticked one of Yes/No/Good/Bad/Average, plus Required-deliverables and Site-visit tick-lists — and photo/video capture (`capture="environment"`) + upload) which surveys it to Surveyed; the completed assessment is stored on the case report and read back grouped-with-badges on the details page. A Surveyed offers Submit to PM/VP which moves it to In review; In review and Rejected are read-only, since approval and everything after are the PM/VP’s (built as batch 3b: the Projects post-approval stages and a Facilities terminal tab).
Projects	The post-approval phase. A location the PM/VP accepts enters as Approved (accepted, lease not yet filed), then runs `Approved → Leased → Design → Construction → Handover` on the canonical *`.tl-step-` state-machine timeline (DESIGN.md “Status timeline”). The scout’s action is Add lease — a location can hold several, one per physical layer (land, building, roof …); filing the first (the Primary) moves Approved → Leased, and the build stages after that are the PM/VP’s to advance (monitor-only here, per FR-11). KPIs for active / in construction / lease expiring / slipped (each filters the table), a `.filt-search` + a single `.filt-select` stage dropdown inside the table card head, and a `.tbl-foot` count. The project details page `#pg-project` carries details, the lease and landlord record**, a “why it slipped” note and the stage timeline.
Facilities	The commissioned terminal. A project that completes Handover becomes a live Facility and lands here, out of Projects (the clean split — a location is only ever in one tab). Read-only: filterable by cluster and searchable, each row opening the facility details page `#pg-facility` (type, cluster, requirement SOP, commissioned date, the project it was sourced from). The scout hands over and monitors; the live-facility record itself belongs to the Facilities PM / VP directory.
Leases (the location’s stack of interests, on the project details page)	PRD FR-9 + the Multiple-leases feature PRD. A location holds many leases, one per physical layer (`land` · `building` · `roof` · `airspace` · `car_park` · `grid` · `whole_site` · `other`), rendered as a `.ls-row` stack: layer badge(s), landlord, term, rent and status, with the one Primary and any Essential or Master `masterRef` leases badged, a footer of layer/active counts and total annualised rent, and superseded leases kept read-only under a “Previous agreements” divider. Each lease carries landlord, letting agent, term, structured rent (amount · period), the signed agreement, and its own renewal reminder; added/edited in the canon centred `.dlg` (layer multi-select `.lchip` chips, role, an `.tgl` Essential toggle, supersedes picker). The Primary gates the stage and headlines the Projects table (`+N` marker for extra layers); the Lease expiring KPI/chip fire on any active lease inside 180 days (`b-amber`) or 90 (`b-red`); a `b-grey` “Not recorded” badge shows where no lease is filed.
Settings	Profile, notifications (requirement published/updated, report reviewed/sent-back, weekly pipeline digest), and scouting preferences (default map region, distance units, attach-GPS-to-reports, auto-save drafts).
Notifications	`#pg-notifications`, opened from the topbar bell. `.ntf-row` entries grouped Today/Earlier, each one an event this persona actually receives: a case report reviewed by the PM, a requirement SOP republished, a project moving stage. Unread rows carry a `.ntf-dot` and clear on click; “Mark all read” clears the topbar bell dot. Stage-move copy must name one of the four FR-10 stages.

The location lifecycle

One location entity carries a single status the whole way through, and each tab owns one phase so a location is never in two places at once:

Draft (created) → Surveyed (case report attached) → In review (sent to PM/VP) → the PM decides → Approved or Rejected → Leased (scout files the lease) → Design → Construction → Handover → Facilities (commissioned).

The pre-approval phase (Locations tab) — Draft / Surveyed / In review / Rejected, with the scout’s own transitions (File location, Attach case report, Submit). The scout drives Draft → Surveyed → In review; approval is the PM/VP’s, so those states are read-only here. The post-approval phase (Projects tab) — a location enters as Approved, and the scout files the lease to move Approved → Leased; the PM/VP advance the Design → Construction → Handover build stages (monitor-only here). The terminal (Facilities tab) — a project that completes Handover commissions into a live Facility and moves out of Projects. Each phase owns its tab, so a location is only ever in one place. The PM-side approve/reject and the cross-flow live-facility record are still to come, as separate batches in another flow. Clusters are now opened upstream by the VP/PM (their New cluster action) and consumed here: this flow’s File location cluster picker is generated from the same CLUSTERS registry, seeded identically across all three flows, so a cluster the exec opens is exactly what the scout can file against — the direction runs VP/PM → scout.

Why this flow exists separately

Atlas is multi-persona. The Location Acquisition Manager’s job — sourcing sites against the PM’s standards, reporting field findings, and running accepted locations through construction — is distinct from operating the estate, which is the Facilities PM’s remit. The Location Acquisition Manager reads the requirement SOPs the PM authors and reports back to the PM and the VP of Facilities; it holds no decision or configuration authority. This flow is the dedicated default surface for anyone with the Location Acquisition Manager role.

PRD traceability

Against PRD.md v1.1 (§2 Functional Requirements). Every requirement is implemented.

PRD	Requirement	Where it lives
FR-1	Dashboard map of facilities, earmarked areas and surveyed areas	Overview · Leaflet map with status pins + legend
FR-2	Tabs with reports and requirements for new facilities	Locations and Requirements sidebar surfaces
FR-3	Status-labelled facility lifecycle	Overview Phase + Status columns; the location lifecycle above; Projects stages
FR-4	SOPs filed as Location, subdivided by facility type	Requirements · “SOP tag” column (badge per subdivision) + `SOP tag: Location · <type>` on the requirement details page
FR-5	SOPs filterable by subdivision	Requirements · `.filt-select` location-type filter
FR-6	Case notes carry text plus image/video, captured or uploaded	Locations · `capture="environment"` + upload, `.media-grid` thumbnails
FR-7	Every case report tied to an SOP	Locations · required Requirement SOP select; “Requirement SOP” column
FR-8	Locations accepted by the PM/VP move to Projects	Projects · `Accepted: · by the PM
FR-9 (+ Multiple-leases PRD)	Attach lease agreements to projects — now many per location, one per physical layer	Project details page · the Leases `.ls-row` stack + `.dlg` (layer multi-select, role, Essential, structured rent, supersedes, renewal reminder); one Primary gates the stage
FR-10	Stages are Leased, Design, Construction, Handover (with an `Approved` entry state prepended)	Projects · `STAGES`, the stage filter, and the `.tl-step-*` timeline
FR-11	Only the PM/VP advance a stage; read-only for this persona	Projects · no advance/sign-off action anywhere; the details page offers only `Flag a delay` / `Send update` / `Add lease details`
Edge cases (§2.1–2.4)	Empty states must be explicit, never look broken	Canonical `.empty-wrap` on every table (Overview, Requirements, Locations, Projects, Facilities)
Edge case (§2.3)	Uploaded-but-unsubmitted notes marked draft	Locations · a location with no report yet is `Draft`; attaching one marks it `Surveyed` (unsubmitted); the Draft/Surveyed/In review/Rejected filter separates them
Edge cases (§2.4)	No lease filed shows explicitly; renewal window flagged	`Not recorded` badge; amber chip inside 180 days, red inside 90, + a Lease expiring KPI/filter
Data entities (§3.1)	Issue/Case Report, SOP, Project, Stage, Lease	`REPORTS`, `REQS`, `PROJECTS`, `STAGES`, `PROJECTS[].leases` (a set, one per layer)

Three PRD questions were resolved into v1.1: the persona name, Locations only (no Issues queue or Requests surface for this persona), and only the PM/VP advance a project stage. Three remain open in PRD.md §4 and are not yet designed here: where Alert/Notification surfaces (the FR-9 renewal reminder currently confirms via a toast, and a Notifications page is also the outstanding fleet-wide atlas-shell-parity gap), regulatory compliance having no requirement behind it, and whether this persona keeps visibility of a project after handover given the lease outlives it.

Source

The interactive prototype lives at ./index.html. Edit that file directly when iterating; no build step. Built to Polaris/Caesar web canon (shell · .tbl tables · .pstat KPIs · .badge b-* · centered .dlg · full details pages · .settings-layout · .tl-step-* status timeline), plus a Leaflet map (CARTO light basemap, L.divIcon status pins). Lint-clean via node site/scripts/lint-canon.mjs.

No side drawers. Every rich record (area, requirement, report, project) opens as a full details page — .pg-back + a .pg-head whose .pg-title-row carries the title with the status badge inline and the actions in .pg-actions, over a two-column .rec-grid of .card blocks each headed by a .card-eyebrow. Create and edit stay in the centred .dlg (File report, Lease details). This flow originally used right-side drawers; they were removed by the fleet-wide facilities sweep when web-no-drawer landed. Do not reintroduce one.

Canon decisions worth keeping in mind when editing this flow:

Stage colours follow the 3+1 status rule (DESIGN.md: pending amber · in-progress blue · done green · failure red). The four PRD stages do not get four colours — Leased is amber, Design and Construction are blue, Handover is green, and a slipped handover adds a red badge. The stage name carries the granularity. Do not invent a 5th status colour.
The stage timeline is the canonical .tl-step-* pattern, copied from DESIGN.md’s “Status timeline (state-machine progress)” with its global token names mapped onto this flow’s local :root (--grey4>--border, --g-primary>--brand, --grey3>--grey2, --grey10>--text-3, --grey12>--text-1). Structure and the done/active/pending state set match the spec exactly.
Empty states use the canonical .empty-wrap (52px grey icon-chip + 22px glyph, title 15/600, message 13 muted) at panel level, per PATTERNS.md. All four tables hide the .tscroll and show the empty panel on a zero-result filter, so an empty result never reads as a broken one (PRD §2.2 edge case). With the current demo data only Projects can actually reach zero, via search or the stage filter; the other three are wired for real data.
Every surface follows the current “Page + table structure” hard rule (PATTERNS.md): no .pg-sub page subtitle anywhere, no .pseg used as a table filter, filters inside the table card head (.filt-search left, .filt-select right), a .tbl-foot carrying the count label and its .pager, and every filter genuinely filtering. Overview, Requirements and Locations predated this and were retrofitted; note their violations passed Layer 1, because web-page-subtitle only matches a line-start .pg-sub div and web-pseg-in-table only a .pseg inside a .tbl-card-head. Passing the lint is not evidence of compliance here — read the rule.
Site assessment checklist (attach-case-report dialog). The SOP’s evaluation matrix renders data-driven from ASSESSMENT (7 categories) + DELIVERABLES / SITE_VISIT: one canonical .filt-select per criterion (Yes/No/Good/Bad/Average) in a scrollable box, and .tgl toggles for the two tick-lists. Copy is ASCII-safe — no em/en dashes, >= 1000 sqm not ≥ 1000 m² — per canon. The row uses three small local classes (.assess-cat / .assess-row / .assess-lbl); the select needs #rf-assess .assess-sel{width:116px} at id specificity because the base .fld select{width:100%} rule would otherwise stretch it to full width and collapse the label. Responses store on report.assessment and read back grouped-with-badges on #pg-report (Yes/Good green, No/Bad red, Average amber).
Outstanding debt: the detail rows. dwRow(k,v) still emits .dw-card/.dw-row, drawer-era classes kept when the records became details pages. The canonical row is the icon key-value .td-row (.td-k + circular .td-ic + .td-v), which this file already defines and never instantiates, so .td-row is currently dead CSS. Converting it means choosing an icon per field across roughly 25 fields on four details pages, and the identical rows exist in facilities-pm and facilities-regional-manager — so it belongs in the same coordinated sweep that removed the drawers, not in a single-flow change that would diverge this flow from its siblings.