Sync engage-native docs with initial codebase push

repositories/d-sports-engage-native.mdx

@@ -6,51 +6,63 @@ icon: "smartphone"
 
 ## Overview
 
-**d-sports-engage-native** (package name: `engage-native`) is the native mobile app for D-Sports. It mirrors the core PWA experience on iOS and Android: wallet, shop, leaderboard, locker room, and profile.
+**d-sports-engage-native** (package name: `engage-native`, version **1.17.3**) is the native mobile app for D-Sports. It mirrors the core PWA experience on iOS and Android: wallet, shop, leaderboard, locker room, and profile.
 
-- **Run:** `bunx expo start` or `bun run start` — then press `a` for Android or `i` for iOS, or scan the QR code with Expo Go.
+- **Run:** `bunx expo start` — then press `a` for Android, `i` for iOS, or scan the QR code with Expo Go.
 
 ## Tech stack
 
-| Category   | Technology                |
-| ---------- | ------------------------- |
-| Framework  | Expo 54, React Native 0.81, React 19 |
-| Auth       | Clerk (Expo)              |
-| Payments   | RevenueCat (react-native-purchases) |
-| Web3       | Thirdweb                  |
-| State      | Zustand                   |
-| Storage    | MMKV                      |
-| UI         | Lucide React Native       |
-| Navigation | Expo Router               |
-| Package    | Bun                       |
+| Category      | Technology                                    |
+| ------------- | --------------------------------------------- |
+| Framework     | Expo 54, React Native 0.81.5, React 19.1     |
+| Auth          | Clerk (`@clerk/clerk-expo`)                   |
+| Payments      | RevenueCat (`react-native-purchases`)         |
+| Web3          | Thirdweb SDK                                  |
+| State         | Zustand 5 + MMKV persistence                 |
+| UI            | Lucide React Native, Expo Blur               |
+| Navigation    | Expo Router 6 (file-based, typed routes)      |
+| Push          | OneSignal (`react-native-onesignal`)          |
+| Analytics     | Sentry (`@sentry/react-native`)              |
+| Backend       | Supabase JS (client-side), D-Sports API       |
+| Package       | Bun                                           |
 
 ## Features
 
-- **Wallet** — Tokens, holdings, pack opening, crypto checkout (via PWA backend)
-- **Shop** — Collectibles, cart, coin bundles, checkout
-- **Leaderboard** — Rankings and filters
-- **Locker room** — Social feed and engagement
-- **Profile** — User profile and settings
-- **Theme** — Dark/light mode (default dark)
-
-## What changed since last docs sync
-
-- Team-aware experiences were expanded to align with backend team/favorites behavior.
-- Quest and rewards surfaces were updated to support per-team progression and pass-aware eligibility.
-- Pack opening and odds disclosure UX were upgraded with safer interactions and clearer status/error handling.
-- Settings and account flows were expanded, including in-app account deletion and richer support/data controls.
+- **Wallet** — token balances, holdings, pack opening, crypto checkout (Arbitrum/Ethereum/Polygon via Thirdweb)
+- **Shop** — collectibles, cart, coin bundles, 3D model viewer (Filament), crypto and fiat checkout
+- **Leaderboard** — team-scoped rankings with filters and detail modals
+- **Locker room** — social feed, daily pick-em game, guess-the-player game, daily spin wheel, quests, and explore fans/teams
+- **Profile** — achievements, milestone avatars, follow lists, points history, and badges
+- **Settings** — account, appearance, accessibility, audio, notifications, data, privacy, legal, support, changelog, and in-app account deletion
+- **Notifications** — push notifications via OneSignal with EAS OTA update support
+- **Theme** — dark/light mode (default dark), blur effects via `expo-blur`
+
+## Environment variables
+
+You configure the app with `EXPO_PUBLIC_*` keys in a `.env` file at the repo root. Required variables:
+
+| Variable | Purpose |
+| -------- | ------- |
+| `EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY` | Clerk authentication |
+| `EXPO_PUBLIC_API_URL` | D-Sports API base URL |
+| `EXPO_PUBLIC_TW_CLIENT_ID` | Thirdweb client ID |
+| `EXPO_PUBLIC_REVENUECAT_API_KEY` | RevenueCat API key |
+| `EXPO_PUBLIC_REVENUECAT_APPSTORE_ID` | RevenueCat App Store ID |
+| `EXPO_PUBLIC_REVENUECAT_ENTITLEMENT` | RevenueCat entitlement identifier |
+| `EXPO_PUBLIC_SUPABASE_URL` | Supabase project URL |
+| `EXPO_PUBLIC_SUPABASE_KEY` | Supabase publishable key |
 
 ## Backend integration surfaces
 
 - Primary API source: `d-sports-api` under `/api/*`.
