ADR-0063: The rental landlord/tenant portal is a standalone SolidStart app

Status

Accepted (2026-09-10); corrected 2026-09-10 after design review
Update 2026-10-12: hosts moved to landlord.rumah.homes / rent.rumah.homes; the rental pair’s session cookie is .rumah.homes via bun-api.rumah.homes. See ADR-0073 and AGENTS.md §8.
Update 2026-10-14: the same Worker also serves tenant.rumah.homes. /tenant/* lives there and /landlord/* on landlord.rumah.homes; src/middleware.ts and AppRoot redirect a workspace path to its own host. The marketplace links to the tenant host (TENANT_PORTAL_URL). See AGENTS.md §8.

Tags

rental, solidstart, architecture, product-boundary, deployment, cloudflare, better-auth, naming, adr-0054, adr-0055, adr-0056

Decision

The authenticated rental portal — the landlord workspace and the tenant portal — moves out of frontend/solidstart/apps/panel into its own independently deployed SolidStart application at frontend/solidstart/apps/rental. Panel keeps exactly one rental surface: the platform-admin listing review at /admin/rental/listings, which calls /api/rental/admin/* like any other client. It owns a self-contained features/rental-admin/ — the six admin functions plus proofStreamUrl and rentalQueryKeys.adminProof, and ProofViewer, whose only production caller is that screen — and shares no rental package with the portal. The portal’s route strings and code identifiers rename from /owner/* to /landlord/*, via a classified inventory rather than a mechanical replace: org-owner semantics, UI text, and wire and column names (owner_user_id) are preserved, as are i18n key names. No backend implementation change and no database or Better Auth schema change. Origin and environment configuration does change — the portal origin must be admitted by ALLOWED_ORIGINS and by Better Auth’s trusted origins, and the portal carries its own VITE_BETTER_AUTH_URL, VITE_API_URL and VITE_CALLBACK_URL. The Go module’s existing three-way split (/api/public/rental/* anonymous, /api/rental/* session, /api/rental/admin/* admin-gated) already expresses the boundary correctly and is not touched.

Why

Rental and the platform panel are two products sold separately. Today a rental customer downloads a bundle containing the platform’s HR, fieldforce, digital-worker and AI admin code, and a panel deploy can break a paying rental customer. The existing code already treats them as separate; only the folder layout disagrees:
  • Imports originating inside the rental tree reach exactly five panel-local roots (~/paraglide/messages, ~/paraglide/runtime, ~/lib/api/error-handlers, ~/lib/create-reactive-translator, ~/app). None is directly an org, fieldforce, AI or admin module — though ~/lib/api/error-handlers reaches Panel’s AI feature transitively until that coupling is cut. References in the other direction — Panel files that mention rental routes — are a separate, smaller set, inventoried during the rename.
  • apps/panel/src/app.tsx carries three branches whose only purpose is to escape the panel: isOwnerRoute() and isTenantSignUpRoute() bypass AuthGate; isTenantRoute() bypasses MainLayout and the org chrome.
  • routes/api/rental/[...path].ts states it outright: “rental is orgless — no x-organization-id injection.”
  • 838 of the panel’s 1,845 i18n keys (45%) are rental_*.
ADR-0056 already rejected serving a rental surface from the panel, on the grounds that “the panel is an authenticated admin surface.” That reasoning applies to the portal too. This is the third independently deployed frontend product boundary, after ADR-0054 (quiz) and ADR-0056 (public marketplace). Central administration is unaffected because it is achieved at the backend — one Go API, one Better Auth, one database (ADR-0055). The panel is simply another client of the admin route group. Splitting the frontend does not touch that.

On the /owner/* → /landlord/* rename

The collision with org-scoped owner dissolves by itself once the apps are separate: role === 'owner' lives only in the panel, /owner/* only in the rental app. The reason to rename anyway is that the frontend and the backend speak different languages for the same actor — /owner/dashboard calls GET /landlord/dashboard-summary, OwnerRoute calls checkLandlordAccess(), /owner/payments calls GET /landlord/review-queue. require_landlord.go:10 documents the mismatch in one sentence: “RequireLandlord gates every rental owner route on the global landlord role.” CONTEXT.md’s Landlord entry is amended to extend landlord from the role token to route and code identifiers, while keeping owner for rental_properties.owner_user_id and for product copy. tenant is deliberately not renamed. It is the word in the tenancy agreement — legal domain vocabulary — and its clash with org multi-tenancy also dissolves with the split (routes/api/tenant/ stays in the panel, routes/tenant/ moves to the portal).

Considered options

  • Extract a shared packages/rental-core for DTOs and API clients — rejected on sizing, not on principle. A versioned package can be published without forcing a consumer redeploy; the objection is that the ceremony exceeds the contents here. The eight items (six admin functions plus proofStreamUrl and rentalQueryKeys.adminProof) are the panel-owned admin surface, not a surface both apps use — proof access is admin-only and the portal never calls them. What the two apps genuinely share is narrower: ListingStatus values and some RentalListing field names, and they read different subsets of that type, so one shared type tends toward the union of both. The package would also prevent frontend-vs-frontend drift, for which there is no demonstrated instance here — not the same as proving it cannot occur — while doing nothing about frontend-vs-Go drift, which is the acknowledged risk; these types are hand-written, not generated. ADR-0052’s contract-drift tests were reverted in PR #75 for the same reason. Worth revisiting if the shared surface grows substantially.
  • Split the Go rental module into a second service — rejected. It would share one database (a distributed monolith), duplicate Better Auth and JWKS handling, and wrap three admin handlers in a deployment unit. Backend topology is invisible to customers and does not affect selling two products.
  • Leave the portal in the panel and accept the coupling — rejected. It is the status quo the three escape hatches in app.tsx are already working around.

Consequences

  • rental becomes the fourth SolidStart app listed in this workspace, alongside panel, cycle-planner and clawui. .github/workflows/frontend-deploy.yml is already per-app with path filters, so this is a config addition rather than new machinery: a rental dispatch option, a paths filter with a matching detect-changes output, and an isolated deploy job.
  • Deployment independence is a pipeline-policy property, not an import-graph property. App-only changes trigger only their own app. Changes to packages/**, the lockfile, or shared workflow config trigger every app whose filter opts into them — the portal’s filter includes packages/**, since it depends on packages/ui for RentalLayout, RentalThemeBoundary and rentalTheme.
  • ADR-0056’s “Arrange Viewing” handoff changes target. The marketplace links to ${PANEL_URL}/tenant/book/{slug} (apps/rental/src/pages/property/[slug].astro). That route moves to the portal, so the variable is repointed to the portal’s host and renamed. ADR-0056 is amended. The marketplace’s own host is unchanged.
  • The portal must sit under the same registrable domain as the Better Auth session cookie. The browser has to send that cookie to the portal host — both for authClient and so the portal’s own same-origin SSR proxy has a cookie to forward. Configuration now places the rental pair’s cookie on .rumah.homes (the .rumah.homes entry of COOKIE_DOMAIN in backend/bun/fly.toml, served by bun-api.rumah.homes), so the portal sits at a sibling host under that domain (landlord.rumah.homes). A gremlin.my migration is deferred and out of scope; a separate registrable domain is out of scope, since SameSite=None and CORS govern cross-site sending of an in-scope cookie, not cookie scope itself. This is an open risk closed by an HTTPS second-host spike, not a confirmation.
  • The “Arrange Viewing” link is a top-level cross-origin navigation. It carries no session and therefore places no registrable-domain requirement of its own on the portal.
  • packages/core and packages/ui now serve four apps; a breaking change there hits both products at once.
  • Local development of the marketplace → portal → admin-review path now needs two SolidStart dev servers running, not one, and CI must start and validate both.
  • Four pre-existing defects surfaced during the analysis and are fixed as part of the work: features/rental/api/index.ts is dead code shadowed by api.ts (bare api imports resolve to the file, not the directory); /sign-in is a phantom route that works only because the panel’s global AuthGate intercepts unauthenticated paths; lib/api/error-handlers.ts calls routeAIError(), making rental’s entire API layer depend on the panel’s AI feature; and routes/owner/OwnerRoute.tsx:44 navigates to a bare /sign-in carrying no return path, which only becomes visible once sign-in is a real route.
  • The root vitest.config.ts hardcodes '~' → apps/panel/src and includes only apps/panel/src/**, so the portal’s tests would not be collected after the move. The fix is explicitly enumerated projects — shared-packages, panel, then rental — each app project owning its alias, setup and app-only include across both .ts and .tsx, with shared-package tests collected exactly once. A glob such as test.projects: ['apps/*'] is not sufficient: it drops shared-package coverage and points at apps that have no Vitest config. Acceptance compares collected test file identities before and after, not a fixed total.
  • The portal’s three auth routes (sign-in, /landlord/sign-up, /tenant/sign-up) share one AuthLayout split panel. Its layout contract, copy and asset brief live in D4d of the design, which is self-contained: the HTML prototype it was transcribed from is untracked by repo policy and is deleted once this work lands, so nothing may refer back to it. This is presentation only: no route is merged or deleted, so the landlord promote step and the tenant booking-intent round-trip are untouched. Three prototype affordances are deliberately not shipped — the sign-in “Preview account” role selector (a real sign-in must not let a visitor declare their identity), the demo disclaimer, and the demo-consent checkbox. See D4d in the design.

Design

docs/superpowers/specs/2026-09-10-rental-portal-app-split-design.md