Property Archive and Delete — P2
Adds two ways to take a rental property off the platform: permanent delete for a property no tenant ever interacted with, and a reversible archive for every other property. Archive closes open enquiries and emails tenants, never touches a current or upcoming tenancy, and keeps tenant history readable; it ships on the rental app, v1 and the Partner API.
- Predecessor Partner API — P1: Foundation and Supply Side (2026-10-03)
- Status Approved
Summary
Landlords and partners get two ways to take a property off the platform: a permanent delete for a property no tenant ever interacted with, and a reversible archive for everything else. Archive closes open enquiries and emails the tenants, never touches a current or upcoming tenancy, and keeps every tenant's history readable.
Decisions
Taken by the product owner on 2026-10-06.
- E1 · Two operations
- Permanent delete for a property no tenant ever interacted with; archive (reversible soft removal) for every other property.
- E2 · Delete eligibility
- None of the property's listings, in any status, ever had a viewing request, offer, agreement or tenancy, and no tenancy names the property. Having been live does not matter.
- E3 · Archive blockers
- Only a current or upcoming tenancy, or an agreement awaiting signatures, refuses archive. Everything else open is closed automatically and affected tenants are emailed.
- E4 · Restore
- An archived property can be restored at any time. Its listings stay withdrawn.
- E5 · Who
- The landlord may delete, archive and restore from the rental app and with a v1 key holding
properties:write. A partner may do so only for properties it created (origin_partner_id= the partner). - E6 · Storage and verbs
- Archive is a new
archived_atcolumn with explicit actions:POST …/archive,POST …/restore,DELETE= permanent only.deleted_atis not reused.
409 property_has_history; the caller archives instead.A · archived_at + explicit verbs
- History views
- Keep working
- Data destruction
- Only on explicit DELETE
- Cost
- One column, named filters
Archive, restore and delete are separate calls; only property-scoped "active" queries add a filter.
B · Single smart DELETE
- History views
- Keep working
- Data destruction
- Unpredictable to caller
- Cost
- One call
DELETE deletes or archives on its own. A retry after a timeout could archive what the caller expected gone; breaks "DELETE means gone".
C · Reuse deleted_at
- History views
- Break
- Data destruction
- Only on explicit DELETE
- Cost
Unscoped()everywhere
GetByID would hide archived properties from agreement and tenancy views; fixing it inverts the safety of the default scope.
Non-goals
- No change to tenancy, agreement, payment, handover or message behaviour or visibility.
- No bulk archive or delete; no scheduled purge of archived properties.
- No storage sweep for objects left behind by a failed post-commit removal.
- No change to the test-data purge (
PurgeTestProperties). - No admin-initiated archive or delete.
Lifecycle
States
active is archived_at IS NULL; archived has it set. Delete removes the row; there is no deleted state.Delete eligibility (E2)
A property is delete-eligible when none of these exist, counting soft-deleted rows and every status:
- a
rental_viewing_requestsrow on any of its listings; - a
rental_offersrow on any of its listings; - a
rental_tenancy_agreementsrow on any of its listings; - a
rental_tenanciesrow withproperty_id= the property.
One EXISTS query computes it; can_delete and DELETE share it. Not eligible → 409 property_has_history.
Archive (E3)
Otherwise, in one transaction after locking the property row:
-
Withdraw listings
Every listing in
draft,pending_review,rejected,liveorsuspendedmoves towithdrawnthrough a new state-machine eventarchive.withdrawkeeps its live-only rule. -
Close viewing requests
pendingorcountered→declinedwith reason "This property is no longer available";confirmed→cancelled. -
Close offers
pendingorcountered→declinedwith the same reason. -
Mark archived
archived_at = now(),archived_by_actorset. -
Business audit row
With counts of listings withdrawn, viewings declined, viewings cancelled, offers declined.
After commit: NotifyViewingDeclined, NotifyViewingCancelled, NotifyOfferDeclined per affected tenant. A mailer error is logged and does not undo the archive. Archiving an archived property → 200, no change, no email.
While archived
Excluded
hidden- Default property lists (landlord, v1, partner)
- Duplicate-address detection
- Catalog and dashboard already exclude it: archive left no live listing and no open request
Refused
409 property_archived- Property update
- Listing create, upsert and submit
- Photo upload, delete, reorder and gallery sync; proof upload
- v1 and partner property upsert matching it by
external_ref— a sync never recreates or silently restores
Unchanged
readable- Tenancies, agreements, payments, handover, messages
- The property detail for its parties
GetByIDis not filtered
Restore (E4)
In one transaction after locking the property row: clear archived_at and archived_by_actor; run the same duplicate-address check a new property gets (checkAndRaiseDuplicateFlag, usecase/property.go:470); business audit row. Listings stay withdrawn; a new listing goes through review as usual. Photos, proofs and external refs are unchanged. Restoring an active property → 200, no change.
Delete
- Lock the property row and re-run eligibility.
- Read photo and proof storage keys, including soft-deleted rows (
Unscoped). - Write the business audit row with the property id and an address snapshot.
Unscopedhard delete: cascades remove listings, photos, proofs, external refs, duplicate flags and hints, and listing checks.- After commit:
PhotoStore.RemoveandProofStore.Deleteper key. A storage error is logged and the request still returns204.
A second DELETE → 404 property_not_found.
API and surfaces
One PropertyLifecycleUseCase serves every surface.
| Operation | Rental app (session) | v1 (landlord key) | Partner (P1 surface) | Success |
|---|---|---|---|---|
| Archive | POST /api/rental/properties/{id}/archive | POST /api/v1/rental/properties/{id}/archive | POST /api/partner/v1/landlords/{lid}/properties/{id}/archive | 200 property |
| Restore | POST /api/rental/properties/{id}/restore | POST /api/v1/rental/properties/{id}/restore | POST /api/partner/v1/landlords/{lid}/properties/{id}/restore | 200 property |
| Delete | DELETE /api/rental/properties/{id} | DELETE /api/v1/rental/properties/{id} | DELETE /api/partner/v1/landlords/{lid}/properties/{id} | 204 |
- Session routes sit behind the existing
RequireLandlord; ownership byEnsureOwner, mismatch →404 property_not_found. - v1 and partner routes require
properties:write. - Partner routes also require
origin_partner_id= the calling partner, else404 property_not_found; no active grant →404 landlord_not_found. - Archive and restore are idempotent by state; no
Idempotency-Keystorage.
List filter and response fields
?archived=true- On
GET …/propertieson all three surfaces: archived only. Default stays active only, so existing callers see no change. archived_at- Nullable timestamp in the property body on all surfaces — additive.
can_delete- Boolean in the owner property detail only (rental app session route), computed by the eligibility query.
archive_impact- Owner detail only:
{ listings, viewing_requests_declined, viewing_requests_cancelled, offers_declined }— the counts archive would change now. The archive confirmation shows them.
v1 contract
Additive: three operations, one response field, one query parameter, three error codes. The test at v1_routes_test.go:1740 that pins DELETE /properties/{id} as unmounted is retired. Updated:
backend/go/openapi/rental-v1.yamland its drift test;frontend/astro/apps/rental/src/docs/landlord-api-v1.md;- the key form's "what each bundle grants" list for
manage-listings(frontend/solidstart/apps/rental/src/features/rental/api/landlord-keys.ts) adds "archive, restore and delete properties".
Partner contract
Rental app (landlord)
- Property detail (
routes/landlord/[id].tsx):- Archive with a confirmation naming what will close (the listing, N viewing requests, N offers) from
archive_impact; - Delete permanently shown only when
can_delete, with a confirmation that requires typing the property's address line; - Restore when archived; edit actions hidden while archived.
- Archive with a confirmation naming what will close (the listing, N viewing requests, N offers) from
- Property list (
routes/landlord/index.tsx): Active / Archived toggle; archived rows show "Archived on {date}". - Tenancy, agreement, payment and handover pages of an archived property open as today.
Data
Schema (migrator_rental.go)
rental_properties.archived_at TIMESTAMPTZ NULL
rental_properties.archived_by_actor TEXT NULL CHECK (archived_by_actor IN ('landlord','api_key','partner'))
CHECK ((archived_at IS NULL) = (archived_by_actor IS NULL))
INDEX (owner_user_id, created_at DESC) WHERE archived_at IS NULL AND deleted_at IS NULL
Listing state machine: EventArchive from draft, pending_review, rejected, live, suspended to withdrawn (code only).
Queries that gain archived_at IS NULL
| Query | Location |
|---|---|
ListByOwner (default; ?archived=true uses IS NOT NULL) | property_repository.go:281 |
ListAddressReferences | :305 |
FindByFingerprint and building/postcode match | :317-343 |
FindCrossLandlordFingerprintMatches | :392 |
| Dup-check sweep and postcode candidates | :409-435 |
| Partner property list (P1) | partner handler |
Errors and concurrency
-
property_has_active_tenancyArchive with a tenancyends_on >= today(KL) or an agreementawaiting_signatures409 -
property_has_historyDelete of a non-eligible property 409 -
property_archivedA refused write on an archived property 409 -
property_not_foundNot yours, already deleted, or a partner acting on a property it did not create reused 404
v1 and partner routes use the v1 envelope; session routes use the rental module's existing error shape with the same codes.
Locks and racing writers
- Archive, restore and delete start with
SELECT … FOR UPDATEon the property row. - Viewing-request, offer and agreement creation take
SELECT … FOR SHAREon the property row before inserting, and refuse an archived property with409 property_archived.
409 property_has_history. An agreement racing an archive resolves the same way.Audit
- Business audit (
audit_log) - One row per archive, restore and delete, in the same transaction, with the existing actor fields (
actor_type,api_key_id,api_key_name, andpartner_idon partner routes). Archive adds counts of listings withdrawn, viewings declined, viewings cancelled, offers declined. Delete adds the property id and an address snapshot. - Row audit (
audit_trails) rental_propertiesalready hasfn_audit_trail(), so archive, restore and delete of the property row are trailed, including the deleted row's last state.
What exists today
Facts read from the repository (19 rows)
| Fact | Where |
|---|---|
rental_properties and rental_listings use gorm.DeletedAt; GORM reads skip soft-deleted rows | persistence/postgresql/property_repository.go:20-51, listing_repository.go:18-47 |
Agreement and tenancy use cases load the property with GetByID (soft-delete scoped) | application/usecase/agreement.go, usecase/tenancy.go |
Hard delete exists for test data only: HardDelete is Unscoped().Delete; candidates exclude properties with a reachable tenancy | property_repository.go:351-384, usecase/property.go:441-468 |
Foreign keys from properties ON DELETE CASCADE: listings, photos, proofs, external refs, duplicate flags and hints | migrations/migrator_rental.go:55,82,94,1422,1461-1462,1640-1641 |
Foreign keys from listings ON DELETE CASCADE: viewing requests, offers, tenancy agreements, listing checks | migrator_rental.go:247,334,379,1517 |
rental_tenancies.property_id has no foreign key; agreement_id is ON DELETE RESTRICT; tenancies have no status column (current/upcoming by starts_on/ends_on) | migrator_rental.go:550-561 |
Status sets: viewing requests pending, countered, confirmed, completed, declined, withdrawn, cancelled; offers pending, countered, accepted, declined, withdrawn; agreements awaiting_signatures, completed, voided | migrator_rental.go:250-251,350-352,398-399 |
Listing state machine: withdraw only from live; withdrawn and rented terminal; draft/pending_review/rejected/suspended have no path to a terminal state | domain/entity/listing.go:73-162 |
Landlord close paths and emails: viewing Decline (NotifyViewingDeclined), viewing Cancel (NotifyViewingCancelled), offer Decline (NotifyOfferDeclined) | usecase/viewing_request.go:772-857, usecase/offer.go:331, port/ports.go:561-573 |
Agreement creation refuses a conflicting tenancy or active agreement (PropertyTenancyOverlapError) | usecase/agreement.go:158-171,256-268 |
Catalog reads only live listings of non-deleted properties | listing_repository.go:408-413 |
Dashboard counts live listings, pending viewings, pending/countered offers, confirmed upcoming viewings | persistence/postgresql/dashboard_reader.go:69-139 |
| Property-scoped duplicate queries | property_repository.go:305-315,317-343,392,409-435 |
| History readers joining properties | landlord_agreement_reader.go:46, landlord_tenancy_reader.go:28, thread_repository.go:124, viewing_request_repository.go:287, handover_response_check_repository.go:278 |
Storage ports: PhotoStore.Remove(ctx, key), ProofStore.Delete(ctx, key) | port/ports.go:206-217,251-265 |
Row-audit trigger exists on rental_properties, rental_offers, rental_tenancy_agreements; none on rental_listings, photos, proofs, viewing requests | migrator_rental.go:200,370,430 |
v1 test pinning DELETE /api/v1/rental/properties/{id} as unmounted | adapter/inbound/http/v1_routes_test.go:1740 |
| Landlord property pages | frontend/solidstart/apps/rental/src/routes/landlord/index.tsx, [id].tsx |
| Landlord API guide | frontend/astro/apps/rental/src/docs/landlord-api-v1.md |
Testing
Integration suites on the disposable pg-test database (:55432).
- Eligibility
- Each of viewing request, offer, agreement, tenancy alone blocks delete; a soft-deleted viewing request blocks; a property that went live without enquiries is eligible;
can_deleteequals the DELETE outcome in every case. - Delete
- Cascades remove listings, photos, proofs, external refs, flags and hints; storage removal called with the read keys after commit; storage error still
204; second DELETE404; audit row with snapshot. - Archive
- Current tenancy, upcoming tenancy and
awaiting_signaturesagreement each block; ended tenancy does not; each non-terminal listing status →withdrawn; pending/countered viewings declined, confirmed cancelled, offers declined, one email each; mailer failure keeps the archive; second archive200and no email. - While archived
- Absent from default list, present with
?archived=true; not matched by duplicate detection; every refused write →409 property_archived; agreement, tenancy, payment and handover views load. - Restore
- Listings stay withdrawn; new listing allowed; duplicate check reruns; photos and refs intact.
- Races
- Delete vs new viewing request; archive vs new agreement — one consistent outcome each.
- Surfaces
- v1 requires
properties:write; partner acts on its own property, gets404on another partner's or the landlord's own; v1 drift and partner drift include the new routes and codes; the old v1 unmounted-DELETE test is removed. - Rental app
- Archive confirmation, delete visible only with
can_delete, Active/Archived toggle, restore, archived history pages — in the browser withegoon UAT.