PRD multiple leases

RECHAJ — MocX Smart Technologies Inc.

Facilities — Multiple Leases per Project

Product Requirements Document — Engineering (feature)


Status	v1.1 — all open questions resolved (§10 is now decisions, not questions). A feature PRD that extends the Location Acquisition Manager’s single-lease record (today’s FR-9) from one lease per location to many — one per physical layer of the site (land, building, roof, airspace, …). It does not re-spec the persona; it adds the multi-lease capability on top of the shipped flow.
Date	October 2026
Prepared by	Product Team (Facilities)
Owners	Facilities Product Manager (TBD) · Office of the CPO
Scope	Atlas (web) — the Location Acquisition Manager persona (the “site acquisition specialist”; slug `facilities-location-scout`), Projects surface and the lease record only.
Source of truth	This PRD for the multi-lease requirements; the persona PRD for the role, and the interactive flow + design.md for everything else.
Classification	CONFIDENTIAL

Naming. The user’s “site acquisition specialist” is this product’s Location Acquisition Manager — first specced as Location Scout, later Estate Manager. The flow keeps the stable slug facilities-location-scout. This PRD uses Location Acquisition Manager throughout.

1. Summary

Today a Project carries exactly one lease (persona PRD §4, FR-9): project.lease is a single record — landlord, letting agent, start, expiry, rent, signed agreement, renewal reminder — or null until the Location Acquisition Manager files it. Filing that lease is what moves a Project from Approved to Leased.

That one-to-one model does not match how Rechaj actually acquires sites. One location is frequently held under more than one agreement:

Stacked interests on one location (the core case). The same site is held under separate leases for different physical layers — the land it sits on, the building on that land, and the roof (routinely leased on its own for rooftop solar PV, or for a mast / signage). Each layer can be a different landlord, term and rent, yet together they describe one location. A Charge-Swap Station, for example, may hold a ground lease for the plot, a building lease for the structure, and a roof lease for the solar array that powers it — three leases, one site.
Multi-parcel sites. A facility assembled from adjacent plots held by different landlords — the main forecourt from one owner, the generator yard or extra parking from another.
Lease succession. A short bridging lease while a long-term lease is negotiated, or a renewal that supersedes an expiring agreement — history kept, not overwritten.

This feature makes Lease a one-to-many child of Project: a Project (one location) can hold any number of leases, each naming the physical layer it covers (land, building, roof, airspace, …), and exactly one flagged Primary. The Primary keeps every behaviour FR-9 ships today (it gates the stage and headlines the Projects table); the other layer-leases are tracked alongside it, each with its own term, rent, document and renewal reminder, so no renewal on any layer of any site is ever missed — the roof-solar lease is as visible as the ground lease.

2. Goals & non-goals

Goals

Let the Location Acquisition Manager attach multiple leases to one location, each naming the physical layer it covers (land, building, roof, airspace, …) and each a full lease record.
Make a location’s leases read as one stack of interests — at a glance, what layers are leased, from whom, until when.
Keep one clear headline per Project (the Primary lease) so the Projects table and KPIs stay legible.
Ensure every lease — any layer, primary or ancillary — carries its own renewal reminder and is caught by the “lease expiring” lens.
Preserve lease history when a lease is renewed or replaced (supersede, never overwrite).
Show the total rent commitment for a location when it spans several leases.

Non-goals (this PRD)

Rent payment / invoicing or a financial ledger — deferred fleet-wide, as in the persona PRD. (This PRD does structure the rent figure so a total is exact — FR-9.11 — but files no payments.)
Lease document storage backend, clause extraction, or e-signature.
A full lease-to-Project many-to-many. A master agreement spanning sites is handled by a shared reference, not a shared record (FR-9.14, §10 D1).
Changing who may edit leases, or the stage model itself (FR-10 / FR-11 unchanged).

3. Persona & entry points

Unchanged persona (Location Acquisition Manager; see persona PRD §2). New entry points, all on the Projects surface:

