fotospiel-app/docs/process/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 Paddle 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 Paddle 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 Paddle (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.
• Welcome Landing, Packages, Summary und Event-Setup sind zweisprachig (DE/EN) via react-i18next; LanguageSwitcher im Dashboard & Welcome-Layout steuert die Locale.

Status — verbleibende Arbeiten

• Paddle-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.