Cruits Housing — Product Backlog¶

GitHub: https://github.com/WAconsult/cruits-housing-ba/blob/main/01-scoping/planning-artifacts/backlog.md

Requirements are decomposed into epics following three principles: user value first, logical cohesion, and respect for the PRD's three-layer architecture (Housing Core · Cruits Integration · Workinn Integration). Iterations cut across epics and define what gets delivered in a given time window.

Epics¶

Epic 1: Project Bootstrap & Housing Inventory Management¶

The system is initialized and deployed. A Provider can log in to Provider Admin, create and manage housing listings (beds and private rooms), configure pricing per rental period, view the booking list per listing and manage capacity blocks, and define payment terms per payer-provider agreement. All actor identities and access controls are established.

Out of scope: self-registration for any actor type (Platform Admin creates all accounts in MVP).

Stories¶

Story 1.1 — Housing Backend Service Initialization As a Platform Admin, I want the housing-be service running via Docker Compose with Django, DRF, Celery, Redis, and PostgreSQL deployed and accessible, so that the team has a stable, runnable backend foundation on which all subsequent features can be built.

Story 1.2 — Housing Admin Frontend Initialization As a Platform Admin, I want the housing-admin-fe React application initialized with Mantine, routing, and an API client configured, so that Provider and Payer Admin screens can be developed on a consistent, ready-to-use frontend foundation.

Story 1.3 — Actor Identity Store & Authentication As a Platform Admin, I want to create accounts for Providers, Payers, and Platform Admins, and have all actors authenticate via OAuth2, so that only verified, authorized users can access the Housing Module.

Story 1.4 — Role-Based Access Control As a Platform Admin, I want access to be enforced strictly by actor role — Providers see only their own data, Payers see only their residents, Flexworkers cannot perform admin actions — so that no actor can access resources or operations outside their permitted scope.

Story 1.5 — GDPR Consent & Anonymisation As a Flexworker, I want to give explicit, timestamped consent before my personal data is stored, and to be able to submit a data anonymisation request, so that my rights under GDPR/AVG are respected and my request is acknowledged and queued for processing.

Story 1.6 — ListingUnit Creation & Management As a Provider, I want to create and manage Buildings (each with a shared address) and create, edit, and deactivate ListingUnits (beds and private rooms) under those Buildings — with type, title, description, capacity, amenities, media, and unit mode (concrete or pool) — via Provider Admin, so that my inventory is accurately represented in the system with no address duplication and is available for worker discovery.

Story 1.7 — Booking List & Provider Blocks As a Provider, I want to view all bookings (resident reservations and capacity blocks) for each of my listings with their current statuses, and to create and cancel capacity blocks for specific date ranges via Provider Admin, so that I have full visibility over listing occupancy and workers can only attempt to reserve units that are genuinely available.

Story 1.8 — Pricing Configuration As a Provider, I want to set a price per listing per rental period (day, week, or month) and define a minimum stay length via Provider Admin, so that workers see accurate pricing and can only attempt to book for valid stay durations.

Story 1.9a — Payer Agreement Management (Iteration 2) As a Provider, I want to configure which Payers have indirect payment access to my listings via Provider Admin, so that only Payers I have a formal agreement with can book my listings under indirect payment, and workers from other Payers can only book via direct payment. FR-8 (partial). Delivers PayerProviderAgreement entity with indirect_payment = enabled / direct_payment_only. Discovery and reservation enforce this check. Extended in Story 1.9.

Story 1.9 — Payment Terms Configuration (Iteration 4) As a Provider, I want to configure full payment terms per payer-provider agreement (prepay N days before arrival, postpay N days after arrival, or custom schedule) and set default payment terms that apply to all direct-payment bookings, via Provider Admin, so that the correct payment arrangement is automatically applied when a booking is confirmed for each Payer and for direct-payment workers. FR-8. Extends Story 1.9a: adds payment schedule fields to existing PayerProviderAgreement records and adds a Provider-level default terms configuration for worker_direct bookings.