From a Project’s detail page, the “Lease & landlord” card becomes a Leases card with an Add lease action and one row per lease.
The existing Lease details dialog (#dlg-lease, FR-9) is reused to add or edit any lease, with new fields for its role and what it covers (§5.2).
Adding the first lease and marking it Primary is what moves Approved → Leased (the stage gate is unchanged; it now keys off the Primary rather than “the lease”).

4. Functional requirements

Numbered to extend FR-9 of the persona PRD. FR-9 remains (“attach lease agreements and other information to projects”); these refine it for the many-lease case.

FR-9.1 — Many leases per Project. A Project may hold zero or more leases. Each lease is a full record (the FR-9 fields) plus the new attributes in §6. There is no fixed cap.
FR-9.2 — Exactly one Primary. When a Project has at least one lease, exactly one is flagged Primary. The first lease filed becomes Primary by default; the Location Acquisition Manager can re-assign Primary to another lease, and the system guarantees the invariant (re-assigning clears the previous Primary).
FR-9.3 — The Primary drives the headline. The Projects table’s Lease expires column and the Project detail header show the Primary lease’s expiry (today’s behaviour, now explicitly the Primary). A Project with leases but no Primary is an invalid state the UI prevents (FR-9.2).
FR-9.4 — The stage gate keys off the Primary. Approved → Leased requires a Primary lease on the Project (replacing “a lease filed”). Ancillary leases do not affect the build stage — there is no ancillary hard-gate (§10 D5). A lease may be flagged essential (e.g. a grid-tie easement, or the roof-solar lease a station depends on); an expired essential lease never blocks a build stage but raises a High-priority renewal alert (FR-9.13) and a prominent flag on the location, so a critical layer cannot lapse unnoticed.
FR-9.5 — Per-lease renewal reminders, rolled up. Each lease carries its own renewal-reminder date and expiry. The “Lease expiring” KPI and the Projects “Lease expiring” filter count a Project when any of its active leases is inside the renewal window (≤ 180 days) or already expired — not only the Primary. The attention surfaces name which lease.
FR-9.6 — Lease roles. Each lease has a role: Primary, Ancillary, Renewal, or Bridging (§6). Role is descriptive except Primary, which is the single gating/headline lease (FR-9.2). Role is orthogonal to the layer (FR-9.9): by default the core-occupancy layer (the building, or the land where there is no separate building lease) is Primary, and roof / airspace / signage leases are Ancillary — but the Location Acquisition Manager can set Primary to any layer.
FR-9.7 — Supersede, don’t overwrite. Renewing or replacing a lease creates a new lease that supersedes the old one; the superseded lease is retained as history (status Superseded), shown but visibly de-emphasised, and is excluded from active roll-ups (rent total, expiry lens). If the superseded lease was Primary, the superseding lease inherits Primary.
FR-9.8 — Total rent. The Project detail shows the sum of annualised rent across the Project’s active leases (Primary + Ancillary + current Renewal; Superseded excluded), alongside the per-lease figures. The sum is exact because rent is structured (FR-9.11), and each lease’s amount is annualised by its period before summing.
FR-9.9 — Layers a lease covers (required). Each lease names one or more physical layers it applies to, from a fixed set: Land (ground) · Building (structure) · Roof · Airspace / signage · Car park · Grid / sub-surface · Whole site · Other (free-text qualifier). At least one layer is required. Most leases name a single layer; a lease whose one agreement genuinely covers two (land and building together, §10 D6) names both. This is what lets one location carry a land lease, a building lease and a roof lease and still read clearly.
FR-9.10 — The location reads as a stack, each layer claimed once. A Project’s leases are presented together as the location’s stack of interests — showing layer(s), landlord, term and status — so it is obvious which layers are leased, from whom, and until when. No two active leases may claim the same layer; attempting it is rejected, unless one Supersedes the other (a renewal, FR-9.7). A combined-layer lease (e.g. {land, building}) claims both of those layers.
FR-9.11 — Rent is a structured figure (§10 D4). Each lease stores amount (number), currency (default NGN) and period (year | quarter | month). The UI displays it formatted (e.g. ₦8,400,000 / yr) and annualises it for the total (FR-9.8). The free-text rent string is replaced; migration parses existing strings best-effort and flags any it cannot (§6).
FR-9.12 — Leases are evergreen; they outlive the build (§10 D2). A lease is not discarded when its Project reaches Handover. The Project persists in a terminal Operating state and keeps its leases; the Location Acquisition Manager remains the lease owner — renewing, superseding and holding the landlord relationship — after handover, which is exactly the role’s post-development remit (persona PRD §2). The operating Facilities PM gains read access to the location’s leases (§8).
FR-9.13 — Renewal reminders fire on the Notifications page and by email (§10 D3). Each lease’s reminder (FR-9.5) surfaces on the Atlas Notifications page (the canonical shell surface every flow carries) and by email, routed to the lease’s owner (the Location Acquisition Manager). If a reminder for an essential lease (FR-9.4) — or any lease inside 30 days of expiry — goes unactioned, it escalates to the Facilities PM. This is the home the persona PRD’s reminder (its open question 4) was missing.
FR-9.14 — Master agreement across locations (§10 D1). A single agreement covering more than one site is not one shared record; it is a lease recorded on each Project, the leases sharing a masterRef (the master-agreement id) and each carrying its apportioned rent. The UI shows a “Part of master agreement masterRef” note and links the sibling leases. This captures the reality without a lease-to-Project many-to-many.

5. Screen specifications

5.1 Projects list (unchanged shape, roll-up redefined)

Lease expires column shows the Primary lease’s expiry with the existing chip states (in-window amber, expired red, “Not recorded” grey when no Primary). When the Project has more than one lease, the cell carries a small +N marker (e.g. 30 Jun 2031 · +2) so a multi-lease Project is visible at a glance.
“Lease expiring” KPI / filter now count by any active lease (FR-9.5), not only the Primary.

5.2 Lease details dialog (`#dlg-lease`, reused + extended)

Today’s fields stay: Landlord, Letting agent, Lease start, Lease expires, Renewal reminder, Signed agreement (upload). Rent becomes structured, and these are added:

Layers — multi-select: Land (ground) · Building (structure) · Roof · Airspace / signage · Car park · Grid / sub-surface · Whole site · Other, with a free-text qualifier for Other (FR-9.9). At least one required; most leases pick one.
Role — select: Primary · Ancillary · Renewal · Bridging. A Make this the Primary lease control (respects FR-9.2; implicit when it is the only lease).
Rent — amount (number) + currency (default ₦ NGN) + period (year / quarter / month) (FR-9.11), replacing the free-text rent string.
Essential — a toggle (FR-9.4): mark a layer the site depends on, so its lapse escalates rather than passing quietly.
Supersedes — (only when Role = Renewal) a picker of the Project’s existing active leases that share a layer with this one; choosing one marks it Superseded on save (FR-9.7).
Master agreement — an optional masterRef + apportioned-rent note when this lease is one site under a cross-location agreement (FR-9.14).

The dialog’s title/subtext reflect add-vs-edit and the Project it belongs to (as today via #lf-title / #lf-sub).

5.3 Project detail — Leases card (replaces “Lease & landlord”)

Reads as the location’s stack of interests. A list, one row per lease, led by its Layer badge(s) (Land / Building / Roof / Airspace / Car park / Grid / Whole site / Other) with the Primary highlighted and an Essential marker where set, then landlord / agent, term (start → expires) with the expiry chip, rent, and status (Active / Pending / Expired / Superseded). A lease that is part of a master agreement shows a “master masterRef” link.
Add lease opens #dlg-lease; a row click opens it to edit.
A footer total: layers leased, active-lease count and total annualised rent (FR-9.8).
Superseded leases render de-emphasised under a “Previous agreements” divider, read-only in place (history, FR-9.7).
After handover the card stays live (FR-9.12): the Operating location keeps its stack, the Location Acquisition Manager still renews from here, and the Facilities PM sees it read-only.

6. Data model

Change: Project.lease (object | null) → Project.leases (array). Each element:

Field	Notes
`id`	Lease id.
`role`	`primary` \| `ancillary` \| `renewal` \| `bridging`. Exactly one `primary` per Project when `leases` is non-empty (FR-9.2). Orthogonal to `layers`.
`layers`	Array of `land` \| `building` \| `roof` \| `airspace` \| `car_park` \| `grid` \| `whole_site` \| `other` (FR-9.9). Required, ≥ 1. The physical layer(s) this lease covers.
`layerNote`	Free-text qualifier when `layers` includes `other`.
`essential`	Boolean (FR-9.4). A layer the site depends on; its lapse escalates (FR-9.13) but never blocks a build stage.
`landlord`, `agent`	As FR-9.
`start`, `expires`, `expiresISO`	As FR-9; `expiresISO` drives the renewal lens.
`rentAmount`, `rentCurrency`, `rentPeriod`	Structured rent (FR-9.11): number · `NGN` (default) · `year`\|`quarter`\|`month`. Replaces the old free-text `rent` string.
`doc`	Signed agreement (document reference).
`reminder`	Per-lease renewal-reminder date (FR-9.5), delivered per FR-9.13.
`status`	`active` \| `pending` \| `expired` \| `superseded` (derived where possible; `superseded` set explicitly on renewal).
`supersedes`	Lease id this one replaces, or null (FR-9.7).
`masterRef`	Master-agreement id when this lease is one site under a cross-location agreement (FR-9.14), else null.

Project lifecycle note (FR-9.12): the stage set gains a terminal operating state after handover; a Project in operating keeps its leases, and leases are never deleted on handover.

Derived, not stored: the Project’s headline expiry (= Primary’s expiresISO), the “expiring” flag (= any active lease in-window/expired), each lease’s annualised rent (from rentAmount × period) and the Project total (= Σ active annualised rent). Computing them keeps the Projects table, the KPI and the detail card in agreement — the same “derive, don’t store” rule the executive tiers follow.

Migration. Existing project.lease objects map to leases: [{ …that record, role:'primary', layers:['whole_site'], essential:true, status:'active', supersedes:null, masterRef:null }], with the old rent string parsed into rentAmount/rentCurrency/rentPeriod (best-effort; any unparseable string is retained verbatim and flagged for review). lease:null maps to leases: []. No data is lost and today’s single-lease Projects behave identically — one whole-site Primary lease — until a second layer is added.

7. Edge cases

No leases on a Project → “No leases recorded” empty state (never a blank field), and the Project cannot advance past Approved (FR-9.4).
One lease → behaves exactly as today; a single whole-site lease, implicitly Primary, no +N marker, no stack divider.
Partial coverage → a location may have some layers leased and others not yet (land + building secured, the roof-solar lease still in negotiation). The stack shows only the layers that exist; no layer beyond the Primary is mandatory, and a missing layer is not an error.
Primary re-assignment always leaves exactly one Primary (FR-9.2), and can move between layers (e.g. a ground lease is Primary until a building lease is signed).
Expired layer (ancillary) — e.g. a lapsed roof-solar lease — flags the Project in the expiring lens and on the detail card, but does not block the stage (only the Primary gates it, FR-9.4).
Renewal of a layer: the new lease inherits the old one’s layer (and its Primary flag if it had one); the old one becomes Superseded, drops out of active roll-ups, and stays on file (FR-9.7).
Same layer twice is rejected: at most one active lease per layer (FR-9.10). A renewal is the exception — it Supersedes the one it replaces, which leaves active. A bridging lease on a layer whose long-term lease is signed but not yet started is fine because the long-term one is pending, not active, so only one is active at a time.
Combined-layer lease (e.g. {land, building} in one agreement) claims both layers; a later separate building lease for that location is then rejected until the combined one is superseded or its building layer removed.
Master agreement (FR-9.14): deleting or superseding one site’s lease does not touch its siblings; each site’s apportioned rent is independent, and the shared masterRef just links them for reference.
Post-handover (FR-9.12): a lease expiring after its Project is operating still fires reminders to the Location Acquisition Manager and escalates to the Facilities PM; the location never falls off the renewal lens just because the build is done.

8. Permissions

Unchanged from the persona PRD §5:

Action	Location Acquisition Manager	PM / VP
Add / edit / supersede leases, set Primary, mark Essential	Yes, on Projects in their region	Read
Advance a stage (incl. the Leased gate)	No (files the Primary, which enables the gate)	Yes (FR-11)
Lease ownership after handover (Operating locations)	Retained — renews and holds the landlord relationship (FR-9.12)	Facilities PM reads the operating site’s leases; renewal escalations route to them

All lease edits are audit-logged; supersede preserves history (FR-9.7).

9. Out of scope

Rent payment / invoicing; lease-document storage backend; clause management / e-signature; a full lease-to-Project many-to-many (a master agreement is handled by reference, FR-9.14). No change to build-stage gating or to who advances stages (FR-10 / FR-11 unchanged); FR-9.12 adds only a terminal Operating state after Handover so leases have somewhere to live.

10. Decisions (resolved)

Every question raised during drafting is decided here and implemented in the requirements above. Kept for the record and the rationale.

D1 — Master agreement across locations → by reference, not a shared record. A lease stays a child of exactly one Project. A single agreement covering multiple sites is recorded as a lease per Project, sharing a masterRef with apportioned rent (FR-9.14). Why: captures the real case without a lease-to-Project many-to-many, which would complicate every roll-up for a rare situation; the shared id still links them for the reader.
D2 — Leases outlive the build. A Project moves to a terminal Operating state at Handover and keeps its leases; the Location Acquisition Manager remains the lease owner and renewer, with the Facilities PM reading (FR-9.12, §8). Why: a lease’s life is years longer than the construction project, and the persona’s own remit already includes post-development lease management — the record must not vanish at handover. Resolves persona PRD open question 6.
D3 — Reminders fire on the Notifications page + email, and escalate. Each lease’s reminder surfaces on the canonical Atlas Notifications page and by email to the lease owner, escalating to the Facilities PM when an essential lease, or any lease within 30 days of expiry, is unactioned (FR-9.13). Why: gives the reminder a concrete home (the shell surface every flow carries) and a safety net. Resolves persona PRD open question 4.
D4 — Rent is structured now. rentAmount + rentCurrency (₦ default) + rentPeriod replace the free-text string (FR-9.11), so the multi-lease total (FR-9.8) is exact. Why: with several leases per location, a best-effort sum of display strings would be wrong; the cost of structuring is one migration parse.
D5 — Build stages are gated by the Primary only; critical layers escalate, never block. No ancillary layer hard-gates a build stage; instead any lease can be flagged essential, which raises a High-priority renewal alert and a prominent flag on lapse (FR-9.4, FR-9.13). Why: blocking the build pipeline on, say, a signage lease would be wrong, but a lapsing grid-tie or roof-solar lease must not pass quietly — escalation, not a gate, is the right control.
D6 — One agreement over two layers → multi-select layers. layer became layers (a set); a combined land-and-building agreement names both (FR-9.9, §6). Why: it reflects real agreements exactly, and the “one active lease per layer” rule (FR-9.10) still holds per layer.
D7 — Layer taxonomy fixed, with the raised gaps added. The set is Land · Building · Roof · Airspace / signage · Car park · Grid / sub-surface · Whole site · Other (FR-9.9). Why: Car park and Grid / sub-surface are common and Rechaj-specific (grid-tie easements), so they earn first-class values; Other + note remains the escape hatch, and the set is reviewable in a later version if a new layer recurs.