Unit library
Generated from
openspec/specs/unit-library/spec.md— edit that file, not this page.
Purpose
Section titled “Purpose”The catalogue of HDB units a homeowner can start a project from — what is known about each one, which of them can actually be furnished, and how someone asks for a unit that has not been traced yet.
Requirements
Section titled “Requirements”Requirement: A published unit carries the facts a homeowner picks by
Section titled “Requirement: A published unit carries the facts a homeowner picks by”The system SHALL describe every published unit by its block, its unit type and its floor area, so a homeowner can recognise their own flat without opening it. A unit missing any of these SHALL remain selectable rather than being hidden.
Scenario: A homeowner finds their flat by block
Section titled “Scenario: A homeowner finds their flat by block”- WHEN a homeowner opens the unit picker
- THEN published units are grouped by block, each showing unit type and floor area
Scenario: A unit whose metadata is incomplete is still offered
Section titled “Scenario: A unit whose metadata is incomplete is still offered”- WHEN a published unit has no block or unit type recorded
- THEN it still appears in the picker under its name, because a unit someone lives in must not vanish from the list on account of a missing field
Requirement: No unit is chosen for the homeowner
Section titled “Requirement: No unit is chosen for the homeowner”The system SHALL NOT preselect a unit. A homeowner SHALL choose theirs explicitly before a project is created, and the flow SHALL NOT advance until they have.
Scenario: The picker opens with nothing selected
Section titled “Scenario: The picker opens with nothing selected”- WHEN a homeowner opens the unit picker
- THEN no unit is selected and the action that continues is unavailable
Scenario: Continuing requires a choice
Section titled “Scenario: Continuing requires a choice”- WHEN a homeowner tries to continue without selecting a unit
- THEN the flow does not advance, and no project is created
Scenario: No unit is presented as the recommended one
Section titled “Scenario: No unit is presented as the recommended one”- WHEN the picker lists published units
- THEN none is marked as a default or otherwise ranked above the others — which flat a homeowner lives in is not something the product can suggest, and a default is how someone ends up in a unit that is not theirs
Requirement: A unit that cannot be furnished is not selectable
Section titled “Requirement: A unit that cannot be furnished is not selectable”The system SHALL record, per published unit, whether that unit’s floorplan contains labelled rooms that furnishing recipes can match. A unit that does not SHALL be listed so a homeowner can see their block is known, but SHALL NOT be selectable — it SHALL offer to notify them when it is ready instead. A unit whose layout is still being drawn cannot deliver the flow’s one promise, and letting someone pick it only to reach an empty shell is worse than saying it is not ready.
Scenario: A unit with no interior rooms is listed but not selectable
Section titled “Scenario: A unit with no interior rooms is listed but not selectable”- WHEN a published unit’s floorplan resolves to a single enclosed outline with no labelled rooms
- THEN the picker shows it, says its layout is still being drawn, and offers to notify the homeowner rather than letting them select it
Scenario: Notify-me joins the same queue as an unpublished block
Section titled “Scenario: Notify-me joins the same queue as an unpublished block”- WHEN a homeowner asks to be notified about a listed-but-unfurnishable unit
- THEN a request is recorded for that block and unit type exactly as if the unit had never been published, so the two ways of waiting produce one queue and one demand count
Scenario: A furnishable unit generates
Section titled “Scenario: A furnishable unit generates”- WHEN a homeowner selects a unit whose floorplan carries labelled rooms
- THEN the generate step runs against it
Scenario: Continuing is never possible from an unfurnishable unit
Section titled “Scenario: Continuing is never possible from an unfurnishable unit”- WHEN a homeowner tries to continue with only an unfurnishable unit chosen
- THEN the flow does not advance and no project is created
Requirement: A homeowner can request a unit that is not published
Section titled “Requirement: A homeowner can request a unit that is not published”The system SHALL let a signed-in homeowner request an HDB unit that the library does not carry, capturing at least the block and the unit type, and SHALL create their account and project intent rather than turning them away.
Scenario: Requesting an untraced block
Section titled “Scenario: Requesting an untraced block”- WHEN a homeowner cannot find their block and submits a request naming the block and unit type
- THEN the request is recorded against their account and acknowledged
Scenario: An HDB floorplan can be attached
Section titled “Scenario: An HDB floorplan can be attached”- WHEN a homeowner attaches the floorplan PDF issued for their unit
- THEN it is stored with the request, because it is what the unit is traced from
Scenario: Requesting twice does not double-count demand
Section titled “Scenario: Requesting twice does not double-count demand”- WHEN a homeowner submits a request for a block and unit type they have already requested
- THEN their existing request is returned rather than a second one created
Requirement: Queue position is shown honestly and drives prioritisation
Section titled “Requirement: Queue position is shown honestly and drives prioritisation”The system SHALL show a requester how many others are waiting on the same unit, and SHALL let an administrator see outstanding requests ordered by that same count — one number serving both the person waiting and the person deciding what to trace next.
Scenario: A requester sees how many are waiting
Section titled “Scenario: A requester sees how many are waiting”- WHEN a homeowner views a request they submitted
- THEN they are shown the number of distinct requesters for that block and unit type
Scenario: Admin sees demand, most-requested first
Section titled “Scenario: Admin sees demand, most-requested first”- WHEN an administrator lists outstanding unit requests
- THEN they are ordered by number of distinct requesters, descending
Scenario: Publishing a usable unit resolves its requests
Section titled “Scenario: Publishing a usable unit resolves its requests”- WHEN a unit matching an outstanding request is published and can be furnished
- THEN those requests are marked fulfilled and are no longer counted as outstanding demand
Requirement: Requesters are emailed when their unit becomes usable
Section titled “Requirement: Requesters are emailed when their unit becomes usable”The system SHALL email each requester when a unit matching their request becomes selectable — that is, when it is published and furnishable — and SHALL email each of them at most once per request. Publishing a unit that still cannot be furnished SHALL NOT notify anyone, because nothing has changed for the person waiting.
Scenario: Release notifies everyone waiting
Section titled “Scenario: Release notifies everyone waiting”- WHEN a unit matching outstanding requests is published and can be furnished
- THEN every distinct requester receives an email naming the block and unit type, with a link that starts a project on it
Scenario: Publishing an unfurnishable unit notifies nobody
Section titled “Scenario: Publishing an unfurnishable unit notifies nobody”- WHEN a unit matching outstanding requests is published but carries no labelled rooms
- THEN no email is sent and the requests stay outstanding — the homeowner still cannot do the thing they were waiting to do
Scenario: A requester is emailed once
Section titled “Scenario: A requester is emailed once”- WHEN a unit is published, and is later updated or republished
- THEN requesters already notified are not emailed again
Scenario: A failed send does not lose the release
Section titled “Scenario: A failed send does not lose the release”- WHEN sending a notification fails
- THEN the unit remains published and the request remains marked fulfilled — the email is a courtesy, and a mail outage must not roll back a release or leave the queue inconsistent
Requirement: A waiting homeowner is offered somewhere to start
Section titled “Requirement: A waiting homeowner is offered somewhere to start”The system SHALL offer a homeowner whose unit is unavailable a published unit of the same room count to work on meanwhile, labelled as a stand-in rather than as their flat.
Scenario: A stand-in is offered
Section titled “Scenario: A stand-in is offered”- WHEN a homeowner’s requested unit type is not published but another published unit has the same number of bedrooms
- THEN that unit is offered as a stand-in, described as not being their exact walls
Scenario: No stand-in exists
Section titled “Scenario: No stand-in exists”- WHEN no published unit matches the requested room count
- THEN no stand-in is offered, and the request is acknowledged on its own — an unrelated layout is worse than none
Requirement: Administrators can read a unit’s stored floorplan
Section titled “Requirement: Administrators can read a unit’s stored floorplan”The system SHALL provide administrators a way to read a published unit’s stored floorplan, so that its contents can be inspected without creating a project from it.
Scenario: Reading a unit’s floorplan
Section titled “Scenario: Reading a unit’s floorplan”- WHEN an administrator requests a published unit by id
- THEN the response includes the unit’s stored floorplan and its recorded metadata
Requirement: Whether a unit is furnishable follows the published recipes
Section titled “Requirement: Whether a unit is furnishable follows the published recipes”Whether a unit’s rooms can be furnished depends on the recipes in force, so the system SHALL decide it against the published recipe set rather than a fixed one, and SHALL bring every published unit’s recorded answer up to date when that set changes. A recipe that matches more room labels makes more units selectable, and a recorded answer that disagrees with the recipes in force is worse than no record at all.
Scenario: Publishing a broader recipe makes a unit selectable
Section titled “Scenario: Publishing a broader recipe makes a unit selectable”- WHEN a recipe set is published whose labels match rooms in a unit previously recorded as not furnishable
- THEN that unit’s recorded answer is brought up to date, and the homeowner picker offers it
Scenario: Publishing a narrower recipe withdraws a unit
Section titled “Scenario: Publishing a narrower recipe withdraws a unit”- WHEN a published set no longer matches any room in a unit that was selectable
- THEN that unit stops being selectable and returns to offering notification instead
Scenario: What publication changed is reported
Section titled “Scenario: What publication changed is reported”- WHEN publishing changes which units are furnishable
- THEN the administrator is told how many units changed, so a recipe edit with consequences for the homeowner flow is not silent