Story 1.10 — Provider Settings As a Provider, I want to configure my account-level defaults — specifically my default rental period unit and default minimum stay period — via Provider Admin, so that new listings are automatically pre-filled with my preferred defaults without requiring manual override each time.

Story 1.11 — House Rules & Restrictions [Nice to Have — post-MVP] As a Provider, I want to configure house rules and restrictions per listing (e.g., no smoking, no pets, quiet hours after a specified time) via Provider Admin, so that workers are clearly informed of property rules on the listing detail screen, separate from the amenities list. FR-85.

Story 1.12 — Housing Quality Score (PKS) on Listing As a Provider, I want to set an optional Housing Quality Score (PKS) on each of my listings via Provider Admin, so that the Cruits integration can use it to determine the maximum accommodation cost covered for workers under indirect payment, and workers can see the quality score of a listing before deciding to reserve. FR-90.

Epic 2: Worker Housing Discovery & Context Handshake¶

A Flexworker arriving through the Cruits app receives a booking context specifying their payment options. They can browse available listings filtered by proximity to their job site, apply filters, and view listing details. All context constraints are enforced server-side.

Out of scope: standalone housing discovery outside the Cruits app (post-MVP).

Stories¶

Story 2.1 — Context Handshake & Booking Context Enforcement As a Flexworker, I want the Cruits app to pass my worker identity, job location, and booking context (available payment options, permitted period, max daily cost) to the Housing Module when I open the Housing section, so that my listings are pre-filtered to my job site and the system enforces my available booking options server-side from the start of my session.

Story 2.2a — Listing Discovery As a Flexworker, I want to see a list of available housing listings in the Cruits app, so that I can browse available accommodation options.

Story 2.2b — Proximity-Based Discovery As a Flexworker, I want to see available housing listings sorted by distance to my job site when I open the Housing section in the Cruits app, so that I can immediately find the most conveniently located accommodation without manual location entry.

Depends on: Story 2.1.

Story 2.3 — Listing Search & Filters As a Flexworker, I want to filter available listings by room type, maximum distance from my job site, and maximum price per period, so that I can quickly narrow down options to those that match my preferences and stay within my budget.

Story 2.4 — Listing Detail View As a Flexworker, I want to view the full details of a listing — photos, description, room type, price per period, distance to my job site, and available unit count or unit identifiers — so that I have all the information I need to make an informed decision before creating a reservation.

Story 2.5 — Saved Listings (Bookmarks) [Nice to Have — post-MVP] As a Flexworker, I want to save listings to a personal bookmark list from the listing card or detail screen, and view saved listings in a dedicated section, so that I can easily return to listings I am interested in without losing them when I close the app. FR-86.

Story 2.6 — Listing Ratings & Reviews [post-MVP] As a Flexworker, I want to see an aggregate star rating and individual text reviews from past residents on the listing detail screen, so that I can make a more informed decision based on real experiences. FR-87. Note: review submission requires a post-checkout review flow not in scope for any current iteration.

Story 2.7 — Interactive Map on Listing Detail [Nice to Have — post-MVP] As a Flexworker, I want to see the listing's location on an interactive map on the detail screen, so that I can visually assess the property's location relative to the city and my job site. FR-88. Scope: Cruits app only (Maps SDK already integrated in Cruits); no backend changes required beyond exposing existing Building coordinates.

Story 2.8 — Pre-Booking Inquiry [post-MVP] As a Flexworker, I want to send a message to a Provider from the listing detail screen before creating a reservation, so that I can ask questions about the listing without committing to a booking. FR-89. Note: MVP messaging is scoped to active bookings only (FR-54, Story 9.2).

Epic 3: Reservation & Booking Flow¶

Visual reference: payment-config-diagram.xml — full booking state machine (open in draw.io).

