fotospiel-app/docs/changes/2025-10-10-tenant-admin-onboarding-plan.md

# Tenant Admin PWA — Onboarding + Management Fusion

## Context
- Goal: Merge the immersive onboarding / ordering flow from the legacy Capacitor app with the new `/event-admin` management experience inside Laravel.
- Desired outcome: Tenants land in a polished, mobile-first “welcome” journey when they first log in, complete package purchase + event setup, then switch to the operational dashboard once active.

## TODOs
1. **Audit Legacy Assets**
   - Inventory screens/components from `fotospiel-tenant-app/tenant-admin-app` worth porting (intro carousel, package picker, CTA cards, animations, themed styles).
   - Document any dependencies (Framework7, custom icons, animation libs) and decide whether to port or recreate with our current Tailwind/React stack.

2. **Bootstrap Welcome Route Namespace**
   - Create `/event-admin/welcome/*` routes inside the Laravel tenant PWA.
   - Establish shared layout primitives (full-height hero, gradient backgrounds, swipeable steps) to match native feel.

3. **Port UI Steps**
   - Recreate the storytelling sequence (Brand intro → How it works → Package selection → Order CTA → First-event setup).
   - Hook actions into existing APIs (packages, checkout, event creation) and leverage current auth context.

4. **Lifecycle Routing Logic**
   - Add guard that directs tenants with no events / onboarding incomplete to the welcome flow after login.
   - Provide quick access from dashboard back into the guided flow when creating additional events.

5. **Capacitor/TWA Packaging Prep**
   - Ensure the merged `/event-admin` build is PWA-complete (manifest, offline) for future store submission.
   - Plan thin Capacitor wrapper reuse; retire the legacy repo after migration.

6. **Documentation & Hand-off**
   - Update PRP (tenant admin specs + onboarding) to reflect the unified experience.
   - Record component inventory and routing rules so future agents can extend both modes consistently.

## Component Audit — 2025-10-10

### Legacy Welcome & Story Shell
- **Hero experience**: `App.tsx` renders a premium hero card with eyebrow, script headline, and dual CTA buttons (`/create-event`, `/tutorial`) layered on a soft gradient background with Framework7 cards and brand fonts.
- **Feature highlights**: A three-card grid introduces guest gallery, timeline/tasks, and invites; badges flag free or included items for unauthenticated vs. subscribed tenants.
- **Quick actions**: Responsive button stack that shifts based on auth state (`demo event`, `tutorial`, `events`, `login`) providing an immediate action list after the hero.
- **Credits strip**: `credits-card` combines balance chips, a RevenueCat-aware badge, and CTA to `/credits-store`; replicating this card gives tenants a quick read on package status.

### Monetisation & Ordering
- **IAP store** (`pages/IAPStorePage.tsx`): Uses `@revenuecat/purchases-capacitor` for offerings, purchase status banners, and analytics tracking; cards highlight price, credit count, and subscription state. Needs Stripe/PayPal parity discussion before porting.
- **Credits context** (`contexts/AuthContext.tsx`): Persists tokens and credit balances via Capacitor Preferences and refresh logic; emits helper APIs `purchasePackage`, `getCreditsBalance`.

### Event Creation Wizard
- **Multi-step flow** (`pages/CreateEventWizard.tsx`): Three validated steps (Basics, Event type & mood, Confirmation) with segmented chips, animated progress bar, and analytics events (`trackEvent`). Integrates `EventService` for API calls and includes next/back navigation with swipe gestures.
- **Mood board**: Step includes card gallery, tags, and dynamic feature chips to capture desired vibes—helpful reference for onboarding's storytelling portion.