-- Native app consumes team, league, quest, reward, wallet, commerce, and social endpoints.
-- Retry/caching logic and auth token injection are centralized in app API client modules.
+- Native app consumes team, league, quest, reward, wallet, commerce, social, and locker room endpoints.
+- Retry/caching logic and auth token injection are centralized in `lib/api/client.ts` with MMKV cache fallback via `lib/api/cache.ts`.
 
 ## Quest and pass UX integration
 
-- Quest UI now reflects team-scoped eligibility and pass-gated progression where applicable.
+- Quest UI reflects team-scoped eligibility and pass-gated progression where applicable.
 - Reward presentation differentiates free/unpaid states and claimability.
-- Native progression state is expected to mirror backend eligibility and completion semantics.
+- Native progression state mirrors backend eligibility and completion semantics.
 
 ## Team-aware experiences
 
@@ -65,11 +77,25 @@ icon: "smartphone"
 ## Getting started
 
 1. Clone the repository and run `bun install`.
-2. Configure environment (Clerk, RevenueCat, Thirdweb, API base URL) per repo README.
+2. Copy `.env.example` to `.env` and fill in the environment variables listed above.
 3. Run `bunx expo start`.
 4. For development builds: `bun run build:dev` (EAS) or run with Expo dev client.
 
-The app targets both native and web (responsive) and uses the same backend (d-sports-api) as the PWA for API and checkout flows.
+The app targets both native and web (responsive) and uses the same backend (`d-sports-api`) as the PWA for API and checkout flows.
+
+## EAS build profiles
+
+The project uses EAS Build with profiles defined in `eas.json`:
+
+| Profile | Description |
+| ------- | ----------- |
+| `development` | Dev client build with simulator support |
+| `development-device` | Dev client build for physical devices |
+| `preview` | Internal distribution (APK for Android) |
+| `staging` | Auto-increment version, staging channel |
+| `production` | Auto-increment version, production channel |
+
+A GitHub Actions workflow (`eas-update.yml`) publishes OTA updates to `develop` and `main` branches on push.
 
 ## Deep dives
 

repositories/d-sports-engage-native/architecture.mdx

@@ -7,24 +7,43 @@ description: "Architecture overview for d-sports-engage-native application layer
 
 The native app is structured around Expo Router screens, feature-oriented components, shared hooks, and API modules.
 
-- Routing: `app/*` with grouped routes for tabs/auth/onboarding/settings.
-- Feature logic: extracted hooks for wallet, shop, locker room, and settings.
-- Shared contexts: user, collectibles, accessibility, and UI visibility/state controls.
+- **Routing:** `app/*` with grouped routes — `(tabs)` for main navigation, `(auth)` for login/signup, `(onboarding)` for new users, and `settings/` for configuration pages.
+- **Feature logic:** extracted hooks for wallet (`use-wallet-screen.ts`), shop (`use-shop-screen.ts`), feed (`use-feed-section.ts`), and settings (`use-user-settings.ts`).
+- **Shared contexts:** `UserContext` (auth/profile), `CollectiblesContext` (packs/items), `AccessibilityContext`, `NavBarVisibilityContext`, and `CreateActionContext`.
+
+## Screen pattern
+
+Screen files contain **only imports and JSX**. All state, effects, and handlers live in dedicated hooks:
+
+- `hooks/use-wallet-screen.ts` — wallet/token fetch, PIN verification, transaction handlers
+- `hooks/use-shop-screen.ts` — cart state, product queries, carousel auto-scroll, checkout logic
+- `hooks/use-feed-section.ts` — social feed data and interactions
+
+Sub-components are extracted into feature directories (`components/wallet/`, `components/shop/`, `components/locker-room/`, `components/profile/`) with barrel exports via `index.ts`.
 
 ## State and context boundaries
 
 - Local/ephemeral UI state lives near feature hooks and components.