A Resident can create a reservation and progress through the full booking state machine (RESERVED → PENDING_PROVIDER → PENDING_PAYER → BOOKED). Hold windows are enforced automatically. All actors receive notifications at each relevant state transition. Bookings transition to ENDED only on explicit checkout action; overstay handling and period-end notifications meet WGV (Wet goed verhuurderschap) legal obligations.

Out of scope: automatic ENDED transition at period.end; financial penalties on cancellation (logging only); deduplication logic for duplicate active reservations (deferred to Story 3.1).

Stories¶

Story 3.1 — Reservation Hold Window Enforcement As a Platform Admin, I want the system to automatically release expired reservation holds and payer approval windows using Celery Beat scheduled tasks, so that units are not locked indefinitely when a booking stalls and capacity returns to the available pool without manual intervention.

Story 3.2 — Reservation Creation As a Flexworker, I want to create a reservation for an available listing from the Cruits app — selecting a specific unit for concrete-mode listings or confirming a pool slot for pool-mode listings — and, when reserving under indirect payment, to see and acknowledge a confirmation notice detailing the payer-covered period, the payer's name, my rights to independent booking, and the 28-day period-end reminder — so that the unit is held for me, the booking record is created with my resident and payer identities, WGV notice obligations are met, and the booking process begins.

Story 3.3 — Provider Confirmation & Direct Booking Path As a Flexworker, I want my reservation to automatically progress through provider confirmation, and — when I am my own payer and no signing is required — reach BOOKED without any manual step, so that my housing is confirmed as quickly as possible.

Story 3.4 — Payer Confirmation Flow As a Payer, I want to be notified when a reservation is waiting for my approval and to be able to confirm or reject it via Payer Admin or API call, so that I can control which housing bookings proceed on behalf of my residents, and the booking either advances to the next step or is released.

Story 3.5 — Booking State Transition Notifications As a Flexworker (and Provider, Payer), I want to receive a notification at every booking state transition relevant to me — an in-app push notification in the Cruits app for the worker, and a desktop notification via SSE for Provider and Payer Admin — so that all parties are kept informed in real time without having to poll for status updates.

Story 3.6 — Booking Status View As a Flexworker, I want to view the current status and full details of my active reservation or booking from the Cruits app, so that I can track where my booking stands and access the confirmed details at any time.

Story 3.7 — Pre-BOOKED Cancellation As a Flexworker, I want to cancel my reservation or booking at any point before it reaches BOOKED state, so that the unit hold is released and I am not committed to housing I no longer need.

Story 3.8 — WGV Compliance: ENDED Trigger, Overstay & Period-End Notification As a Provider (and Platform Admin), I want bookings to transition to ENDED only on explicit checkout action (Resident self-checkout or Provider confirmation), to be notified — along with the Resident — when a booking period ends without checkout, to be able to flag a booking as Overstay, and for Residents to receive advance period-end notification reminders, so that the Housing Module meets all obligations under Wet goed verhuurderschap (WGV) and housing law art. 7:231 BW regarding tenancy continuity and resident rights.

Covers: FR-80, FR-81, FR-83. Note: FR-82 (indirect-payment confirmation notice) is implemented in Story 3.2.

Story 3.9 — BOOKED Booking Cancellation As a Flexworker (and Provider, Payer), I want to cancel a confirmed booking, providing a reason and acknowledging that I take responsibility as defined by the accommodation contract and applicable legislation, so that the unit is released, all parties are notified of the cancellation and its stated reason, and the event is permanently recorded in the booking history.

Note: cancellation window configuration (per Provider/Payer settings) is a prerequisite; financial penalties are outside MVP scope.

Epic 4: Documents Management¶

A Provider can upload contract templates and configure signing mode (per-booking or framework). When a booking reaches the signing step, a DocuSign envelope is created and the Resident signs digitally. Signed contracts are downloaded, stored internally, and accessible to all parties — including after the booking ends.

