From 8b436733fe5162c0fa3f90c6b90a0acff7f1bf6c Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Thu, 16 Apr 2026 07:51:57 +0000 Subject: [PATCH] docs: sync engage-native docs with Expo 55, RN 0.83, and full feature coverage Generated-By: mintlify-agent --- repositories/d-sports-engage-native.mdx | 83 ++++++++++++------- .../d-sports-engage-native/architecture.mdx | 47 ++++++++--- .../feature-mapping.mdx | 35 +++++++- 3 files changed, 124 insertions(+), 41 deletions(-) diff --git a/repositories/d-sports-engage-native.mdx b/repositories/d-sports-engage-native.mdx index e79c1b6..2b6fb0c 100644 --- a/repositories/d-sports-engage-native.mdx +++ b/repositories/d-sports-engage-native.mdx @@ -1,56 +1,83 @@ --- title: "d-sports-engage-native" -description: "Native iOS and Android app for D-Sports Engage. Expo 54, React Native, Clerk, RevenueCat, Thirdweb." +description: "Native iOS and Android app for D-Sports Engage. Expo 55, React Native 0.83, Clerk, RevenueCat, Thirdweb." 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.18.4**) 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 or `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 55, React Native 0.83, React 19 | +| Auth | Clerk (Expo) | +| Payments | RevenueCat (react-native-purchases) | +| Web3 | Thirdweb | +| State | Zustand + MMKV persistence | +| Push notifications | OneSignal | +| Error tracking | Sentry | +| UI | Lucide React Native | +| Navigation | Expo Router (file-based) | +| Package manager | 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 +- **Shop** — Collectibles, cart, coin bundles, fiat (RevenueCat) and crypto checkout +- **Leaderboard** — Team-scoped rankings and filters +- **Locker room** — Social feed, daily pick-em, spin wheel, and guess-the-player games +- **Profile** — User profile, achievements, milestone avatars, and follow lists +- **Quests** — Team-aware progression with pass-gated eligibility +- **Settings** — Account, appearance, accessibility, notifications, privacy, support, and legal +- **Widgets** — iOS Live Activity and Android home-screen widgets - **Theme** — Dark/light mode (default dark) -## What changed since last docs sync +## Environment variables -- 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. +The app uses `EXPO_PUBLIC_*` keys at runtime. You need to configure these in a `.env` file: + +| Variable | Purpose | +| -------- | ------- | +| `EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY` | Clerk authentication | +| `EXPO_PUBLIC_API_URL` | Backend API base URL (`https://api.d-sports.org`) | +| `EXPO_PUBLIC_TW_CLIENT_ID` | Thirdweb client ID for Web3 | +| `EXPO_PUBLIC_REVENUECAT_API_KEY` | RevenueCat API key | +| `EXPO_PUBLIC_REVENUECAT_APPSTORE_ID` | RevenueCat App Store ID | +| `EXPO_PUBLIC_REVENUECAT_ENTITLEMENT` | RevenueCat entitlement name | +| `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. +- Retry/caching logic and auth token injection are centralized in `lib/api/client.ts`. +- Domain-specific API modules: `wallet-api.ts`, `shop-api.ts`, `user-api.ts`, `quests-api.ts`, `leaderboard-api.ts`, `locker-room-api.ts`, `teams-api.ts`, `collectibles-api.ts`, `checkout-api.ts`. + +## EAS build profiles + +The app uses [EAS Build](https://docs.expo.dev/build/introduction/) with these profiles defined in `eas.json`: + +| Profile | Channel | Notes | +| ------- | ------- | ----- | +| `development` | `development` | Dev client, internal distribution, iOS simulator | +| `development-device` | `development` | Dev client on physical devices | +| `preview` | `preview` | Internal distribution, Android APK | +| `staging` | `staging` | Auto-increment version | +| `production` | `production` | Auto-increment, auto-submit to stores | + +Run builds with `bun run build:dev`, `bun run build:preview`, or `bun run build:prod`. ## 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,9 +92,9 @@ 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. +4. For development builds: `bun run build:dev` (EAS) or run locally with `expo run:ios` / `expo run:android`. The app targets both native and web (responsive) and uses the same backend (d-sports-api) as the PWA for API and checkout flows. diff --git a/repositories/d-sports-engage-native/architecture.mdx b/repositories/d-sports-engage-native/architecture.mdx index af786e3..9875464 100644 --- a/repositories/d-sports-engage-native/architecture.mdx +++ b/repositories/d-sports-engage-native/architecture.mdx @@ -7,24 +7,51 @@ 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 nested settings pages. +- **Feature logic:** Screen files contain only imports and JSX. All state, effects, and handlers live in dedicated hooks (e.g., `hooks/use-wallet-screen.ts`, `hooks/use-shop-screen.ts`). +- **Shared contexts:** `UserContext` (auth/profile), `CollectiblesContext` (owned packs/items), `NavBarVisibilityContext` (scroll-based nav hide/show), `CreateActionContext` (FAB/action modal state), and `AccessibilityContext`. + +## Tab bar + +The tab bar has platform-specific implementations: + +- **iOS:** `app/(tabs)/_layout.ios.tsx` uses `NativeTabs` from `expo-router/unstable-native-tabs` (system UIKit tab bar). The wallet tab shows a numeric badge for unopened packs. The app uses `systemChromeMaterialDark` with gold selection tint (`#FFD700`). +- **Android and web:** `app/(tabs)/_layout.tsx` uses JS-based `Tabs` with a hidden default bar and a custom `PillTabBar` overlay. Android uses `expo-blur` (`BlurView`) for the pill background. +- **Shared config:** `components/navigation/tab-config.ts` defines tab order, SF Symbol pairs for iOS, and active-tab pathname rules. ## 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 **Zustand** (`services/store.ts`) persisted to **MMKV** (`services/storage.ts`). +- User/session-sensitive state is coordinated with backend auth and profile sync endpoints via `context/user-context.tsx`. ## 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. +- `lib/api/client.ts` is the base HTTP client with auth token injection from Clerk. +- `lib/api/cache.ts` provides `fetchWithCache()` for MMKV cache-first fetching. +- Domain modules: `wallet-api.ts`, `shop-api.ts`, `user-api.ts`, `quests-api.ts`, `leaderboard-api.ts`, `locker-room-api.ts`, `teams-api.ts`, `collectibles-api.ts`, `checkout-api.ts`. +- Quest/reward/team flows consume backend eligibility as source of truth. + +## Checkout and payments + +- **Fiat payments:** RevenueCat (`lib/revenuecat/provider.tsx`) handles Apple IAP (native), Google Play (native), and Stripe (web). +- **Crypto checkout:** `lib/api/checkout-api.ts` calls the PWA backend (`POST /api/checkout/crypto` and `POST /api/checkout/crypto/verify`). Thirdweb SDK handles on-chain transaction signing. +- **Supported chains:** Arbitrum (default), Ethereum, Polygon. ## 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. +- **iOS:** Native tab bar with Liquid Glass material, Apple Sign In, haptic feedback via `expo-haptics`. +- **Android:** Custom pill tab bar with blur, adaptive icons, predictive back gesture disabled. +- **Web:** Responsive max-width container (`components/layout/AppScreen.tsx` at 480px), hover states via `components/ui/WebHoverWrapper.tsx`, PWA manifest with `display: standalone`. +- Haptics, modal controls, and animation handling use platform-safe fallbacks with React Native Reanimated. + +## Push notifications + +OneSignal is used for push notifications across iOS and Android. The `onesignal-expo-plugin` config plugin handles native setup during `expo prebuild`. Subscription management is in `lib/onesignal-subscription.ts`. + +## Widgets + +- **iOS:** Live Activity widget (`widgets/ios/LiveActivityStatus.tsx`) and rank/points widget (`widgets/ios/RankOrPointsWidget.tsx`). +- **Android:** Home-screen widgets via `react-native-android-widget` with registry in `widgets/android/registry.tsx`. +- **Shared:** `widgets/widget-controls.ts` provides control logic and data helpers. diff --git a/repositories/d-sports-engage-native/feature-mapping.mdx b/repositories/d-sports-engage-native/feature-mapping.mdx index 27fbcd7..58486b6 100644 --- a/repositories/d-sports-engage-native/feature-mapping.mdx +++ b/repositories/d-sports-engage-native/feature-mapping.mdx @@ -9,18 +9,47 @@ description: "Native feature coverage and parity mapping against backend/PWA beh ## Wallet and pack opening -- Wallet screens consume balances, token data, and secure key/pin flows from backend APIs. +- Wallet screens consume balances, token data, and secure key/pin flows from backend APIs via `lib/api/wallet-api.ts`. - Pack browsing, purchase, and open flows use backend-driven states and inventory refresh behavior. +- Crypto checkout supports Arbitrum, Ethereum, and Polygon chains via Thirdweb SDK. +- Fiat checkout uses RevenueCat for Apple IAP, Google Play, and Stripe (web). - Odds-disclosure surfaces read backend-provided probability payloads. +## Shop and commerce + +- Collectible cards, packs, and coin bundles are rendered with 3D model previews (Filament on native, Three.js on web). +- Cart state, coin cart, and checkout logic are managed in `hooks/use-shop-screen.ts`. +- `components/shop/CryptoCheckoutModal.tsx` handles wallet selection, transaction sending, and verification polling. + ## Quest, rewards, and pass surfaces -- Quest UI supports team-aware progression and pass-gated eligibility. +- Quest UI supports team-aware progression and pass-gated eligibility via `lib/api/quests-api.ts`. - Reward states and claim flows follow backend quest/reward APIs. - Global pass and event pass effects are reflected in native quest visibility/completion UX. +- Quest detail modals and hero icons are rendered in the locker room section. + +## Locker room and social + +- Social feed with post creation, comments, and user-generated content in `components/locker-room/FeedSection.tsx`. +- Daily games: pick-em (`DailyPickEmGame.tsx`), spin wheel (`DailySpinWheelGame.tsx`), and guess-the-player (`GuessThePlayerGame.tsx`). +- User profile hover cards, fan exploration, and team exploration surfaces. +- Content moderation with hidden UGC preview and report-after-prompt flows. ## Team and leaderboard integration -- Teams and leagues metadata are consumed from backend `/api/teams` and `/api/leagues`. +- Teams and leagues metadata are consumed from backend `/api/teams` and `/api/leagues` via `lib/api/teams-api.ts`. - Leaderboard displays and team-scoped ranking views align with backend leaderboard contracts. +- Team quest sections show per-team progression and pass-aware eligibility. - Favorite-team interactions influence quest and leaderboard context where backend eligibility requires it. + +## Profile and achievements + +- User profiles with milestone avatars, achievement cards, and badge display. +- Follow/follower lists and points history modals. +- Badge image resolution with caching (`components/profile/CachedBadgeImage.tsx`). + +## Settings + +- Nested settings screens: account, appearance, accessibility, audio, notifications, privacy, data, legal, support, and room settings. +- In-app account deletion, blocked users management, and connected accounts. +- Changelog viewer with timeline UI (`components/settings/changelog/`).