Skip to content

Sync engage-native docs with Expo 55 and expanded features #293

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mintlify wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Sync engage-native docs with Expo 55 and expanded features #293

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 49 additions & 26 deletions repositories/d-sports-engage-native.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"
---

Expand All @@ -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

Expand All @@ -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.

Expand Down
49 changes: 39 additions & 10 deletions repositories/d-sports-engage-native/architecture.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
44 changes: 42 additions & 2 deletions repositories/d-sports-engage-native/feature-mapping.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.