-- Cross-screen state is managed with context providers and persisted storage where required.
-- User/session-sensitive state is coordinated with backend auth and profile sync endpoints.
+- Cross-screen state is managed with context providers — Zustand store (`services/store.ts`) persisted via MMKV (`services/storage.ts`).
+- User/session-sensitive state is coordinated with Clerk auth and backend profile sync endpoints.
 
 ## API client and retry behavior
 
-- All network calls route through `lib/api/*` modules.
-- Client wrappers handle auth token propagation, error normalization, and retry strategy.
-- Quest/reward/team flows should consume backend eligibility as source of truth.
+- All network calls route through `lib/api/*` domain modules (wallet, shop, user, quests, leaderboard, locker room, teams, collectibles, checkout, games).
+- `lib/api/client.ts` handles auth token injection and error normalization.
+- `lib/api/cache.ts` provides MMKV cache-first fetching via `fetchWithCache()`.
+- Quest/reward/team flows consume backend eligibility as source of truth.
+
+## Theme system
+
+- `theme/colors.ts` defines brand colors (Gold `#F5C842`, Royal Blue `#4169E1`) and dark/light palettes.
+- `components/theme-provider.tsx` provides `useTheme()` hook with `resolvedTheme`.
+- `expo-blur` is used for blur effects in UI overlays.
+- Default theme is dark mode with base background `#0a0e1a`.
 
 ## Platform-specific behavior
 
 - iOS/Android platform differences are handled in native-specific components and runtime checks.
-- Web-target support exists but mobile behavior is primary for interaction and performance design.
-- Haptics, modal controls, and animation handling are implemented with platform-safe fallbacks.
+- Web-target support exists with responsive `maxWidth: 480px` container (`components/layout/AppScreen.tsx`) and hover states (`components/ui/WebHoverWrapper.tsx`).
+- Haptics (`expo-haptics`), modal controls, and animations (React Native Reanimated) are implemented with platform-safe fallbacks.
+- Path alias `@/*` maps to the project root for clean imports.

repositories/d-sports-engage-native/feature-mapping.mdx

@@ -11,6 +11,8 @@ description: "Native feature coverage and parity mapping against backend/PWA beh
 
 - Wallet screens consume balances, token data, and secure key/pin flows from backend APIs.
 - Pack browsing, purchase, and open flows use backend-driven states and inventory refresh behavior.
+- Crypto checkout supports Arbitrum (default), Ethereum, and Polygon chains via Thirdweb SDK.
+- Fiat payments are handled through RevenueCat (Apple IAP on iOS, Google Play on Android, Stripe on web).
 - Odds-disclosure surfaces read backend-provided probability payloads.
 
 ## Quest, rewards, and pass surfaces
@@ -19,8 +21,41 @@ description: "Native feature coverage and parity mapping against backend/PWA beh
 - Reward states and claim flows follow backend quest/reward APIs.
 - Global pass and event pass effects are reflected in native quest visibility/completion UX.
 
+## Locker room and games
+
+- Social feed with post creation, comments, and user interaction.
+- **Daily pick-em game** — users predict outcomes with backend-validated results.
+- **Guess the player game** — interactive player identification challenge.
+- **Daily spin wheel** — daily reward mechanic with animated wheel.
+- **Featured games carousel** — rotates available games for discovery.
+- Explore fans and teams discovery surfaces.
+- User profile hover cards and user stats display.
+
 ## Team and leaderboard integration
 
 - Teams and leagues metadata are consumed from backend `/api/teams` and `/api/leagues`.
 - Leaderboard displays and team-scoped ranking views align with backend leaderboard contracts.
 - Favorite-team interactions influence quest and leaderboard context where backend eligibility requires it.
+- Team detail modals show team info, branding, and related content.
+
+## Profile and achievements
+
+- Milestone avatars with progressive unlock tiers.
+- Achievement cards and chips with detail modals.
+- Profile followers/following lists with follow actions.
+- Points history tracking and display.
+- Cached badge images with local asset mapping.
+
+## Notifications
+
+- Push notifications via OneSignal (`react-native-onesignal`).
+- In-app notification screen at `app/notifications.tsx`.
+- Notification settings configurable in settings.
+
+## Settings
+
+- Account management including in-app account deletion.
+- Appearance, accessibility, audio, notification, data, privacy, legal, room, and support settings.
+- In-app changelog viewer.
+- Help center with FAQ and contact support form.
+- Report-a-problem flow with structured feedback.