From cf4b26868d2b02fef1366318dd343c3b51bfc5d7 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Sun, 5 Apr 2026 03:48:38 +0000 Subject: [PATCH] docs: sync engage-native docs with initial codebase push (v1.17.3) Generated-By: mintlify-agent --- repositories/d-sports-engage-native.mdx | 90 ++++++++++++------- .../d-sports-engage-native/architecture.mdx | 39 +++++--- .../feature-mapping.mdx | 35 ++++++++ 3 files changed, 122 insertions(+), 42 deletions(-) diff --git a/repositories/d-sports-engage-native.mdx b/repositories/d-sports-engage-native.mdx index e79c1b6..2d04b89 100644 --- a/repositories/d-sports-engage-native.mdx +++ b/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 diff --git a/repositories/d-sports-engage-native/architecture.mdx b/repositories/d-sports-engage-native/architecture.mdx index af786e3..3b47aa1 100644 --- a/repositories/d-sports-engage-native/architecture.mdx +++ b/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. diff --git a/repositories/d-sports-engage-native/feature-mapping.mdx b/repositories/d-sports-engage-native/feature-mapping.mdx index 27fbcd7..17737d3 100644 --- a/repositories/d-sports-engage-native/feature-mapping.mdx +++ b/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.