CGC 2026 Client

React Native iOS-first app for Smart Knee BLE pairing, workout sessions, and sensor-driven insights.

Screenshots · Getting Started · Architecture · Project Structure

---

Overview

CGC 2026 Client is an Expo Router mobile app focused on connecting to a Smart Knee device over BLE, collecting session data, and integrating with backend workout APIs. The app combines authenticated API workflows, real-time BLE streaming, and context-driven state composition.
It is currently implemented with an iOS-first BLE architecture (react-native-ble-plx) while still keeping Expo/React Native cross-platform structure.

---

Screenshots

---

Features

• BLE device management - Scan, pair, reconnect, and recover Smart Knee connections with iOS-specific handling.
• Workout and session flows - Load workout types/session history and run active workout screens with API-backed data.
• Sensor streaming pipeline - Stream sample data from BLE characteristics into app-level providers and services.
• Auth + secure token handling - Clerk authentication with secure token storage.
• CSV export tooling - Export captured sensor data through iOS export provider flows.

---

Tech Stack

Layer	Technology
Framework	React Native 0.79 + Expo SDK 53
Navigation	Expo Router (file-based routing)
State management	React Context + XState + React Query
BLE	react-native-ble-plx
API Client	Axios-based authenticated client
Auth	Clerk (@clerk/clerk-expo) + Expo Secure Store
Styling/UI	React Native StyleSheet + themed components
Language	TypeScript

---

Getting Started

Prerequisites

• Node.js 18+
• npm
• Xcode (for iOS Simulator or physical device builds)
• Optional: Android Studio (if you want Android simulator support)

Installation

npm install

Environment Variables

Create a .env file in the project root using .env.example.

EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY=
EXPO_PUBLIC_API_BASE_URL=

Running the app

# Start Expo dev server
npx expo start

You can also run native iOS builds directly:

npx expo run:ios --device
npx expo run:ios --device --configuration Release
npx expo run:ios --device --configuration Release --no-bundler
npx expo prebuild --clean && npx expo run:ios

Package scripts:

npm run start
npm run ios
npm run android
npm run web

Lint

npm run lint

Reset starter scaffold (optional)

npm run reset-project

This keeps the Expo starter reset behavior in case you still need it for experimentation.

---

Project Structure

client/
├── app/                    # Expo Router screens/routes
│   ├── (tabs)/             # Main tabbed navigation (home/activities/dev)
│   ├── workout/            # Workout detail routes
│   ├── session/            # Session detail routes
│   ├── bluetooth.tsx       # BLE device discovery/pair UI
│   └── _layout.tsx         # Root provider composition + stack routes
├── contexts/               # App-level providers (BLE, auth, storage, workout, export)
├── services/               # Domain services (knee device, battery, workout APIs)
├── hooks/                  # Reusable hooks (queries, theme, route guards)
├── components/             # UI and feature components
├── constants/              # BLE UUIDs, colors, environment config
├── lib/                    # Helper utilities (BLE connection helpers, auth client, math)
└── types/                  # Shared TypeScript types

---

Architecture

The app composes feature providers in app/_layout.tsx to create a clear top-down data and capability flow:

• QueryProvider for server state caching and async request orchestration.
• StorageProvider for persisted app/device keys.
• AuthProvider and AuthApiProvider for Clerk auth + authenticated API client.
• WorkoutAPIProvider for workout/session backend interactions.
• BLEProvider delegating to IOSBleProvider on iOS.
• KneeDeviceProvider, CalibrationProvider, BatteryProvider, and WorkoutProvider for hardware/session domain logic.

BLE state transitions are managed with XState in the iOS provider (idle -> scanning -> pairing -> connected) and wrapped with a type-safe context API for UI usage.

┌─────────────────────────────────────────────────────────────┐
│ UI Layer (Expo Router screens + feature components)         │
├─────────────────────────────────────────────────────────────┤
│ Context Layer (Auth, BLE, KneeDevice, Workout, Battery)     │
├─────────────────────────────────────────────────────────────┤
│ Services Layer (BLE service, workout API service, exports)  │
├─────────────────────────────────────────────────────────────┤
│ Platform + External (iOS BLE stack, Clerk, backend API)     │
└─────────────────────────────────────────────────────────────┘

---

Notes

• BLE functionality is iOS-first and relies on native capabilities unavailable in standard web runtime.
• For best validation of BLE flows, test on a physical iPhone with the target device nearby.
• Integrates with firmware via BLE and the server via REST APIs