From 778c09f6e440b13b9bec691dcf2debcb6f9dbdbc Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 1 Jan 2026 11:12:30 +0000
Subject: [PATCH 1/2] docs: Add comprehensive mobile app development plan

Create detailed plan for building React Native mobile apps for Android
and iOS. Includes framework comparison, architecture design, reusable
asset analysis, implementation phases, and risk assessment.

Recommends Expo with React Native for best balance of developer
experience, code sharing potential, and native capabilities.
---
 docs/mobile-app-plan.md | 669 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 669 insertions(+)
 create mode 100644 docs/mobile-app-plan.md

diff --git a/docs/mobile-app-plan.md b/docs/mobile-app-plan.md
new file mode 100644
index 00000000..0dab642b
--- /dev/null
+++ b/docs/mobile-app-plan.md
@@ -0,0 +1,669 @@
+# Boardsesh Mobile App Development Plan
+
+## Executive Summary
+
+This document outlines a strategy for building native Android and iOS apps for Boardsesh that provide feature parity with the existing Next.js web application. The recommended approach is **React Native with Expo** due to code sharing potential, strong Bluetooth support, and the team's existing React expertise.
+
+---
+
+## Table of Contents
+
+1. [Current Architecture Analysis](#current-architecture-analysis)
+2. [Framework Comparison](#framework-comparison)
+3. [Recommended Approach](#recommended-approach)
+4. [Reusable Assets](#reusable-assets)
+5. [Components Requiring Rebuild](#components-requiring-rebuild)
+6. [Feature Implementation Plan](#feature-implementation-plan)
+7. [Technical Architecture](#technical-architecture)
+8. [Package Structure](#package-structure)
+9. [Implementation Phases](#implementation-phases)
+10. [Risk Assessment](#risk-assessment)
+
+---
+
+## Current Architecture Analysis
+
+### What We Have
+
+| Layer | Technology | Mobile Compatibility |
+|-------|-----------|---------------------|
+| Frontend | Next.js 15 + React 19 | ❌ Requires rewrite |
+| UI Library | Ant Design | ❌ Web-only |
+| State Management | Context + useReducer | ✅ Portable |
+| Real-time | GraphQL-ws WebSocket | ✅ Works in RN |
+| Backend | GraphQL Yoga + Redis | ✅ No changes needed |
+| Database | PostgreSQL + Drizzle | ✅ Server-side only |
+| Shared Types | TypeScript types | ✅ Fully reusable |
+| Board Rendering | SVG | ⚠️ Needs react-native-svg |
+| Bluetooth | Web Bluetooth API | ❌ Needs react-native-ble-plx |
+| Offline Storage | IndexedDB | ❌ Needs AsyncStorage/SQLite |
+
+### Key Features to Replicate
+
+1. **Board Visualization** - SVG-based interactive climbing board display
+2. **Bluetooth Control** - Connect to board hardware, control LEDs
+3. **Queue Management** - Add/remove/reorder climbs, set current climb
+4. **Party Mode** - Real-time multi-user session collaboration
+5. **Search & Discovery** - Find climbs with filters (grade, quality, setter)
+6. **Authentication** - Aurora Climbing login, user sessions
+7. **Logbook** - Track ascents, attempts, personal progress
+8. **Favorites & Playlists** - Save and organize climbs
+
+---
+
+## Framework Comparison
+
+### Option 1: React Native + Expo (Recommended)
+
+**Pros:**
+- React expertise transfers directly
+- Expo simplifies Bluetooth, push notifications, app store deployment
+- Large ecosystem, active community
+- react-native-ble-plx is mature for Bluetooth
+- react-native-svg works well for board rendering
+- Code sharing possible with web via React Native Web
+
+**Cons:**
+- Need to rewrite all UI components
+- Some Expo limitations (mitigated by dev builds)
+- Performance tuning may be needed for complex SVG rendering
+
+### Option 2: Capacitor (Wrap Existing Web App)
+
+**Pros:**
+- Minimal code changes to existing web app
+- Fastest initial development
+- Single codebase for all platforms
+
+**Cons:**
+- Web Bluetooth still doesn't work in Capacitor WebView
+- Would need native Bluetooth plugin anyway
+- Performance concerns with complex SVG/animations
+- "WebView app" feel, not truly native
+
+### Option 3: Flutter
+
+**Pros:**
+- Excellent performance
+- Single codebase for iOS/Android
+- Strong Bluetooth libraries
+
+**Cons:**
+- Dart language - no code reuse with existing TypeScript
+- Team would need to learn new framework
+- Duplicate business logic
+
+### Option 4: Native (Swift/Kotlin)
+
+**Pros:**
+- Best possible performance
+- Full platform capabilities
+
+**Cons:**
+- Two separate codebases
+- Significantly more development effort
+- No code sharing with web
+
+### Recommendation: React Native + Expo
+
+React Native with Expo provides the best balance of:
+- Developer experience (React/TypeScript skills transfer)
+- Code sharing (shared-schema, business logic, types)
+- Native capabilities (Bluetooth, offline storage)
+- Ecosystem maturity (well-tested libraries for all our needs)
+
+---
+
+## Recommended Approach
+
+### High-Level Strategy
+
+1. **Create a new `packages/mobile` package** in the monorepo
+2. **Use Expo with development builds** for native module support
+3. **Share code via internal packages** (shared-schema, potentially shared-logic)
+4. **Build progressively** - start with core features, add complexity
+
+### Technology Stack
+
+| Concern | Library |
+|---------|---------|
+| Framework | Expo SDK 52+ with React Native |
+| Navigation | React Navigation 7 |
+| UI Library | Tamagui or React Native Paper |
+| Bluetooth | react-native-ble-plx |
+| SVG Rendering | react-native-svg |
+| State Management | React Context + useReducer (same pattern) |
+| GraphQL | graphql-request + graphql-ws |
+| Offline Storage | expo-sqlite or @react-native-async-storage |
+| Authentication | expo-secure-store + custom auth |
+| Forms | React Hook Form |
+| Animations | react-native-reanimated |
+
+---
+
+## Reusable Assets
+
+### Fully Reusable (No Changes)
+
+1. **Backend Package** (`packages/backend`)
+   - GraphQL API works with any client
+   - WebSocket subscriptions compatible
+   - No changes required
+
+2. **Shared Schema** (`packages/shared-schema`)
+   - GraphQL schema definitions
+   - TypeScript type definitions
+   - GraphQL operations (queries, mutations, subscriptions)
+
+3. **Database Package** (`packages/db`)
+   - Server-side only, no changes needed
+
+### Reusable with Adaptation
+
+1. **Business Logic**
+   - Queue reducer logic (`queue-control/reducer.ts`)
+   - Hold state mappings and color constants
+   - URL parameter encoding (for deep linking)
+   - Climb data transformations
+
+2. **Design Tokens** (`theme-config.ts`)
+   - Colors, spacing values
+   - Typography scale
+   - Border radius values
+
+3. **Constants**
+   - Board type definitions
+   - Hold state colors
+   - Grade mappings
+
+### Create New Shared Package
+
+Consider creating `packages/shared-logic` for:
+- Queue reducer
+- Climb utilities
+- Board configuration logic
+- Common validation schemas
+
+---
+
+## Components Requiring Rebuild
+
+### UI Components (Complete Rewrite)
+
+| Web Component | Mobile Equivalent |
+|--------------|-------------------|
+| Ant Design components | Tamagui/RN Paper components |
+| Search Drawer | Bottom Sheet with filters |
+| Queue List | FlatList with gestures |
+| Board Renderer | react-native-svg based |
+| Climb Card | Native card component |
+| Settings screens | Native settings UI |
+| Auth forms | Native form components |
+
+### Platform-Specific Features
+
+| Feature | Web Technology | Mobile Technology |
+|---------|---------------|-------------------|
+| Bluetooth | Web Bluetooth API | react-native-ble-plx |
+| Offline storage | IndexedDB | expo-sqlite / AsyncStorage |
+| Deep linking | Next.js routing | React Navigation deep links |
+| Push notifications | N/A | expo-notifications |
+| Haptic feedback | N/A | expo-haptics |
+| Screen wake lock | Wake Lock API | expo-keep-awake |
+
+---
+
+## Feature Implementation Plan
+
+### Core Features (MVP)
+
+1. **Board Visualization**
+   - SVG rendering with react-native-svg
+   - Touch handling for hold selection
+   - Zoom/pan with react-native-gesture-handler
+   - Mirroring support
+
+2. **Bluetooth Connection**
+   - Device discovery and pairing
+   - LED control protocol (port existing logic)
+   - Connection state management
+   - Background reconnection
+
+3. **Climb Search**
+   - Filter by grade, quality, ascents
+   - Setter search
+   - Sort options
+   - Infinite scroll results
+
+4. **Queue Management**
+   - Add/remove climbs
+   - Reorder with drag-and-drop
+   - Set current climb
+   - Queue persistence
+
+5. **Authentication**
+   - Aurora Climbing login
+   - Secure token storage
+   - Session management
+
+### Enhanced Features (Post-MVP)
+
+1. **Party Mode**
+   - Session creation/joining
+   - Real-time sync
+   - User presence
+   - Leader controls
+
+2. **Logbook**
+   - Track ascents and attempts
+   - Progress statistics
+   - History view
+
+3. **Favorites & Playlists**
+   - Save favorite climbs
+   - Create/manage playlists
+   - Quick access
+
+4. **Offline Mode**
+   - Cache climb data
+   - Queue offline changes
+   - Sync when connected
+
+5. **Push Notifications**
+   - Party invitations
+   - Queue updates when app backgrounded
+
+---
+
+## Technical Architecture
+
+### Package Structure
+
+```
+boardsesh/
+├── packages/
+│   ├── web/                    # Existing Next.js app
+│   ├── backend/                # Existing GraphQL backend
+│   ├── shared-schema/          # GraphQL schema + types
+│   ├── db/                     # Database schema
+│   ├── shared-logic/           # NEW: Shared business logic
+│   │   ├── src/
+│   │   │   ├── queue/          # Queue reducer, actions
+│   │   │   ├── board/          # Board config, hold mappings
+│   │   │   ├── climb/          # Climb utilities
+│   │   │   └── index.ts
+│   │   └── package.json
+│   └── mobile/                 # NEW: React Native app
+│       ├── app/                # Expo Router app directory
+│       │   ├── (tabs)/         # Tab navigation
+│       │   ├── (auth)/         # Auth screens
+│       │   ├── board/          # Board screens
+│       │   ├── party/          # Party mode screens
+│       │   └── _layout.tsx
+│       ├── components/
+│       │   ├── board/          # Board renderer
+│       │   ├── queue/          # Queue components
+│       │   ├── search/         # Search UI
+│       │   ├── common/         # Shared components
+│       │   └── bluetooth/      # Bluetooth controls
+│       ├── hooks/
+│       │   ├── useBluetooth.ts
+│       │   ├── useQueue.ts
+│       │   └── useParty.ts
+│       ├── services/
+│       │   ├── bluetooth/      # BLE protocol
+│       │   ├── graphql/        # GraphQL client
+│       │   └── storage/        # Local storage
+│       ├── contexts/
+│       │   ├── AuthContext.tsx
+│       │   ├── QueueContext.tsx
+│       │   └── BluetoothContext.tsx
+│       ├── theme/
+│       │   └── tokens.ts       # Design tokens
+│       ├── app.json            # Expo config
+│       ├── package.json
+│       └── tsconfig.json
+```
+
+### Data Flow Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      Mobile App                              │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
+│  │   Screens   │  │  Components │  │   Context Providers │  │
+│  │  (Expo      │──│  (Tamagui/  │──│  - Auth             │  │
+│  │   Router)   │  │   RN Paper) │  │  - Queue            │  │
+│  └─────────────┘  └─────────────┘  │  - Bluetooth        │  │
+│                                     │  - Party            │  │
+│                                     └─────────────────────┘  │
+│         │                                    │               │
+│         ▼                                    ▼               │
+│  ┌─────────────┐                    ┌─────────────────────┐  │
+│  │   Hooks     │                    │   Local Storage     │  │
+│  │  - useQueue │                    │   - SQLite/         │  │
+│  │  - useBLE   │                    │     AsyncStorage    │  │
+│  └─────────────┘                    └─────────────────────┘  │
+│         │                                                    │
+└─────────┼────────────────────────────────────────────────────┘
+          │
+          ▼
+┌─────────────────────────────────────────────────────────────┐
+│                   Backend (Unchanged)                        │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────────────┐    ┌─────────────────┐                 │
+│  │  GraphQL HTTP   │    │  GraphQL WS     │                 │
+│  │  (Queries/      │    │  (Subscriptions)│                 │
+│  │   Mutations)    │    │                 │                 │
+│  └────────┬────────┘    └────────┬────────┘                 │
+│           │                      │                           │
+│           ▼                      ▼                           │
+│  ┌─────────────────────────────────────────────────────────┐│
+│  │              GraphQL Yoga Server                         ││
+│  │              + Room Manager + PubSub                     ││
+│  └─────────────────────────────────────────────────────────┘│
+│                          │                                   │
+│                          ▼                                   │
+│  ┌───────────────┐  ┌───────────────┐                       │
+│  │  PostgreSQL   │  │    Redis      │                       │
+│  │  (Data)       │  │  (Pub/Sub)    │                       │
+│  └───────────────┘  └───────────────┘                       │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Bluetooth Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                   BluetoothContext                           │
+├─────────────────────────────────────────────────────────────┤
+│  State:                                                      │
+│  - connectionState: 'disconnected' | 'scanning' |           │
+│                     'connecting' | 'connected'               │
+│  - device: Device | null                                     │
+│  - error: Error | null                                       │
+├─────────────────────────────────────────────────────────────┤
+│  Actions:                                                    │
+│  - startScan()                                               │
+│  - connect(deviceId)                                         │
+│  - disconnect()                                              │
+│  - sendClimb(frames, holdStateMap)                          │
+│  - clearBoard()                                              │
+└─────────────────────────────────────────────────────────────┘
+          │
+          ▼
+┌─────────────────────────────────────────────────────────────┐
+│              BluetoothService (react-native-ble-plx)         │
+├─────────────────────────────────────────────────────────────┤
+│  - BleManager instance                                       │
+│  - Device scanning with Aurora UUID filter                   │
+│  - GATT service/characteristic discovery                     │
+│  - Write commands with chunking (20 byte limit)             │
+│  - Connection monitoring and auto-reconnect                  │
+└─────────────────────────────────────────────────────────────┘
+          │
+          ▼
+┌─────────────────────────────────────────────────────────────┐
+│                  Bluetooth Protocol                          │
+│         (Port from web: board-bluetooth-control/)            │
+├─────────────────────────────────────────────────────────────┤
+│  - Nordic UART Service UUID: 6e400001-...                   │
+│  - Write Characteristic: 6e400002-...                        │
+│  - Packet framing: FIRST(82), MIDDLE(81), LAST(83)          │
+│  - Color encoding: RGB to 8-bit                              │
+│  - Position encoding                                         │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Implementation Phases
+
+### Phase 1: Foundation (4-6 weeks)
+
+**Goals:** Project setup, core infrastructure, basic navigation
+
+**Tasks:**
+- [ ] Initialize Expo project with TypeScript
+- [ ] Set up monorepo integration (npm workspaces)
+- [ ] Configure React Navigation with Expo Router
+- [ ] Create shared-logic package, extract queue reducer
+- [ ] Set up Tamagui or React Native Paper with theme tokens
+- [ ] Implement GraphQL client (HTTP + WebSocket)
+- [ ] Create authentication flow (login, secure storage)
+- [ ] Build basic navigation structure (tabs, stack)
+
+**Deliverables:**
+- Working app skeleton
+- User can log in
+- Navigation between placeholder screens
+
+### Phase 2: Board Visualization (3-4 weeks)
+
+**Goals:** Render climbing board, display climbs
+
+**Tasks:**
+- [ ] Port SVG board renderer to react-native-svg
+- [ ] Implement hold rendering with state colors
+- [ ] Add touch handling for hold selection
+- [ ] Implement pinch-to-zoom and pan
+- [ ] Create climb card component
+- [ ] Build climb detail view
+- [ ] Add mirroring support
+
+**Deliverables:**
+- Board displays correctly with holds lit up
+- Can view climb details
+- Touch interactions work smoothly
+
+### Phase 3: Bluetooth Integration (3-4 weeks)
+
+**Goals:** Connect to board hardware, control LEDs
+
+**Tasks:**
+- [ ] Set up react-native-ble-plx with Expo dev build
+- [ ] Implement device scanning with Aurora filter
+- [ ] Create connection management (connect, disconnect, reconnect)
+- [ ] Port Bluetooth protocol (packet framing, color encoding)
+- [ ] Build Bluetooth UI (scan modal, connection status)
+- [ ] Add screen wake lock (expo-keep-awake)
+- [ ] Test on physical devices with actual boards
+
+**Deliverables:**
+- Can discover and connect to board
+- Sending climb lights up correct holds
+- Connection survives app backgrounding
+
+### Phase 4: Search & Queue (3-4 weeks)
+
+**Goals:** Find climbs, manage queue
+
+**Tasks:**
+- [ ] Build search UI (filters, sort options)
+- [ ] Implement infinite scroll results
+- [ ] Port queue reducer to shared-logic
+- [ ] Create queue list with drag-to-reorder
+- [ ] Add climb to queue functionality
+- [ ] Implement current climb selection
+- [ ] Local queue persistence
+
+**Deliverables:**
+- Full search functionality
+- Queue management works
+- Queue persists between sessions
+
+### Phase 5: Party Mode (3-4 weeks)
+
+**Goals:** Real-time multi-user sessions
+
+**Tasks:**
+- [ ] Implement WebSocket subscription handling
+- [ ] Port party session logic
+- [ ] Create/join session UI
+- [ ] User presence display
+- [ ] Leader controls
+- [ ] Queue sync between users
+- [ ] Handle connection failures gracefully
+
+**Deliverables:**
+- Can create and join party sessions
+- Real-time queue sync works
+- Multiple users collaborate successfully
+
+### Phase 6: Logbook & Progress (2-3 weeks)
+
+**Goals:** Track climbing progress
+
+**Tasks:**
+- [ ] Implement tick tracking (ascents, attempts)
+- [ ] Build logbook view
+- [ ] Add progress statistics
+- [ ] Create history timeline
+- [ ] Sync with server
+
+**Deliverables:**
+- Can log ascents and attempts
+- View climbing history
+- Stats display correctly
+
+### Phase 7: Polish & Launch Prep (2-3 weeks)
+
+**Goals:** Production readiness
+
+**Tasks:**
+- [ ] Performance optimization
+- [ ] Error handling and crash reporting (Sentry)
+- [ ] Offline mode improvements
+- [ ] App store assets (icons, screenshots)
+- [ ] Privacy policy, terms of service
+- [ ] Beta testing
+- [ ] App store submission
+
+**Deliverables:**
+- Apps submitted to App Store and Play Store
+- Production-ready builds
+
+---
+
+## Risk Assessment
+
+### Technical Risks
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| BLE protocol differences between platforms | Medium | High | Early testing on both iOS/Android with real hardware |
+| SVG performance with complex boards | Medium | Medium | Profile early, consider Skia if needed |
+| WebSocket reliability in mobile context | Low | High | Robust reconnection logic, offline queue |
+| Expo limitations requiring eject | Low | Medium | Use dev builds from start, evaluate native modules early |
+
+### Resource Risks
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| Underestimated UI rebuild effort | Medium | High | Start with core screens, iterate |
+| Testing across device variety | Medium | Medium | Establish device test matrix early |
+| App store approval delays | Medium | Low | Submit early, be prepared for review feedback |
+
+### Timeline Risks
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| Bluetooth debugging takes longer | High | Medium | Allocate buffer time, test on physical devices early |
+| Feature creep from web parity expectations | Medium | High | Define MVP strictly, communicate tradeoffs |
+
+---
+
+## Success Criteria
+
+### MVP Success Metrics
+
+- [ ] App runs on iOS 15+ and Android 10+
+- [ ] Can connect to Kilter/Tension boards via Bluetooth
+- [ ] Can search, view, and send climbs to board
+- [ ] Queue management works offline and online
+- [ ] Party mode supports 2+ users simultaneously
+- [ ] App Store and Play Store approved
+
+### Performance Targets
+
+- App launch to interactive: < 2 seconds
+- Board render time: < 500ms
+- Bluetooth connection time: < 5 seconds
+- Search response time: < 1 second
+
+---
+
+## Appendix
+
+### Recommended Libraries
+
+```json
+{
+  "dependencies": {
+    "expo": "~52.0.0",
+    "react-native": "0.76.x",
+    "react": "18.3.x",
+
+    "expo-router": "~4.0.0",
+    "@react-navigation/native": "^7.0.0",
+
+    "tamagui": "^1.100.0",
+    "@tamagui/config": "^1.100.0",
+
+    "react-native-ble-plx": "^3.2.0",
+    "react-native-svg": "^15.0.0",
+    "react-native-gesture-handler": "~2.20.0",
+    "react-native-reanimated": "~3.16.0",
+
+    "graphql": "^16.8.0",
+    "graphql-request": "^7.0.0",
+    "graphql-ws": "^6.0.0",
+
+    "expo-secure-store": "~14.0.0",
+    "expo-sqlite": "~15.0.0",
+    "expo-keep-awake": "~14.0.0",
+    "expo-haptics": "~14.0.0",
+
+    "@tanstack/react-query": "^5.0.0",
+    "zod": "^3.22.0"
+  }
+}
+```
+
+### iOS Bluetooth Permissions (Info.plist)
+
+```xml
+<key>NSBluetoothAlwaysUsageDescription</key>
+<string>Boardsesh needs Bluetooth to connect to your climbing board and control the LED holds.</string>
+<key>NSBluetoothPeripheralUsageDescription</key>
+<string>Boardsesh needs Bluetooth to connect to your climbing board.</string>
+<key>UIBackgroundModes</key>
+<array>
+  <string>bluetooth-central</string>
+</array>
+```
+
+### Android Bluetooth Permissions (AndroidManifest.xml)
+
+```xml
+<uses-permission android:name="android.permission.BLUETOOTH" />
+<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
+<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
+<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
+<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+```
+
+---
+
+## Next Steps
+
+1. **Validate approach** - Review this plan with stakeholders
+2. **Set up mobile package** - Initialize Expo project in monorepo
+3. **Proof of concept** - Build BLE connection + basic board render
+4. **Iterate** - Begin Phase 1 implementation
+
+---
+
+*Document created: January 2026*
+*Last updated: January 2026*

From 0d594a9139e3a8d90c7dd65c500879a1a7946bc9 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 1 Jan 2026 12:00:03 +0000
Subject: [PATCH 2/2] docs: Streamline mobile app plan with validation focus

- Remove framework comparison, focus solely on React Native + Expo
- Add Milestone 0 for early technical validation (BLE, WebSocket, SVG)
- Move Party Mode to Milestone 2 as key differentiating feature
- Add validation checkpoints after each milestone
- Include device test matrix and validation gates
- Define clear exit criteria before proceeding to next milestone
---
 docs/mobile-app-plan.md | 965 +++++++++++++++++++---------------------
 1 file changed, 467 insertions(+), 498 deletions(-)

diff --git a/docs/mobile-app-plan.md b/docs/mobile-app-plan.md
index 0dab642b..33f1de6a 100644
--- a/docs/mobile-app-plan.md
+++ b/docs/mobile-app-plan.md
@@ -2,612 +2,563 @@
 
 ## Executive Summary
 
-This document outlines a strategy for building native Android and iOS apps for Boardsesh that provide feature parity with the existing Next.js web application. The recommended approach is **React Native with Expo** due to code sharing potential, strong Bluetooth support, and the team's existing React expertise.
+This document outlines the implementation plan for building native Android and iOS apps using **React Native with Expo**. The plan prioritizes early validation of high-risk technical components and positions Party Mode (real-time collaboration) as a core differentiating feature.
 
 ---
 
 ## Table of Contents
 
-1. [Current Architecture Analysis](#current-architecture-analysis)
-2. [Framework Comparison](#framework-comparison)
-3. [Recommended Approach](#recommended-approach)
-4. [Reusable Assets](#reusable-assets)
-5. [Components Requiring Rebuild](#components-requiring-rebuild)
-6. [Feature Implementation Plan](#feature-implementation-plan)
-7. [Technical Architecture](#technical-architecture)
-8. [Package Structure](#package-structure)
-9. [Implementation Phases](#implementation-phases)
-10. [Risk Assessment](#risk-assessment)
+1. [Technology Stack](#technology-stack)
+2. [Reusable Assets](#reusable-assets)
+3. [Components Requiring Rebuild](#components-requiring-rebuild)
+4. [Package Structure](#package-structure)
+5. [Implementation Milestones](#implementation-milestones)
+6. [Validation Strategy](#validation-strategy)
+7. [Risk Assessment](#risk-assessment)
+8. [Success Criteria](#success-criteria)
 
 ---
 
-## Current Architecture Analysis
-
-### What We Have
-
-| Layer | Technology | Mobile Compatibility |
-|-------|-----------|---------------------|
-| Frontend | Next.js 15 + React 19 | ❌ Requires rewrite |
-| UI Library | Ant Design | ❌ Web-only |
-| State Management | Context + useReducer | ✅ Portable |
-| Real-time | GraphQL-ws WebSocket | ✅ Works in RN |
-| Backend | GraphQL Yoga + Redis | ✅ No changes needed |
-| Database | PostgreSQL + Drizzle | ✅ Server-side only |
-| Shared Types | TypeScript types | ✅ Fully reusable |
-| Board Rendering | SVG | ⚠️ Needs react-native-svg |
-| Bluetooth | Web Bluetooth API | ❌ Needs react-native-ble-plx |
-| Offline Storage | IndexedDB | ❌ Needs AsyncStorage/SQLite |
-
-### Key Features to Replicate
-
-1. **Board Visualization** - SVG-based interactive climbing board display
-2. **Bluetooth Control** - Connect to board hardware, control LEDs
-3. **Queue Management** - Add/remove/reorder climbs, set current climb
-4. **Party Mode** - Real-time multi-user session collaboration
-5. **Search & Discovery** - Find climbs with filters (grade, quality, setter)
-6. **Authentication** - Aurora Climbing login, user sessions
-7. **Logbook** - Track ascents, attempts, personal progress
-8. **Favorites & Playlists** - Save and organize climbs
-
----
-
-## Framework Comparison
-
-### Option 1: React Native + Expo (Recommended)
-
-**Pros:**
-- React expertise transfers directly
-- Expo simplifies Bluetooth, push notifications, app store deployment
-- Large ecosystem, active community
-- react-native-ble-plx is mature for Bluetooth
-- react-native-svg works well for board rendering
-- Code sharing possible with web via React Native Web
-
-**Cons:**
-- Need to rewrite all UI components
-- Some Expo limitations (mitigated by dev builds)
-- Performance tuning may be needed for complex SVG rendering
-
-### Option 2: Capacitor (Wrap Existing Web App)
-
-**Pros:**
-- Minimal code changes to existing web app
-- Fastest initial development
-- Single codebase for all platforms
-
-**Cons:**
-- Web Bluetooth still doesn't work in Capacitor WebView
-- Would need native Bluetooth plugin anyway
-- Performance concerns with complex SVG/animations
-- "WebView app" feel, not truly native
-
-### Option 3: Flutter
-
-**Pros:**
-- Excellent performance
-- Single codebase for iOS/Android
-- Strong Bluetooth libraries
-
-**Cons:**
-- Dart language - no code reuse with existing TypeScript
-- Team would need to learn new framework
-- Duplicate business logic
-
-### Option 4: Native (Swift/Kotlin)
-
-**Pros:**
-- Best possible performance
-- Full platform capabilities
-
-**Cons:**
-- Two separate codebases
-- Significantly more development effort
-- No code sharing with web
-
-### Recommendation: React Native + Expo
-
-React Native with Expo provides the best balance of:
-- Developer experience (React/TypeScript skills transfer)
-- Code sharing (shared-schema, business logic, types)
-- Native capabilities (Bluetooth, offline storage)
-- Ecosystem maturity (well-tested libraries for all our needs)
-
----
-
-## Recommended Approach
-
-### High-Level Strategy
-
-1. **Create a new `packages/mobile` package** in the monorepo
-2. **Use Expo with development builds** for native module support
-3. **Share code via internal packages** (shared-schema, potentially shared-logic)
-4. **Build progressively** - start with core features, add complexity
-
-### Technology Stack
-
-| Concern | Library |
-|---------|---------|
-| Framework | Expo SDK 52+ with React Native |
-| Navigation | React Navigation 7 |
-| UI Library | Tamagui or React Native Paper |
-| Bluetooth | react-native-ble-plx |
-| SVG Rendering | react-native-svg |
-| State Management | React Context + useReducer (same pattern) |
-| GraphQL | graphql-request + graphql-ws |
-| Offline Storage | expo-sqlite or @react-native-async-storage |
-| Authentication | expo-secure-store + custom auth |
-| Forms | React Hook Form |
-| Animations | react-native-reanimated |
+## Technology Stack
+
+| Concern | Library | Rationale |
+|---------|---------|-----------|
+| Framework | Expo SDK 52+ | Simplified native module management, OTA updates |
+| Navigation | Expo Router | File-based routing, deep linking built-in |
+| UI Library | Tamagui | Performance-focused, great theming, cross-platform |
+| Bluetooth | react-native-ble-plx | Mature, well-documented, handles iOS/Android differences |
+| SVG Rendering | react-native-svg | Direct port path from web SVG components |
+| Gestures | react-native-gesture-handler | Smooth drag-drop, pinch-zoom |
+| Animations | react-native-reanimated | 60fps animations, worklet-based |
+| State | React Context + useReducer | Same pattern as web, easy code sharing |
+| GraphQL HTTP | graphql-request | Lightweight, TypeScript-first |
+| GraphQL WS | graphql-ws | Same library as web, proven compatibility |
+| Data Fetching | @tanstack/react-query | Caching, background sync, same as web |
+| Offline Storage | expo-sqlite | Relational queries, better than AsyncStorage |
+| Secure Storage | expo-secure-store | Keychain/Keystore for tokens |
+| Forms | React Hook Form + Zod | Validation, same schemas as web |
 
 ---
 
 ## Reusable Assets
 
-### Fully Reusable (No Changes)
-
-1. **Backend Package** (`packages/backend`)
-   - GraphQL API works with any client
-   - WebSocket subscriptions compatible
-   - No changes required
-
-2. **Shared Schema** (`packages/shared-schema`)
-   - GraphQL schema definitions
-   - TypeScript type definitions
-   - GraphQL operations (queries, mutations, subscriptions)
+### Direct Reuse (No Changes)
 
-3. **Database Package** (`packages/db`)
-   - Server-side only, no changes needed
+| Package | What's Reusable |
+|---------|-----------------|
+| `packages/backend` | Entire package - GraphQL API, WebSocket subscriptions |
+| `packages/shared-schema` | GraphQL schema, TypeScript types, operations |
+| `packages/db` | Server-side only, unchanged |
 
-### Reusable with Adaptation
+### Reuse with Extraction
 
-1. **Business Logic**
-   - Queue reducer logic (`queue-control/reducer.ts`)
-   - Hold state mappings and color constants
-   - URL parameter encoding (for deep linking)
-   - Climb data transformations
+Create `packages/shared-logic` to share:
 
-2. **Design Tokens** (`theme-config.ts`)
-   - Colors, spacing values
-   - Typography scale
-   - Border radius values
-
-3. **Constants**
-   - Board type definitions
-   - Hold state colors
-   - Grade mappings
+```
+packages/shared-logic/
+├── src/
+│   ├── queue/
+│   │   ├── reducer.ts       # Queue state reducer (from web)
+│   │   ├── actions.ts       # Action creators
+│   │   └── types.ts         # Queue types
+│   ├── board/
+│   │   ├── hold-states.ts   # HOLD_STATE_MAP constants
+│   │   ├── colors.ts        # Color encoding utilities
+│   │   └── config.ts        # Board configurations
+│   ├── bluetooth/
+│   │   └── protocol.ts      # Packet framing, encoding (platform-agnostic)
+│   ├── climb/
+│   │   ├── transformers.ts  # Climb data utilities
+│   │   └── validators.ts    # Zod schemas
+│   └── index.ts
+└── package.json
+```
 
-### Create New Shared Package
+### Adapt from Web
 
-Consider creating `packages/shared-logic` for:
-- Queue reducer
-- Climb utilities
-- Board configuration logic
-- Common validation schemas
+| Source | Adaptation Needed |
+|--------|-------------------|
+| `theme-config.ts` | Convert to Tamagui token format |
+| `graphql/operations.ts` | Already portable, just import |
+| URL slug encoding | Adapt for deep linking |
 
 ---
 
 ## Components Requiring Rebuild
 
-### UI Components (Complete Rewrite)
-
-| Web Component | Mobile Equivalent |
-|--------------|-------------------|
-| Ant Design components | Tamagui/RN Paper components |
-| Search Drawer | Bottom Sheet with filters |
-| Queue List | FlatList with gestures |
-| Board Renderer | react-native-svg based |
-| Climb Card | Native card component |
-| Settings screens | Native settings UI |
-| Auth forms | Native form components |
-
-### Platform-Specific Features
-
-| Feature | Web Technology | Mobile Technology |
-|---------|---------------|-------------------|
-| Bluetooth | Web Bluetooth API | react-native-ble-plx |
-| Offline storage | IndexedDB | expo-sqlite / AsyncStorage |
-| Deep linking | Next.js routing | React Navigation deep links |
-| Push notifications | N/A | expo-notifications |
-| Haptic feedback | N/A | expo-haptics |
-| Screen wake lock | Wake Lock API | expo-keep-awake |
+### UI Layer (Complete Rewrite)
+
+| Web (Ant Design) | Mobile (Tamagui) |
+|------------------|------------------|
+| `<Drawer>` search | `<Sheet>` bottom sheet |
+| `<List>` queue | `<FlatList>` with drag handles |
+| `<Card>` climb | Custom `<ClimbCard>` |
+| `<Modal>` dialogs | `<Dialog>` or `<Sheet>` |
+| `<Form>` inputs | Tamagui `<Input>`, `<Select>` |
+| `<Tabs>` navigation | Expo Router tab layout |
+
+### Platform Features
+
+| Feature | Implementation |
+|---------|----------------|
+| Bluetooth | `react-native-ble-plx` with custom hooks |
+| Local storage | `expo-sqlite` with Drizzle ORM |
+| Deep linking | Expo Router linking config |
+| Push notifications | `expo-notifications` |
+| Haptics | `expo-haptics` on actions |
+| Wake lock | `expo-keep-awake` during climbing |
+| Background fetch | `expo-background-fetch` for sync |
 
 ---
 
-## Feature Implementation Plan
-
-### Core Features (MVP)
-
-1. **Board Visualization**
-   - SVG rendering with react-native-svg
-   - Touch handling for hold selection
-   - Zoom/pan with react-native-gesture-handler
-   - Mirroring support
-
-2. **Bluetooth Connection**
-   - Device discovery and pairing
-   - LED control protocol (port existing logic)
-   - Connection state management
-   - Background reconnection
-
-3. **Climb Search**
-   - Filter by grade, quality, ascents
-   - Setter search
-   - Sort options
-   - Infinite scroll results
-
-4. **Queue Management**
-   - Add/remove climbs
-   - Reorder with drag-and-drop
-   - Set current climb
-   - Queue persistence
-
-5. **Authentication**
-   - Aurora Climbing login
-   - Secure token storage
-   - Session management
-
-### Enhanced Features (Post-MVP)
-
-1. **Party Mode**
-   - Session creation/joining
-   - Real-time sync
-   - User presence
-   - Leader controls
-
-2. **Logbook**
-   - Track ascents and attempts
-   - Progress statistics
-   - History view
-
-3. **Favorites & Playlists**
-   - Save favorite climbs
-   - Create/manage playlists
-   - Quick access
-
-4. **Offline Mode**
-   - Cache climb data
-   - Queue offline changes
-   - Sync when connected
-
-5. **Push Notifications**
-   - Party invitations
-   - Queue updates when app backgrounded
-
----
-
-## Technical Architecture
-
-### Package Structure
+## Package Structure
 
 ```
 boardsesh/
 ├── packages/
-│   ├── web/                    # Existing Next.js app
-│   ├── backend/                # Existing GraphQL backend
-│   ├── shared-schema/          # GraphQL schema + types
-│   ├── db/                     # Database schema
-│   ├── shared-logic/           # NEW: Shared business logic
+│   ├── web/                    # Existing (unchanged)
+│   ├── backend/                # Existing (unchanged)
+│   ├── shared-schema/          # Existing (unchanged)
+│   ├── db/                     # Existing (unchanged)
+│   │
+│   ├── shared-logic/           # NEW: Extracted business logic
 │   │   ├── src/
-│   │   │   ├── queue/          # Queue reducer, actions
-│   │   │   ├── board/          # Board config, hold mappings
-│   │   │   ├── climb/          # Climb utilities
-│   │   │   └── index.ts
-│   │   └── package.json
+│   │   │   ├── queue/
+│   │   │   ├── board/
+│   │   │   ├── bluetooth/
+│   │   │   └── climb/
+│   │   ├── package.json
+│   │   └── tsconfig.json
+│   │
 │   └── mobile/                 # NEW: React Native app
-│       ├── app/                # Expo Router app directory
-│       │   ├── (tabs)/         # Tab navigation
-│       │   ├── (auth)/         # Auth screens
-│       │   ├── board/          # Board screens
-│       │   ├── party/          # Party mode screens
+│       ├── app/                # Expo Router screens
+│       │   ├── (tabs)/
+│       │   │   ├── index.tsx           # Home/Board
+│       │   │   ├── search.tsx          # Search climbs
+│       │   │   ├── queue.tsx           # Queue management
+│       │   │   └── profile.tsx         # User profile
+│       │   ├── (auth)/
+│       │   │   ├── login.tsx
+│       │   │   └── register.tsx
+│       │   ├── party/
+│       │   │   ├── [sessionId].tsx     # Party session
+│       │   │   └── create.tsx          # Create session
+│       │   ├── climb/
+│       │   │   └── [uuid].tsx          # Climb detail
 │       │   └── _layout.tsx
+│       │
 │       ├── components/
-│       │   ├── board/          # Board renderer
-│       │   ├── queue/          # Queue components
-│       │   ├── search/         # Search UI
-│       │   ├── common/         # Shared components
-│       │   └── bluetooth/      # Bluetooth controls
-│       ├── hooks/
-│       │   ├── useBluetooth.ts
-│       │   ├── useQueue.ts
-│       │   └── useParty.ts
-│       ├── services/
-│       │   ├── bluetooth/      # BLE protocol
-│       │   ├── graphql/        # GraphQL client
-│       │   └── storage/        # Local storage
+│       │   ├── board/
+│       │   │   ├── BoardRenderer.tsx   # SVG board display
+│       │   │   ├── HoldOverlay.tsx     # Interactive holds
+│       │   │   └── BoardControls.tsx   # Zoom, mirror
+│       │   ├── bluetooth/
+│       │   │   ├── ScanModal.tsx
+│       │   │   ├── ConnectionStatus.tsx
+│       │   │   └── SendButton.tsx
+│       │   ├── party/
+│       │   │   ├── UserList.tsx
+│       │   │   ├── SessionControls.tsx
+│       │   │   └── JoinSheet.tsx
+│       │   ├── queue/
+│       │   │   ├── QueueList.tsx
+│       │   │   ├── QueueItem.tsx
+│       │   │   └── CurrentClimb.tsx
+│       │   ├── search/
+│       │   │   ├── SearchSheet.tsx
+│       │   │   ├── FilterControls.tsx
+│       │   │   └── ResultsList.tsx
+│       │   └── common/
+│       │       ├── ClimbCard.tsx
+│       │       ├── GradeDisplay.tsx
+│       │       └── LoadingState.tsx
+│       │
 │       ├── contexts/
 │       │   ├── AuthContext.tsx
+│       │   ├── BluetoothContext.tsx
 │       │   ├── QueueContext.tsx
-│       │   └── BluetoothContext.tsx
+│       │   └── PartyContext.tsx
+│       │
+│       ├── hooks/
+│       │   ├── useBluetooth.ts
+│       │   ├── usePartySession.ts
+│       │   ├── useClimbSearch.ts
+│       │   └── useQueue.ts
+│       │
+│       ├── services/
+│       │   ├── bluetooth/
+│       │   │   ├── BleManager.ts
+│       │   │   └── BoardProtocol.ts
+│       │   ├── graphql/
+│       │   │   ├── client.ts
+│       │   │   └── wsClient.ts
+│       │   └── storage/
+│       │       ├── database.ts
+│       │       └── secureStore.ts
+│       │
 │       ├── theme/
-│       │   └── tokens.ts       # Design tokens
-│       ├── app.json            # Expo config
+│       │   └── tamagui.config.ts
+│       │
+│       ├── app.json
+│       ├── eas.json
 │       ├── package.json
 │       └── tsconfig.json
 ```
 
-### Data Flow Architecture
+---
 
-```
-┌─────────────────────────────────────────────────────────────┐
-│                      Mobile App                              │
-├─────────────────────────────────────────────────────────────┤
-│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
-│  │   Screens   │  │  Components │  │   Context Providers │  │
-│  │  (Expo      │──│  (Tamagui/  │──│  - Auth             │  │
-│  │   Router)   │  │   RN Paper) │  │  - Queue            │  │
-│  └─────────────┘  └─────────────┘  │  - Bluetooth        │  │
-│                                     │  - Party            │  │
-│                                     └─────────────────────┘  │
-│         │                                    │               │
-│         ▼                                    ▼               │
-│  ┌─────────────┐                    ┌─────────────────────┐  │
-│  │   Hooks     │                    │   Local Storage     │  │
-│  │  - useQueue │                    │   - SQLite/         │  │
-│  │  - useBLE   │                    │     AsyncStorage    │  │
-│  └─────────────┘                    └─────────────────────┘  │
-│         │                                                    │
-└─────────┼────────────────────────────────────────────────────┘
-          │
-          ▼
-┌─────────────────────────────────────────────────────────────┐
-│                   Backend (Unchanged)                        │
-├─────────────────────────────────────────────────────────────┤
-│  ┌─────────────────┐    ┌─────────────────┐                 │
-│  │  GraphQL HTTP   │    │  GraphQL WS     │                 │
-│  │  (Queries/      │    │  (Subscriptions)│                 │
-│  │   Mutations)    │    │                 │                 │
-│  └────────┬────────┘    └────────┬────────┘                 │
-│           │                      │                           │
-│           ▼                      ▼                           │
-│  ┌─────────────────────────────────────────────────────────┐│
-│  │              GraphQL Yoga Server                         ││
-│  │              + Room Manager + PubSub                     ││
-│  └─────────────────────────────────────────────────────────┘│
-│                          │                                   │
-│                          ▼                                   │
-│  ┌───────────────┐  ┌───────────────┐                       │
-│  │  PostgreSQL   │  │    Redis      │                       │
-│  │  (Data)       │  │  (Pub/Sub)    │                       │
-│  └───────────────┘  └───────────────┘                       │
-└─────────────────────────────────────────────────────────────┘
-```
+## Implementation Milestones
 
-### Bluetooth Architecture
+### Milestone 0: Technical Validation (2-3 weeks)
 
-```
-┌─────────────────────────────────────────────────────────────┐
-│                   BluetoothContext                           │
-├─────────────────────────────────────────────────────────────┤
-│  State:                                                      │
-│  - connectionState: 'disconnected' | 'scanning' |           │
-│                     'connecting' | 'connected'               │
-│  - device: Device | null                                     │
-│  - error: Error | null                                       │
-├─────────────────────────────────────────────────────────────┤
-│  Actions:                                                    │
-│  - startScan()                                               │
-│  - connect(deviceId)                                         │
-│  - disconnect()                                              │
-│  - sendClimb(frames, holdStateMap)                          │
-│  - clearBoard()                                              │
-└─────────────────────────────────────────────────────────────┘
-          │
-          ▼
-┌─────────────────────────────────────────────────────────────┐
-│              BluetoothService (react-native-ble-plx)         │
-├─────────────────────────────────────────────────────────────┤
-│  - BleManager instance                                       │
-│  - Device scanning with Aurora UUID filter                   │
-│  - GATT service/characteristic discovery                     │
-│  - Write commands with chunking (20 byte limit)             │
-│  - Connection monitoring and auto-reconnect                  │
-└─────────────────────────────────────────────────────────────┘
-          │
-          ▼
-┌─────────────────────────────────────────────────────────────┐
-│                  Bluetooth Protocol                          │
-│         (Port from web: board-bluetooth-control/)            │
-├─────────────────────────────────────────────────────────────┤
-│  - Nordic UART Service UUID: 6e400001-...                   │
-│  - Write Characteristic: 6e400002-...                        │
-│  - Packet framing: FIRST(82), MIDDLE(81), LAST(83)          │
-│  - Color encoding: RGB to 8-bit                              │
-│  - Position encoding                                         │
-└─────────────────────────────────────────────────────────────┘
-```
+> **Goal:** Prove feasibility of high-risk components before committing to full build
 
----
+**Validation Targets:**
 
-## Implementation Phases
+| Component | Validation Criteria | Risk Level |
+|-----------|---------------------|------------|
+| Bluetooth | Connect to real board, send LED command | 🔴 High |
+| WebSocket | Establish graphql-ws connection, receive subscription | 🟡 Medium |
+| SVG Rendering | Render full board with 200+ holds, smooth zoom | 🟡 Medium |
+| Monorepo | shared-logic imports work in Expo | 🟢 Low |
 
-### Phase 1: Foundation (4-6 weeks)
+**Deliverables:**
+- [ ] Minimal Expo app with dev build
+- [ ] Connect to Kilter/Tension board via BLE
+- [ ] Send one climb's LED data successfully
+- [ ] WebSocket subscription receives queue updates
+- [ ] Board SVG renders with pinch-zoom
+- [ ] Shared-logic package imports work
+
+**Exit Criteria:** All validation targets pass on both iOS and Android physical devices
+
+---
+
+### Milestone 1: Foundation + Real-time Core (3-4 weeks)
 
-**Goals:** Project setup, core infrastructure, basic navigation
+> **Goal:** Establish app foundation with WebSocket infrastructure as first-class citizen
 
 **Tasks:**
 - [ ] Initialize Expo project with TypeScript
-- [ ] Set up monorepo integration (npm workspaces)
-- [ ] Configure React Navigation with Expo Router
-- [ ] Create shared-logic package, extract queue reducer
-- [ ] Set up Tamagui or React Native Paper with theme tokens
-- [ ] Implement GraphQL client (HTTP + WebSocket)
-- [ ] Create authentication flow (login, secure storage)
-- [ ] Build basic navigation structure (tabs, stack)
+- [ ] Configure monorepo integration (npm workspaces)
+- [ ] Set up Tamagui with design tokens from web
+- [ ] Create `shared-logic` package, extract queue reducer
+- [ ] Implement authentication flow
+  - [ ] Aurora login form
+  - [ ] Secure token storage (expo-secure-store)
+  - [ ] Auth context provider
+- [ ] Build GraphQL infrastructure
+  - [ ] HTTP client for queries/mutations
+  - [ ] WebSocket client for subscriptions
+  - [ ] Connection state management
+  - [ ] Automatic reconnection with backoff
+- [ ] Create tab navigation structure
+- [ ] Build placeholder screens
+
+**Validation Checkpoint:**
+- [ ] User can log in with Aurora credentials
+- [ ] WebSocket connects and stays connected
+- [ ] Subscription receives test events
+- [ ] App handles network loss gracefully
 
-**Deliverables:**
-- Working app skeleton
-- User can log in
-- Navigation between placeholder screens
+---
 
-### Phase 2: Board Visualization (3-4 weeks)
+### Milestone 2: Party Mode - The Differentiator (3-4 weeks)
 
-**Goals:** Render climbing board, display climbs
+> **Goal:** Deliver real-time collaboration early as key feature validation
 
 **Tasks:**
-- [ ] Port SVG board renderer to react-native-svg
-- [ ] Implement hold rendering with state colors
-- [ ] Add touch handling for hold selection
-- [ ] Implement pinch-to-zoom and pan
-- [ ] Create climb card component
-- [ ] Build climb detail view
-- [ ] Add mirroring support
+- [ ] Implement party session management
+  - [ ] Create session with board configuration
+  - [ ] Join via session ID or deep link
+  - [ ] Leave session cleanup
+- [ ] Build real-time queue sync
+  - [ ] Port queue reducer to shared-logic
+  - [ ] Subscribe to `queueUpdates`
+  - [ ] Handle all delta event types
+  - [ ] Optimistic updates with correlation tracking
+- [ ] Create party UI components
+  - [ ] User presence list with avatars
+  - [ ] Leader indicator
+  - [ ] Session controls (end, transfer leadership)
+  - [ ] Connection status indicator
+- [ ] Implement session events
+  - [ ] Subscribe to `sessionUpdates`
+  - [ ] User joined/left notifications
+  - [ ] Leader change handling
+- [ ] Deep linking for session invites
+  - [ ] `boardsesh://party/join/{sessionId}`
+  - [ ] Universal links for web fallback
+
+**Validation Checkpoint:**
+- [ ] Two devices can join same session
+- [ ] Queue changes sync in <500ms
+- [ ] User presence updates in real-time
+- [ ] Session survives app backgrounding
+- [ ] Deep link opens correct session
 
-**Deliverables:**
-- Board displays correctly with holds lit up
-- Can view climb details
-- Touch interactions work smoothly
+---
 
-### Phase 3: Bluetooth Integration (3-4 weeks)
+### Milestone 3: Board Visualization (3-4 weeks)
 
-**Goals:** Connect to board hardware, control LEDs
+> **Goal:** Interactive board display with full touch support
 
 **Tasks:**
-- [ ] Set up react-native-ble-plx with Expo dev build
-- [ ] Implement device scanning with Aurora filter
-- [ ] Create connection management (connect, disconnect, reconnect)
-- [ ] Port Bluetooth protocol (packet framing, color encoding)
-- [ ] Build Bluetooth UI (scan modal, connection status)
-- [ ] Add screen wake lock (expo-keep-awake)
-- [ ] Test on physical devices with actual boards
+- [ ] Port SVG board renderer
+  - [ ] Convert web SVG to react-native-svg
+  - [ ] Render board background image
+  - [ ] Render hold overlays with state colors
+- [ ] Implement touch interactions
+  - [ ] Pinch-to-zoom with react-native-gesture-handler
+  - [ ] Pan/scroll when zoomed
+  - [ ] Hold tap detection
+  - [ ] Double-tap to reset zoom
+- [ ] Build climb display
+  - [ ] Current climb visualization
+  - [ ] Hold state colors (start, hand, foot, finish)
+  - [ ] Mirroring support
+- [ ] Create climb info components
+  - [ ] Climb card (name, grade, setter, stats)
+  - [ ] Climb detail modal
+  - [ ] Grade display with accuracy
+
+**Validation Checkpoint:**
+- [ ] Board renders all holds correctly
+- [ ] Zoom/pan is smooth (60fps)
+- [ ] Hold colors match web exactly
+- [ ] Mirrored climbs display correctly
 
-**Deliverables:**
-- Can discover and connect to board
-- Sending climb lights up correct holds
-- Connection survives app backgrounding
+---
 
-### Phase 4: Search & Queue (3-4 weeks)
+### Milestone 4: Bluetooth Integration (3-4 weeks)
 
-**Goals:** Find climbs, manage queue
+> **Goal:** Connect to hardware and control LEDs
 
 **Tasks:**
-- [ ] Build search UI (filters, sort options)
-- [ ] Implement infinite scroll results
-- [ ] Port queue reducer to shared-logic
-- [ ] Create queue list with drag-to-reorder
-- [ ] Add climb to queue functionality
-- [ ] Implement current climb selection
-- [ ] Local queue persistence
+- [ ] Set up react-native-ble-plx
+  - [ ] Configure Expo dev build with native modules
+  - [ ] Request permissions (iOS/Android differences)
+  - [ ] Handle permission denied states
+- [ ] Implement device discovery
+  - [ ] Scan with Aurora service UUID filter
+  - [ ] Display discovered devices
+  - [ ] Remember last connected device
+- [ ] Build connection management
+  - [ ] Connect with timeout handling
+  - [ ] Monitor connection state
+  - [ ] Auto-reconnect on disconnect
+  - [ ] Background connection maintenance
+- [ ] Port Bluetooth protocol
+  - [ ] Extract to shared-logic (platform-agnostic)
+  - [ ] Packet framing (FIRST/MIDDLE/LAST)
+  - [ ] Color encoding (RGB to 8-bit)
+  - [ ] Position encoding
+- [ ] Create Bluetooth UI
+  - [ ] Scan modal with device list
+  - [ ] Connection status in header
+  - [ ] Send to board button
+  - [ ] Clear board action
+- [ ] Screen wake lock during session
+
+**Validation Checkpoint:**
+- [ ] Discovers Kilter and Tension boards
+- [ ] Connects reliably on iOS and Android
+- [ ] Sending climb lights correct holds
+- [ ] Reconnects after Bluetooth toggle
+- [ ] Works with screen locked (wake lock)
 
-**Deliverables:**
-- Full search functionality
-- Queue management works
-- Queue persists between sessions
+---
 
-### Phase 5: Party Mode (3-4 weeks)
+### Milestone 5: Search & Queue Management (3-4 weeks)
 
-**Goals:** Real-time multi-user sessions
+> **Goal:** Find climbs and manage local queue
 
 **Tasks:**
-- [ ] Implement WebSocket subscription handling
-- [ ] Port party session logic
-- [ ] Create/join session UI
-- [ ] User presence display
-- [ ] Leader controls
-- [ ] Queue sync between users
-- [ ] Handle connection failures gracefully
+- [ ] Build search interface
+  - [ ] Bottom sheet with filters
+  - [ ] Grade range slider
+  - [ ] Quality/stars filter
+  - [ ] Ascents minimum filter
+  - [ ] Setter name autocomplete
+  - [ ] Sort options
+- [ ] Implement search API integration
+  - [ ] Infinite scroll with React Query
+  - [ ] Debounced search input
+  - [ ] Result caching
+- [ ] Create queue management
+  - [ ] Queue list with drag-to-reorder
+  - [ ] Add from search results
+  - [ ] Remove with swipe
+  - [ ] Set as current climb
+  - [ ] Clear queue action
+- [ ] Local persistence
+  - [ ] Store queue in SQLite
+  - [ ] Restore on app launch
+  - [ ] Sync with party session
+
+**Validation Checkpoint:**
+- [ ] Search returns correct results
+- [ ] Filters work as expected
+- [ ] Drag reorder is smooth
+- [ ] Queue persists across app restarts
+- [ ] Queue syncs with party when connected
 
-**Deliverables:**
-- Can create and join party sessions
-- Real-time queue sync works
-- Multiple users collaborate successfully
+---
 
-### Phase 6: Logbook & Progress (2-3 weeks)
+### Milestone 6: Logbook & Progress (2-3 weeks)
 
-**Goals:** Track climbing progress
+> **Goal:** Track climbing achievements
 
 **Tasks:**
-- [ ] Implement tick tracking (ascents, attempts)
-- [ ] Build logbook view
+- [ ] Implement tick tracking
+  - [ ] Log ascent from climb view
+  - [ ] Log attempt
+  - [ ] Sync with server
+- [ ] Build logbook UI
+  - [ ] History list by date
+  - [ ] Filter by board/grade
+  - [ ] Climb detail from history
 - [ ] Add progress statistics
-- [ ] Create history timeline
-- [ ] Sync with server
+  - [ ] Grades climbed chart
+  - [ ] Attempts vs sends ratio
+  - [ ] Streak tracking
 
-**Deliverables:**
-- Can log ascents and attempts
-- View climbing history
-- Stats display correctly
+**Validation Checkpoint:**
+- [ ] Ticks save and sync
+- [ ] History displays correctly
+- [ ] Stats calculate accurately
+
+---
 
-### Phase 7: Polish & Launch Prep (2-3 weeks)
+### Milestone 7: Polish & Launch (2-3 weeks)
 
-**Goals:** Production readiness
+> **Goal:** Production readiness and app store submission
 
 **Tasks:**
 - [ ] Performance optimization
-- [ ] Error handling and crash reporting (Sentry)
-- [ ] Offline mode improvements
-- [ ] App store assets (icons, screenshots)
-- [ ] Privacy policy, terms of service
+  - [ ] Profile and fix slow renders
+  - [ ] Optimize SVG rendering
+  - [ ] Reduce bundle size
+- [ ] Error handling
+  - [ ] Sentry integration
+  - [ ] User-friendly error messages
+  - [ ] Crash recovery
+- [ ] Offline improvements
+  - [ ] Graceful degradation
+  - [ ] Offline queue edits
+  - [ ] Sync on reconnect
+- [ ] App store preparation
+  - [ ] App icons (all sizes)
+  - [ ] Splash screen
+  - [ ] Screenshots for store listings
+  - [ ] App descriptions
+  - [ ] Privacy policy
+  - [ ] Terms of service
 - [ ] Beta testing
+  - [ ] TestFlight distribution
+  - [ ] Play Store internal testing
+  - [ ] Gather feedback
 - [ ] App store submission
 
-**Deliverables:**
-- Apps submitted to App Store and Play Store
-- Production-ready builds
+**Validation Checkpoint:**
+- [ ] No crashes in beta testing
+- [ ] Performance targets met
+- [ ] App store review passed
 
 ---
 
-## Risk Assessment
+## Validation Strategy
 
-### Technical Risks
+### Continuous Validation Practices
 
-| Risk | Likelihood | Impact | Mitigation |
-|------|------------|--------|------------|
-| BLE protocol differences between platforms | Medium | High | Early testing on both iOS/Android with real hardware |
-| SVG performance with complex boards | Medium | Medium | Profile early, consider Skia if needed |
-| WebSocket reliability in mobile context | Low | High | Robust reconnection logic, offline queue |
-| Expo limitations requiring eject | Low | Medium | Use dev builds from start, evaluate native modules early |
+| Practice | Frequency | Purpose |
+|----------|-----------|---------|
+| Physical device testing | Daily | Catch platform-specific issues early |
+| Bluetooth hardware tests | Weekly | Verify protocol compatibility |
+| Party mode multi-device | Per milestone | Ensure real-time sync works |
+| Performance profiling | Per milestone | Catch regressions |
+| Beta user feedback | Milestones 5-7 | Real-world validation |
 
-### Resource Risks
+### Device Test Matrix
+
+| Platform | Devices | Priority |
+|----------|---------|----------|
+| iOS | iPhone 12+, iPhone SE | High |
+| Android | Pixel 6+, Samsung Galaxy S21+ | High |
+| Android | Budget Android (Redmi, etc.) | Medium |
+
+### Validation Gates
+
+Each milestone has explicit validation checkpoints. **Do not proceed to next milestone until all checkpoints pass.**
+
+---
+
+## Risk Assessment
+
+### Technical Risks
 
 | Risk | Likelihood | Impact | Mitigation |
 |------|------------|--------|------------|
-| Underestimated UI rebuild effort | Medium | High | Start with core screens, iterate |
-| Testing across device variety | Medium | Medium | Establish device test matrix early |
-| App store approval delays | Medium | Low | Submit early, be prepared for review feedback |
+| BLE differences iOS vs Android | High | High | Milestone 0 validates both platforms |
+| WebSocket reliability on mobile | Medium | High | Robust reconnection in Milestone 1 |
+| SVG performance with many holds | Medium | Medium | Profile in Milestone 3, fallback to Skia |
+| Background Bluetooth on iOS | Medium | Medium | Test extensively, document limitations |
 
-### Timeline Risks
+### Schedule Risks
 
 | Risk | Likelihood | Impact | Mitigation |
 |------|------------|--------|------------|
-| Bluetooth debugging takes longer | High | Medium | Allocate buffer time, test on physical devices early |
-| Feature creep from web parity expectations | Medium | High | Define MVP strictly, communicate tradeoffs |
+| Milestone 0 fails validation | Low | Critical | Early validation prevents wasted effort |
+| BLE debugging takes longer | High | Medium | Buffer time built into Milestone 4 |
+| App store rejection | Medium | Low | Follow guidelines, submit early |
 
 ---
 
 ## Success Criteria
 
-### MVP Success Metrics
+### MVP Definition
 
-- [ ] App runs on iOS 15+ and Android 10+
-- [ ] Can connect to Kilter/Tension boards via Bluetooth
-- [ ] Can search, view, and send climbs to board
-- [ ] Queue management works offline and online
-- [ ] Party mode supports 2+ users simultaneously
-- [ ] App Store and Play Store approved
+The MVP includes Milestones 0-5:
+- ✅ Bluetooth board connection
+- ✅ Real-time party mode
+- ✅ Board visualization
+- ✅ Climb search
+- ✅ Queue management
+
+Logbook (Milestone 6) and polish (Milestone 7) complete the v1.0 release.
 
 ### Performance Targets
 
-- App launch to interactive: < 2 seconds
-- Board render time: < 500ms
-- Bluetooth connection time: < 5 seconds
-- Search response time: < 1 second
+| Metric | Target |
+|--------|--------|
+| App cold start | < 2 seconds |
+| Board render | < 500ms |
+| BLE connection | < 5 seconds |
+| Search response | < 1 second |
+| Queue sync latency | < 500ms |
+| Frame rate | 60fps during interactions |
+
+### Platform Requirements
+
+| Platform | Minimum Version |
+|----------|-----------------|
+| iOS | 15.0+ |
+| Android | API 29 (Android 10)+ |
 
 ---
 
 ## Appendix
 
-### Recommended Libraries
+### Dependencies
 
 ```json
 {
   "dependencies": {
     "expo": "~52.0.0",
+    "expo-router": "~4.0.0",
     "react-native": "0.76.x",
     "react": "18.3.x",
 
-    "expo-router": "~4.0.0",
-    "@react-navigation/native": "^7.0.0",
-
     "tamagui": "^1.100.0",
     "@tamagui/config": "^1.100.0",
 
@@ -624,46 +575,64 @@ boardsesh/
     "expo-sqlite": "~15.0.0",
     "expo-keep-awake": "~14.0.0",
     "expo-haptics": "~14.0.0",
+    "expo-notifications": "~0.29.0",
 
     "@tanstack/react-query": "^5.0.0",
-    "zod": "^3.22.0"
+    "zod": "^3.22.0",
+    "react-hook-form": "^7.50.0",
+    "@hookform/resolvers": "^3.3.0"
   }
 }
 ```
 
-### iOS Bluetooth Permissions (Info.plist)
+### Platform Permissions
 
+**iOS (Info.plist):**
 ```xml
 <key>NSBluetoothAlwaysUsageDescription</key>
-<string>Boardsesh needs Bluetooth to connect to your climbing board and control the LED holds.</string>
+<string>Connect to your climbing board to control LED holds</string>
 <key>NSBluetoothPeripheralUsageDescription</key>
-<string>Boardsesh needs Bluetooth to connect to your climbing board.</string>
+<string>Connect to your climbing board</string>
 <key>UIBackgroundModes</key>
 <array>
   <string>bluetooth-central</string>
 </array>
 ```
 
-### Android Bluetooth Permissions (AndroidManifest.xml)
-
+**Android (AndroidManifest.xml):**
 ```xml
-<uses-permission android:name="android.permission.BLUETOOTH" />
-<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
 <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
 <uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
 <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
 ```
 
----
+### Deep Linking Configuration
 
-## Next Steps
+```json
+{
+  "expo": {
+    "scheme": "boardsesh",
+    "web": {
+      "bundler": "metro"
+    },
+    "plugins": [
+      [
+        "expo-router",
+        {
+          "origin": "https://boardsesh.com"
+        }
+      ]
+    ]
+  }
+}
+```
 
-1. **Validate approach** - Review this plan with stakeholders
-2. **Set up mobile package** - Initialize Expo project in monorepo
-3. **Proof of concept** - Build BLE connection + basic board render
-4. **Iterate** - Begin Phase 1 implementation
+Supported deep links:
+- `boardsesh://party/join/{sessionId}` - Join party session
+- `boardsesh://climb/{uuid}` - Open climb detail
+- `boardsesh://board/{boardName}/{layoutId}/{sizeId}/{setIds}/{angle}` - Open board config
 
 ---
 
-*Document created: January 2026*
+*Document version: 2.0*
 *Last updated: January 2026*