ADR-0006: Tenant Administration as Store-Ready PWA

Status: Accepted
Date: 2025-09-08
Deciders: Product, Engineering
Related: PRP Addendum 2025-09-08 (Tenant Admin PWA)

Context

The original PRP envisioned tenant administration via a Filament panel. We want a dedicated, installable experience for tenant admins and the ability to distribute through Google Play and Apple App Store. We also want a cleaner API-first separation and mobile-friendly capabilities (push, offline, background sync).

Decision

Implement a separate React/Vite PWA for tenant admins ("Tenant Admin PWA").
Distribute via:
- Android: Trusted Web Activity (TWA), bound to admin.<platform-domain> via Digital Asset Links, or Capacitor when native plugins are necessary.
- iOS: Capacitor wrapper for App Store distribution.
Keep Super Admin as a Filament 4 web panel only.
Expose all tenant features through /api/v1/tenant/*, authenticated using Authorization Code + PKCE and refresh tokens. Tokens include tenant_id and roles. Enforce tenant isolation with global scopes and policies.
Billing: Packages & add-ons (legacy credits removed).

Consequences

Filament resources for tenant admins in PRP are deprecated as implementation guidance. They remain as field/validation reference only.
Backend must provide complete API coverage for tenant use cases and implement token-based auth with refresh and rotation.
Mobile packaging CI is added (TWA/Capacitor), including assetlinks.json, fastlane lanes, and privacy manifests.

Implementation Notes

Repo layout additions:
- apps/admin-pwa (React/Vite)
- packages/mobile (Capacitor + TWA wrappers)
- Existing apps/guest-pwa and Filament-based Super Admin remain.
Security:
- PKCE, refresh tokens, and secure storage. Rate limits per tenant and device. Audit logs for sensitive actions and impersonation.
Offline:
- Service Worker with background sync; conflict resolution with ETag/If-Match.

Alternatives Considered

Keep tenant admin in Filament: faster initially but not store-distributable and poorer mobile UX.
Native apps: higher cost and longer timeline; PWA + thin wrappers meet requirements.

2.1 KiB Raw Blame History