Out of scope: Payer signing; DocuSign envelope resend (worker must create a new Reservation if envelope expires); multi-language template generation.

Stories¶

Story 4.1 — Contract Template Setup & Signing Mode Configuration As a Provider, I want to upload a contract template and choose a signing mode — per-booking (a new contract is signed for each booking) or framework (a single contract is signed once per resident-provider pair) — via Provider Admin, so that the correct contract and signing workflow is applied automatically when a booking reaches the signing step.

Story 4.2 — DocuSign Signing Envelope: Per-Booking Mode As a Flexworker, I want to receive a DocuSign signing request for my booking contract and complete the signature digitally, so that my accommodation agreement is formally signed and the booking can advance to BOOKED.

Story 4.3 — Framework Contract Mode As a Flexworker, I want to sign a framework contract with a housing provider once, so that all subsequent bookings with the same provider proceed directly to BOOKED without requiring me to sign again.

Story 4.4 — Signed Document Storage & Access As a Flexworker (and Provider, Payer), I want the completed, signed contract to be permanently stored in the Housing Module and accessible from the booking detail view — including after the booking has ended or been cancelled — so that all parties have a reliable, permanent record of the signed agreement.

Epic 5: Provider Operations¶

A Provider can view all active residents across their properties (booking and payment status), access the archive of past bookings, raise Ghost Alarms when physical presence is in question, and manage document templates — all via Provider Admin.

Stories¶

Story 5.1 — Active Residents View As a Provider, I want to see a list of all current residents across my properties — with their booking status and payment status per booking — via Provider Admin, so that I have operational visibility over who is living in my units and can identify any issues at a glance.

Story 5.2 — Booking Archive As a Provider, I want to access an archive of all past bookings (ENDED and CANCELLED) with the same resident and booking details as the active view — via Provider Admin, so that I have a complete historical record of all residencies for reference and reporting.

Story 5.3 — Ghost Alarm Management As a Provider, I want to raise a Ghost Alarm on any active resident when I suspect their physical presence at the booked address is in question, and to receive a notification when a Payer raises a Ghost Alarm on one of my residents, so that all parties are alerted and can take appropriate action, and the event is logged in the booking history.

Epic 6: Payer Operations¶

A Payer can view all resident bookings, confirm or reject pending reservations, raise Ghost Alarms, and monitor settlement reports via Payer Admin. A Provider can enable automatic invoice generation per payer agreement; invoices are accessible from the Settlements view.

Out of scope: payment tracking, outstanding balance calculation, and reconciliation (post-MVP).

Stories¶

Story 6.1 — Payer Residents View & Reservation Management As a Payer, I want to view all active and historical bookings for my residents — with booking and payment status per booking — and confirm or reject reservations awaiting my approval from Payer Admin, so that I have full visibility over housing for workers in my care and can act on pending approvals in one place.

Story 6.2 — Settlements View As a Payer, I want to view a financial settlements report showing the amount, period, and payment status (paid / pending / overdue) for each booking, with aggregate totals, so that I can monitor housing costs and identify any outstanding payments.

Story 6.3 — Ghost Alarm Management: Payer As a Payer, I want to raise a Ghost Alarm on any of my active residents and receive a notification when a Provider raises a Ghost Alarm on one of my residents, so that I am always informed when a resident's physical presence is in question and can take appropriate action.

Story 6.4 — Automatic Invoice Generation As a Provider, I want to upload an invoice template and enable automatic invoice generation per payer agreement, so that PDF invoices are generated automatically according to the payment schedule and are accessible to the Payer from their Settlements view.

Epic 7: Cruits Booking Flow Integration¶

When a booking is confirmed, the Cruits platform automatically receives the confirmed housing address and booking details. Booking failures and cancellations are also delivered. Pool-mode address updates (assigned post check-in) trigger re-delivery. All delivery is at-least-once with event_id deduplication.

Stories¶