### Theme & Visual System
- **Design tokens** (`styles/tokens.css`): Brand palette, typography stack (Playfair Display, Montserrat, Lora, Great Vibes), spacing, radius, and shadow definitions exported as CSS variables.
- **Framework7 overrides** (`styles/theme.css`, `styles/fonts.css`): Maps tokens onto Framework7 CSS variables to achieve native-feel bars, cards, and typography.
- **Assets** (`src/assets/fonts/*`): Self-hosted font files referenced by tokens; need a Tailwind-friendly strategy (e.g., CSS `@font-face` via Vite) if we replicate the look.

### Supporting Utilities
- **Services**: `services/AuthService.ts`, `services/EventService.ts`, `services/analytics.ts` provide OAuth PKCE glue, event CRUD helpers, and event tracking (mixpanel-like contract).
- **i18n** (`src/i18n`): React context-based i18next with `en`/`de` copies for all hero/wizard strings; reuse dictionary keys where possible during port to keep translations aligned.

**Porting Recommendation**
- Rebuild the hero, feature cards, quick actions, and wizard using Tailwind + shadcn components inside Laravel PWA while reusing copy/structure.
- Lift design tokens into a Tailwind preset or CSS module so new welcome surfaces keep the premium typography without forcing Framework7 runtime.
- Treat RevenueCat-specific logic as optional: plan abstraction so Stripe/PayPal packages in Laravel can slot in later if we skip native IAPs initially.

## Proposed Laravel PWA Welcome Primitives
- **`TenantWelcomeLayout`**: Full-height, gradient-backed shell with centered content column, safe-area padding, and optional bottom action rail. Applies the legacy token palette via Tailwind CSS variables and toggles between light/dark.
- **`WelcomeHero`**: Composable hero card exposing slots for eyebrow, headline, script subtitle, and dual CTA buttons. Ships with animation hooks (e.g., `framer-motion`/CSS fade) but degrades gracefully.
- **`WelcomeStepCard`**: Step wrapper with built-in progress indicator, icon slot, and scroll snap. Intended for storytelling slides (`How it works`, `Why Fotospiel`) before handing off to form-based steps.
- **`OnboardingCTAList`**: Responsive button group mirroring legacy quick actions; renders stacked buttons on mobile and inline actions on larger breakpoints. Consumes tenant/auth context to toggle copy.
- **`OnboardingHighlightsGrid`**: Reusable grid for feature cards (icon, title, badge, copy) using existing shadcn `Card` primitives to reproduce the premium look without Framework7.
- **`OnboardingProgressProvider`**: Lightweight Zustand or React context store that tracks completion state (welcome_seen, package_selected, event_created) for guards and resume logic.
- **Theming bridge**: Introduce `tenant-admin.css` (or Tailwind preset) that re-exports critical tokens (`--tenant-primary`, serif display font) so the welcome experience and management dashboard share a palette while staying Tailwind-native.

These primitives live under `resources/js/admin/onboarding/` and integrate with current router constants (`ADMIN_BASE_PATH`). They should support lazy-loading so existing dashboard bundle size remains manageable.

## Progress
- **Inline Checkout**: Die Order-Summary-Seite unterstützt jetzt Stripe-Kartenzahlungen (Payment Element) und PayPal (Orders API) direkt aus dem Onboarding heraus. Free-Packages lassen sich ohne Umweg aktivieren.
- Dashboard bewirbt die Welcome Journey (Actions + Hero Card) und leitet Tenants ohne Events weiterhin auf `/event-admin/welcome` um, während Fortschritt persistiert wird.
- Playwright-Skelett `tests/e2e/tenant-onboarding-flow.test.ts` angelegt und via `npm run test:e2e` ausführbar; Tests sind vorerst deaktiviert, bis Seed-Daten + Auth-Helper zur Verfügung stehen.

## Status — verbleibende Arbeiten
- PayPal-Testabdeckung (Playwright/RTL) und Error-UX gehören noch in die Roadmap, ebenso wie End-to-End-Validierung auf Staging.

## Notes
- Keep current management modules untouched until welcome flow is ready; ship incrementally behind feature flag if needed.
- Reuse new API helpers, QueryClient, and constants to avoid divergence between flows.