gw/mobile.md

You are working on an existing SvelteKit codebase with separate `backend` and `frontend` folders.

Assume the frontend is a SvelteKit application.

Your task is to decouple all mobile-specific experience logic from the main frontend and introduce a first-class mobile architecture for two distinct app experiences:

1. Admin mobile experience
2. Member mobile experience

These should feel like a polished mobile app experience similar in quality and intentionality to a React Expo app, but built fully within this SvelteKit project.

Critical objective
The mobile experience must not just be a responsive version of the desktop site. Mobile users should be routed into dedicated, optimised mobile layouts and flows so they receive a purpose-built experience rather than squeezed desktop screens.

Read first
- Read `THEME.md` first and use it as the source of truth for visual language, spacing, tone, interaction style, and component feel.
- Update `THEME.md` to explicitly document the new mobile design language and mobile UX rules.
- Preserve the existing bottom bar navigation pattern. This is a key product feature and must remain, while being refined for mobile.

High-level goals
- Decouple all mobile logic into its own clear architecture.
- Create shared mobile foundations used by both Admin and Member mobile apps.
- Ensure Admin and Member mobile experiences share the same design language and UX philosophy.
- Keep desktop and tablet experiences stable.
- Implement proper routing so mobile users are served dedicated mobile routes/layouts instead of generic responsive pages.

Core requirements

1. Create a dedicated mobile architecture
Refactor the frontend so mobile concerns are separated into their own folder structure instead of being scattered across desktop pages and shared components.

Target outcome:
- shared mobile UI system
- shared mobile layout shell
- shared bottom navigation system
- shared mobile interaction primitives
- dedicated Admin mobile routes
- dedicated Member mobile routes
- explicit desktop vs mobile route separation

Suggested structure
Refine if necessary, but preserve the intent:

frontend/
  src/
    lib/
      mobile/
        components/
        layouts/
        navigation/
        stores/
        utils/
        styles/
        guards/
    routes/
      (desktop)/
        ...
      (mobile)/
        admin/
          ...
        members/
          ...

Or an equivalent structure that clearly separates:
- mobile shared system
- mobile admin experience
- mobile member experience
- desktop/default experience

2. Implement dedicated mobile route handling in SvelteKit
This is required.

You must introduce a routing strategy that ensures mobile users are directed into purpose-built mobile routes rather than receiving the responsive desktop experience.

Requirements:
- Determine a maintainable SvelteKit approach for routing users to mobile experiences
- Use a clean and explicit strategy, for example:
  - route groups
  - layout-level guards
  - hooks
  - server/client detection
  - redirects based on device class where appropriate
- Avoid fragile UA logic where possible, but pragmatic device detection is acceptable if implemented cleanly
- Do not create redirect loops
- Do not break deep links
- Preserve auth, permissions, and route protection
- Ensure Admin mobile users land in Admin mobile flows
- Ensure Member mobile users land in Member mobile flows
- Ensure desktop users remain on desktop routes
- Make this maintainable and easy to reason about

Expected behaviour:
- Mobile users should receive mobile-specific routes/layouts/screens
- Desktop users should receive desktop-specific routes/layouts/screens
- Shared business logic should remain reusable where appropriate
- End users should not accidentally fall back into desktop responsive pages unless explicitly intended

3. Create a mobile app shell
Build a mobile shell that feels app-like rather than website-like.

Requirements:
- fixed or sticky top area where appropriate
- preserved bottom tab bar navigation
- safe spacing for thumb reach and small screens
- proper scrolling regions
- smooth transitions between sections
- sticky action areas where useful
- consistent mobile headers, titles, back navigation, and action buttons
- support for common in-app patterns like stacked navigation, slide-up panels, and compact action menus

4. Shared design language between Admin and Member mobile
Admin and Member mobile areas should feel like part of the same product family.

Ensure:
- same spacing scale
- same mobile card styling
- same navigation treatment
- same touch target sizing
- same motion philosophy
- same bottom nav design system
- same typography rules
- same form and list behaviour
- same empty/loading/error state patterns

But separate:
- route groups
- permissions
- business logic
- data flows
- feature sets

