DIY Rental Platform — Slice 1: Listings and Owner Onboarding

Why this document exists

plan.md describes a whole PropTech company — agent-free marketplace, legal document automation, e-signing, rental enforcement, utility bill monitoring, and a property-management operation with field staff. Even its "MVP" holds six subsystems. That's too large for one spec, so this document covers slice 1 only; later slices get their own spec, plan, and build cycle.

Everything else in plan.md — property management operations, TNB and water APIs, maintenance tickets, law firm escalation, loyalty programmes, agent behaviour detection — is Phase 2 or later, not designed here.

What slice 1 proves

A Malaysian property owner will create an account, list a real property, pass ownership review, and see it live — and tenants can find it. Nothing else. If owners will not do this, no further slice is worth building.

• An owner completes listing submission without help
• An admin approves or rejects from the panel with a reason the owner can read
• A tenant finds a listing through search and filters, with no account
• No public response ever contains owner contact details or ownership documents

Scope

In scope

• Owner signup and login: a public /owner/sign-up page (Better Auth signUp.email, no invite required) plus a narrow rental endpoint that promotes the new account to a global landlord role — no self-serve signup path exists in the panel today, so this is new work, not reuse
• Create and edit a property: type, address, area, rent, deposit terms, furnishing, house rules, available date, photos
• Ownership declaration checkbox plus proof document upload (utility bill, quit rent, or SPA first page)
• Admin review queue: approve, reject with reason, suspend a live listing, restore a suspended listing
• Public marketplace: browse, filter by area / price / type / furnishing, listing detail page, "Direct from Owner" badge
• Owner contact details never shown publicly. The detail page shows a disabled "Arrange Viewing" button labelled coming soon

Out of scope, by decision

Viewing booking, messaging, offers, tenancy agreements, e-sign, payments, the refundable listing deposit, tenant accounts, ratings, agent behaviour detection, property management operations, utility APIs. Tenants browse without an account in slice 1 — tenant login arrives with slice 2, the first slice that needs it.

Architecture

Languages

English only at launch, wired through the same Paraglide setup as other apps, so Malay and Chinese can be added later without rework. Owner-written descriptions stay free text in whatever language the owner types.

Data model

Four tables, created by GORM AutoMigrate in a new migrator_rental.go.

Owner profile

No table — the existing users record is enough for slice 1

Admin actions

No table — review fields live on the listing; the shared audit infrastructure records who did what

Listing state machine

stateDiagram-v2
    [*] --> draft
    draft --> pending_review
    pending_review --> live
    pending_review --> rejected
    rejected --> pending_review : owner edits
    live --> withdrawn
    live --> suspended : admin action
    suspended --> live : admin restore
    withdrawn --> [*]
    

withdrawn and suspended are not both dead ends: suspension is reversible straight back to live by an admin. Once a listing reaches withdrawn, the owner may create a brand-new listing (starting again at draft) for the same property (see §5's cardinality rule). This is the only real logic in slice 1 — covered by table-driven tests over every valid and invalid transition, including the restore and the post-withdrawal new listing.

Flows

A — Owner lists a property

1. Sign up

   New landlord signs up at a public /owner/sign-up page (Better Auth signUp.email, no invite needed); a narrow rental endpoint promotes the account to the global landlord role.

2. Fill the property form

   At /owner/properties/new.

3. Upload photos

   Public storage prefix, via a rental-owned upload endpoint calling the shared storage interface directly — not the org-scoped shared attachments flow, since a landlord has no organization.

4. Upload ownership proof

   Private prefix, via a rental-owned upload endpoint; the storage layer never returns a public URL for it.

5. Declare ownership

   Ticks the ownership declaration; declared_owner_at and declared_ip are (re-)stamped on this submission.

6. Submit

   Status becomes pending_review.

7. Admin discovers it

   By visiting the filtered review queue — no notification is sent in slice 1 (the shared notifications module requires an organization, which a landlord doesn't have).

8. Approve or reject

   Admin approves — status live, slug generated, owner emailed. Or rejects — review_reason written, owner sees it, fixes, resubmits (re-stamping the declaration).

B — Public browse, no login

GET /api/public/rental/listings?area=&min_rent=&max_rent=&type=&furnishing=&page=
GET /api/public/rental/listings/{slug}

Returns live listings only. The response carries no owner name, phone, email, exact address_line, or proof document — ever (only area/city/postcode, so a tenant can't show up unannounced before a viewing is arranged). Astro renders these server-side at /property/{slug} with cache headers so Cloudflare serves repeat traffic.

C — Admin review

/admin/rental/listings?status=pending_review in the panel, using the existing review-queue table patterns. Approve, reject with reason, suspend a live listing, or restore a suspended listing back to live. Ownership proofs are viewed by streaming through an authenticated admin-only endpoint — never a public or signed URL. If another rental_properties row shares the same normalized address, the review screen shows a plain warning banner (a read-time query, no new schema or notification).

Two boundaries that matter

Storage separation

Different prefixes, different access paths, never mixed.

Authorization

internal/api/http/middleware/better_auth_rbac.go's RequireOrgRole is organization-scoped and requires an organization ID in context. A B2C landlord has no organization, so rental must not use it.

Error handling

Testing

Delivery order

Each step ends with something observable. Backend through step 5 first means frontend work is never blocked on API shape.

1. Backend skeleton

   Module skeleton, config profile, migrations → tables exist, health check passes.

2. Property + listing CRUD

   Owner CRUD with authorization tests → API works via curl.

3. Upload

   Photo and proof upload, both storage prefixes → files land in the right buckets.

4. Lifecycle

   Submit, state machine, admin approve, reject, suspend, and restore → full lifecycle via API.

5. Public read API

   Public read API and golden test → live listings queryable, nothing leaks.

6. Owner UI

   Panel /owner/* routes and layout → owner lists a property in a browser.

7. Admin UI

   Panel /admin/rental/* review queue → admin approves in a browser.

8. Public site

   Astro search, filters, detail page, SEO tags → tenants can find listings.

9. E2E + deploy

   Playwright happy path, deploy both frontends.

Legal note

The platform is a tool provider, not a real estate agent and not a legal advisor. Terms must state that listings are for property owners listing their own properties. This matters more from slice 3 onward, when the system generates tenancy agreements, but the positioning belongs in the terms from launch.