Skip to content

Unit library

Generated from openspec/specs/unit-library/spec.md — edit that file, not this page.

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.

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
  • WHEN a homeowner tries to continue without selecting a unit
  • THEN the flow does not advance, and no project is created
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
  • 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.

  • 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
  • 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.

  • 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
  • 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.

  • 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