5. Mobile-first component system
Create or refactor reusable mobile components so logic is not duplicated across Admin and Member experiences.

Examples:
- `MobileAppShell.svelte`
- `MobilePageShell.svelte`
- `MobileHeader.svelte`
- `MobileSection.svelte`
- `MobileCard.svelte`
- `MobileListItem.svelte`
- `MobileBottomNav.svelte`
- `MobileActionBar.svelte`
- `MobileSearchBar.svelte`
- `MobileFilterSheet.svelte`
- `MobileTabs.svelte`
- `MobileStatCard.svelte`
- `MobileFormField.svelte`
- `MobileEmptyState.svelte`

Use names that fit the project, but the system should be clearly structured and reusable.

6. Route strategy for Admin and Members
Introduce a clear, maintainable routing approach for mobile.

Need:
- dedicated Admin mobile routes
- dedicated Member mobile routes
- shared layout wrappers where sensible
- clear conventions for naming and extending routes

Examples:
- `/m/admin/dashboard`
- `/m/admin/bookings`
- `/m/admin/customers`
- `/m/members/home`
- `/m/members/bookings`
- `/m/members/profile`

Desktop equivalents should remain in their own route structure.

You may adapt to the project’s existing route conventions, but the separation must be obvious, scalable, and easy for future developers to follow.

7. UX expectations
The mobile UX should feel premium, dense, fast, and intentional.

It should:
- feel native-app inspired
- prioritise one-handed use
- avoid crammed desktop patterns squeezed onto small screens
- use bottom navigation elegantly
- support quick scanning of bookings, schedules, profiles, alerts, and actions
- reduce modal overload where possible
- prefer slide-up panels / sheets / stacked views where appropriate
- make forms usable on mobile without frustration

8. Keep desktop logic stable
Do not break or regress desktop/tablet experiences.
Refactor carefully so mobile-specific logic is isolated without causing duplication or regressions in the main frontend.

9. Update THEME.md
Update `THEME.md` to include a substantial new section for mobile design language.

This new section must define:
- mobile philosophy
- mobile vs desktop experience rules
- bottom navigation principles
- touch target minimums
- spacing and rhythm for small screens
- mobile card/list patterns
- mobile form behaviour
- hierarchy of headers and page titles
- motion and transitions for mobile
- how Admin and Member mobile experiences stay visually aligned
- what should never be done in mobile views

10. Documentation
Document all structural changes clearly.
Update any relevant docs so another developer can understand:
- where mobile code now lives
- how mobile routing works
- how device-based rerouting works
- how shared mobile components should be used
- how Admin and Member mobile experiences differ
- how to extend the mobile shell safely
- how to avoid mixing desktop-only concerns back into mobile components

Implementation standards
- Keep code production-quality, clean, and maintainable.
- Prefer composition over duplication.
- Avoid massive files.
- Extract reusable patterns.
- Keep naming clear and scalable.
- Preserve existing business logic unless a cleaner shared abstraction is necessary.
- Do not leave mobile logic buried inside unrelated desktop components.
- Do not implement this as random CSS media query patches only.
- Make the mobile experience feel like a deliberate application layer.

Technical expectations for SvelteKit
- Use idiomatic SvelteKit patterns
- Be deliberate about where redirects occur:
  - hooks
  - `+layout.server.ts`
  - `+page.server.ts`
  - shared route guards
- Ensure SSR/CSR behaviour is considered
- Ensure hydration does not cause route flicker
- Ensure navigation between mobile routes remains smooth
- Preserve auth/session handling and existing route protections
- Keep deep linking functional
- Prevent infinite redirect edge cases

Deliverables
1. Refactored folder structure for mobile architecture
2. Shared mobile layout/components/navigation primitives
3. Dedicated Admin mobile experience
4. Dedicated Member mobile experience
5. Proper SvelteKit mobile rerouting strategy so end users receive optimised mobile routes
6. Preserved and improved bottom bar navigation
7. Updated `THEME.md` with explicit mobile design language
8. Any additional docs needed to explain the architecture

At the end, provide:
- a summary of what was changed
- the new folder structure
- which files were created
- which files were updated
- how mobile rerouting works
- any migration notes
- follow-up recommendations for improving the mobile UX further