# 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.