Story 7.1 — Booking Status Webhook Delivery to Cruits As the Cruits Platform, I want to automatically receive a webhook notification — with confirmed address, booking status, period, price, and payment form — whenever a booking reaches BOOKED, CANCELLED, or RESERVATION_FAILED state, so that the Cruits system always has up-to-date housing status for each worker without manual data entry, with at-least-once delivery guaranteed via event_id deduplication.

Story 7.2 — Pool-Mode Address Update Re-Delivery As the Cruits Platform, I want to automatically receive an updated confirmed address when a Provider assigns a specific unit to a pool-mode resident after check-in, so that the Cruits system holds the exact unit address — not just the building address — once it becomes known.

Epic 8: Workinn / GoMeddo Integration¶

Workinn housing inventory syncs automatically from GoMeddo via event-driven webhooks (delta-sync by default, full resync on demand). Provider confirmation for Workinn listings routes through the GoMeddo API. GoMeddo-generated accommodation agreements are supplied to Housing Core for signing. Active bookings are protected from sync conflicts.

Stories¶

Story 8.1 — GoMeddo Inventory Full Sync & Data Mapping As a Platform Admin, I want to trigger a full sync of Workinn inventory from GoMeddo — capturing unit type, hierarchy position, address, price, media (with fallback), and availability — and have all units represented as ListingUnits in the Housing Module, so that Workinn housing is available for worker discovery from day one of the integration.

Story 8.2 — Event-Driven Delta Sync via GoMeddo Webhooks As a Platform Admin, I want the system to automatically update Workinn ListingUnit availability and pricing in real time by subscribing to GoMeddo webhook events, so that inventory data stays current without requiring manual resyncs after initial onboarding.

Story 8.3 — Active Booking Conflict Protection As a Platform Admin, I want sync operations to leave any ListingUnit with an active booking untouched, and to receive a notification and a conflict record when an incoming GoMeddo event conflicts with an active booking, so that no automated sync can inadvertently disrupt a booking already in progress.

Story 8.4 — GoMeddo Provider Confirmation Flow As a Flexworker, I want my reservation for a Workinn listing to be automatically confirmed or rejected via the GoMeddo API, with the booking advancing or failing accordingly, so that Workinn availability is verified in real time as part of the standard booking flow.

Story 8.5 — GoMeddo Document Integration As a Flexworker, I want the accommodation agreement generated by GoMeddo for my Workinn booking to be automatically used as the contract for the signing step, so that the correct Workinn contract is always applied without requiring the Provider to upload a separate template.

Epic 9: In-App Messaging¶

A Provider and Resident can exchange in-app messages within the context of an active booking. Message history is preserved for the booking duration and retained after ENDED / CANCELLED for the same period as the booking record. Post-booking access: Provider via Archive view; Resident via booking history.

Out of scope: WhatsApp and external channel integrations (post-MVP); new messages initiated after booking reaches ENDED or CANCELLED.

Stories¶

Story 9.1 — Messaging Infrastructure & Provider Admin Interface As a Provider, I want to send and receive in-app messages with each of my active residents directly from Provider Admin, with full message history preserved for the duration of the booking, so that I can communicate with residents without leaving the platform or relying on external channels.

Story 9.2 — Flexworker Messaging in Cruits App As a Flexworker, I want to access in-app messaging with my housing provider from the booking status view in the Cruits app, so that I can ask questions or communicate issues directly with the provider without leaving the app.

Iterations¶

Iteration 1: Housing Inventory Browsing¶

Goal: A Flexworker can open the Housing section in the Cruits app and browse the full housing inventory — list view and listing detail. A Provider can create and manage listings with pricing via Provider Admin.

Explicitly deferred to later iterations: context handshake & booking context (2.1), proximity filtering (2.2b), listing filters (2.3), GDPR consent framework (1.5), booking list & provider blocks (1.7), payment terms configuration (1.9).

Comments