From 6953ee45b67ed9c5044642721f5402102136f300 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Thu, 16 Apr 2026 01:20:19 +0000 Subject: [PATCH] docs: sync engage-native docs with Expo 55, RN 0.83, and expanded feature coverage Generated-By: mintlify-agent --- repositories/d-sports-engage-native.mdx | 75 ++++++++++++------- .../d-sports-engage-native/architecture.mdx | 49 +++++++++--- .../feature-mapping.mdx | 44 ++++++++++- 3 files changed, 130 insertions(+), 38 deletions(-) diff --git a/repositories/d-sports-engage-native.mdx b/repositories/d-sports-engage-native.mdx index e79c1b6..e271d51 100644 --- a/repositories/d-sports-engage-native.mdx +++ b/repositories/d-sports-engage-native.mdx @@ -1,6 +1,6 @@ --- 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" --- @@ -12,45 +12,58 @@ icon: "smartphone" ## 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 | +| Storage | MMKV | +| UI | Lucide React Native | +| Navigation | Expo Router (file-based, typed routes) | +| Push | OneSignal | +| Error tracking | Sentry | +| Widgets | expo-widgets (iOS), react-native-android-widget | +| 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 +- **Shop** — Collectibles, cart, coin bundles, fiat (RevenueCat) and crypto (Thirdweb) checkout +- **Leaderboard** — Rankings, team-scoped filters, quest hero icons +- **Locker room** — Social feed, daily pick'em, spin wheel, guess-the-player games, explore fans/teams +- **Profile** — User profile, achievements, milestone avatars, follow lists, points history +- **Settings** — Account, appearance, accessibility, notifications, support, changelog, legal +- **Widgets** — iOS home-screen and Live Activity widgets, Android home-screen widget for rank/points +- **Push notifications** — OneSignal integration with iOS app groups - **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. Required variables: + +| Variable | Purpose | +| -------- | ------- | +| `EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY` | Clerk authentication | +| `EXPO_PUBLIC_API_URL` | Backend API base URL | +| `EXPO_PUBLIC_TW_CLIENT_ID` | Thirdweb Web3 client | +| `EXPO_PUBLIC_REVENUECAT_API_KEY` | RevenueCat in-app purchases | +| `EXPO_PUBLIC_SUPABASE_URL` | Supabase client 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`. +- API 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`, `games-api.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,9 +78,19 @@ icon: "smartphone" ## Getting started 1. Clone the repository and run `bun install`. -2. Configure environment (Clerk, RevenueCat, Thirdweb, API base URL) per repo README. -3. Run `bunx expo start`. +2. Copy `.env` and configure environment variables (Clerk, RevenueCat, Thirdweb, API base URL, Supabase). +3. Run `bunx expo start` — press `a` for Android, `i` for iOS, or scan the QR code. 4. For development builds: `bun run build:dev` (EAS) or run with Expo dev client. +5. For TypeScript checks: `bun tsc --noEmit`. + +### EAS build commands + +| Command | Description | +| ------- | ----------- | +| `bun run build:dev` | Development build (all platforms) | +| `bun run build:preview` | Preview build (all platforms) | +| `bun run build:prod` | Production build (all platforms) | +| `bun run update` | OTA update via EAS Update | 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..1fe5afa 100644 --- a/repositories/d-sports-engage-native/architecture.mdx +++ b/repositories/d-sports-engage-native/architecture.mdx @@ -7,24 +7,53 @@ 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 JSX; all state, effects, and handlers live in dedicated hooks (`use-wallet-screen.ts`, `use-shop-screen.ts`, `use-feed-section.ts`, `use-shop-screen.ts`). +- **Shared contexts:** user, collectibles, accessibility, navbar visibility, and create-action state controls. +- **Path alias:** `@/*` maps to project root for clean imports. ## State and context boundaries +- **Zustand + MMKV** for global state (`services/store.ts`) with synchronous persistence via `services/storage.ts`. +- **React Context** providers in `context/`: + - `UserContext` — authentication, user profile, team membership + - `CollectiblesContext` — owned packs and items + - `NavBarVisibilityContext` — scroll-based hide/show of bottom nav + - `CreateActionContext` — FAB/action modal state + - `AccessibilityContext` — accessibility preferences sync - 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. ## 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/*` modules with a centralized HTTP client in `lib/api/client.ts`. +- Client wrappers handle auth token propagation (Clerk), error normalization, and retry strategy. +- `lib/api/cache.ts` provides `fetchWithCache()` with MMKV cache-first fetching for offline resilience. +- Quest/reward/team flows consume backend eligibility as source of truth. + +## Tab bar navigation + +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) with `systemChromeMaterialDark` material and gold selection accent (`#FFD700`). +- **Android and web:** `app/(tabs)/_layout.tsx` uses Expo Router `Tabs` with the default bar hidden, replaced by a custom `PillTabBar` overlay with `expo-blur`. +- **Shared config:** `components/navigation/tab-config.ts` defines tab order, SF Symbol pairs, and active-tab detection logic. + +## Checkout and payments + +- **RevenueCat** (`lib/revenuecat/provider.tsx`) handles fiat payments — Apple IAP (native), Google Play (native), and Stripe (web). +- **Crypto checkout** (`lib/api/checkout-api.ts`) calls the PWA backend at `POST /api/checkout/crypto` and `POST /api/checkout/crypto/verify`. +- **Thirdweb SDK** handles on-chain transaction signing. Supported chains: Arbitrum (default), Ethereum, Polygon. +- `components/shop/CryptoCheckoutModal.tsx` provides wallet selection, transaction sending, verification polling, and status UI. + +## Widgets + +- **iOS:** `widgets/ios/RankOrPointsWidget.tsx` (home screen) and `widgets/ios/LiveActivityStatus.tsx` (Live Activity) via `expo-widgets`. +- **Android:** `widgets/android/registry.tsx` with `react-native-android-widget` for a rank/points home-screen widget. +- **Shared:** `widgets/widget-controls.ts` provides data helpers and `lib/widget-data.ts` handles data serialization. ## 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/Android platform differences are handled in native-specific layout files (e.g., `_layout.ios.tsx` vs `_layout.android.tsx`) and runtime checks. +- Web-target support exists with responsive `maxWidth: 480px` container (`components/layout/AppScreen.tsx`), web hover states, and PWA manifest configuration. +- Haptics (`hooks/use-haptics.ts`), modal controls, and animation handling (React Native Reanimated) use platform-safe fallbacks. diff --git a/repositories/d-sports-engage-native/feature-mapping.mdx b/repositories/d-sports-engage-native/feature-mapping.mdx index 27fbcd7..d582a2d 100644 --- a/repositories/d-sports-engage-native/feature-mapping.mdx +++ b/repositories/d-sports-engage-native/feature-mapping.mdx @@ -11,16 +11,56 @@ 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 send/receive transactions use Thirdweb SDK with Arbitrum, Ethereum, and Polygon chain support. +- Opened packs section tracks inventory with detail modals for each opened pack. - Odds-disclosure surfaces read backend-provided probability payloads. +## Shop and checkout + +- Collectible browsing with rarity-based styling, detail modals, and 3D model viewers (Filament on native, Three.js on web). +- Cart management with coin bundles and fiat checkout via RevenueCat (Apple IAP, Google Play, Stripe). +- Crypto checkout flow with wallet selection, on-chain transaction signing, and verification polling. + +## Locker room and social + +- Social feed with post creation, comments, and user-generated content moderation (hide/report). +- **Daily pick'em game** — team-based daily predictions. +- **Spin wheel game** — daily reward wheel with animated spin. +- **Guess-the-player game** — player identification challenge. +- Explore fans and explore teams discovery surfaces. +- User profile hover cards with follow/block actions. + ## 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 with quest detail modals. - Reward states and claim flows follow backend quest/reward APIs. - Global pass and event pass effects are reflected in native quest visibility/completion UX. ## 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. +- Leaderboard displays with team-scoped ranking views, quest hero icons, and team quest sections. - Favorite-team interactions influence quest and leaderboard context where backend eligibility requires it. + +## Profile and achievements + +- User profile with milestone avatars, achievement cards/chips, and badge display. +- Achievement detail modals with cached badge images. +- Follow lists (followers/following) with profile modals. +- Points history tracking. + +## Settings + +- **Account** — connected accounts, security, blocked users, account deletion. +- **Appearance** — dark/light theme toggle. +- **Accessibility** — accessibility preferences with sync across sessions. +- **Notifications** — push notification preferences (OneSignal). +- **Support** — contact support, report problem, help center. +- **Legal** — terms of service, privacy policy, EULA. +- **Changelog** — in-app changelog with timeline UI. + +## Widgets and Live Activities + +- **iOS home-screen widget** — rank or points display (`RankOrPointsWidget`). +- **iOS Live Activity** — live status updates for scores (`LiveActivityStatus`). +- **Android home-screen widget** — rank or points display via `react-native-android-widget`.