docs: expand d-sports-engage-native page with architecture details

repositories/d-sports-engage-native.mdx

@@ -1,15 +1,13 @@
 ---
 title: "d-sports-engage-native"
 description: "Native iOS and Android app for D-Sports Engage. Expo 54, React Native, 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.
 
-- **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.
-
 ## Tech stack
 
 | Category   | Technology                |
@@ -17,31 +15,109 @@
 | 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                       |
 
 ## 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)
 
 ## 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`.
-4. For development builds: `bun run build:dev` (EAS) or run with Expo dev client.
+```bash
+# Install dependencies
+bun install
+
+# Start development server
+bunx expo start
+# Press 'a' for Android, 'i' for iOS, or scan QR with Expo Go
+
+# TypeScript check
+bun tsc --noEmit
+```
+
+Configure environment (Clerk, RevenueCat, Thirdweb, API base URL) per repo README. For development builds, use `bun run build:dev` (EAS) or run with Expo dev client.
+
+## Project structure
+
+```tree
+app/
+├── (auth)/              # Login/signup screens
+├── (onboarding)/        # New user onboarding flow
+├── (tabs)/              # Main tab navigation
+│   ├── wallet.tsx       # Wallet screen (JSX only — logic in hook)
+│   ├── shop.tsx         # Shop screen (JSX only — logic in hook)
+│   ├── leaderboard.tsx  # Leaderboard screen
+│   ├── locker-room.tsx  # Social feed
+│   ├── profile.tsx      # User profile
+│   └── styles/          # Extracted StyleSheet files
+├── settings/            # Settings pages with nested modals/tabs
+└── _layout.tsx          # Root layout with providers + auth protection
+
+components/
+├── wallet/              # 9 extracted wallet sub-components
+├── shop/                # 7 extracted shop sub-components
+├── locker-room/         # Locker room components
+├── layout/              # AppScreen wrapper (responsive web max-width)
+├── ui/                  # Reusable UI primitives (Button, TextField, etc.)
+├── Icon/                # Icon wrapper using lucide-react-native
+└── theme-provider.tsx   # Theme context (dark/light)
+
+hooks/
+├── use-wallet-screen.ts # All wallet state, effects, and handlers
+├── use-shop-screen.ts   # All shop state, effects, and handlers
+└── useScrollHandler.ts  # Scroll-based navbar visibility
+
+lib/
+├── api/                 # API client modules (wallet, shop, user, quests, checkout, etc.)
+├── revenuecat/          # RevenueCat in-app purchases provider
+├── token-utils.ts       # Shared getTokenColors()
+├── rarity-utils.ts      # Shared walletRarityColors
+└── utils.ts             # cn() class merging utility
+
+context/
+├── user-context.tsx     # Authentication, user profile, team membership
+├── collectibles-context.tsx # Owned packs and items
+├── navbar-visibility-context.tsx
+└── create-action-context.tsx
+
+services/
+├── store.ts             # Zustand global store (theme, cart, points)
+├── storage.ts           # MMKV persistence adapter
+└── types.ts             # Core types (User, Room, Team, Product)
+```
+
+## Architecture patterns
+
+- **File-based routing** via Expo Router with route groups `(tabs)`, `(auth)`, `(onboarding)`
+- **Modular screen architecture** — screen files contain only JSX; all state/effects/handlers live in dedicated hooks (`use-wallet-screen.ts`, `use-shop-screen.ts`)
+- **Extracted sub-components** — wallet and shop screens decomposed into `components/wallet/` and `components/shop/` with barrel exports
+- **Zustand + MMKV** for global state with synchronous persistence
+- **React Context** for auth, collectibles, navbar visibility
+- **API client layer** in `lib/api/` with MMKV cache fallback
+- **Crypto checkout** via Thirdweb SDK calling PWA backend for on-chain payments (Arbitrum, Ethereum, Polygon)
+- **PWA-ready** — `display: standalone`, responsive desktop layout, web hover states, keyboard nav
+- **Path alias** `@/*` maps to project root
+
+## Branding
+
+| Token | Value |
+| ----- | ----- |
+| Base Background (Dark) | `#0a0e1a` |
+| Accent Gold | `#F5C842` / `#FFD700` |
+| Primary Blue | `#4169E1` |
 
-The app targets both native and web (responsive) and uses the same backend (d-sports-api) as the PWA for API and checkout flows.
+Default theme is dark mode.
 
 <Card title="Ecosystem overview" icon="map" href="/repositories/ecosystem-overview">
   See how the native app fits with the PWA, site, and Mic'd Up.
 </Card>