WellNuo/CLAUDE.md

WellNuo - Project Architecture

API-First Architecture

IMPORTANT: This project uses an API-first approach. NO local storage for business data!

Key Principles

1. All beneficiary data comes from the remote API only

   • No AsyncStorage for beneficiaries
   • No local caching of beneficiary lists
   • Every CRUD operation goes through the WellNuo API

2. Single Source of Truth: WellNuo Backend

   • All beneficiary data is stored in Supabase via the backend
   • Changes are immediately persisted to the server
   • App always fetches fresh data on screen focus

API Endpoints

WellNuo API (Primary)

Base URL: https://wellnuo.smartlaunchhub.com/api

Method	Endpoint	Description
GET	/me/beneficiaries	List all beneficiaries for current user
GET	/me/beneficiaries/:id	Get single beneficiary details
POST	/me/beneficiaries	Create new beneficiary
PATCH	/me/beneficiaries/:id	Update beneficiary
DELETE	/me/beneficiaries/:id	Remove beneficiary access
GET	/me/profile	Get current user profile
PATCH	/me/profile	Update user profile (firstName, lastName, phone)

Authentication: Bearer token (JWT from /auth/login)

Legacy API (WebView Dashboard)

Base URL: https://eluxnetworks.net/function/well-api/api

Used only for:

• Developer Mode / WebView dashboard
• Real sensor data visualization (from NDK devices)

Data Flow

┌─────────────┐     ┌──────────────────┐     ┌─────────────┐
│  React App  │ ──▶ │  WellNuo Backend │ ──▶ │   Supabase  │
│  (Expo)     │ ◀── │  (Express.js)    │ ◀── │  (Postgres) │
└─────────────┘     └──────────────────┘     └─────────────┘

Database Schema

• users - User accounts (email, password hash)
• person_details - Beneficiary profiles (firstName, lastName, avatar, etc.)
• user_access - Links accessor_id → beneficiary_id with role (owner/viewer)
• subscriptions - Subscription status for beneficiaries
• devices - IoT devices linked to beneficiaries

What NOT to do

• ❌ Don't use localBeneficiaries from BeneficiaryContext for actual data
• ❌ Don't save beneficiary data to AsyncStorage
• ❌ Don't cache API responses locally for offline use
• ❌ Don't assume data is available without API call
• ❌ Don't save user profile data (name, phone) to SecureStore
• ❌ Don't use userName from SecureStore - it's legacy!

What TO do

• ✅ Always fetch fresh data via api.getAllBeneficiaries() or api.getWellNuoBeneficiary(id)
• ✅ Get user profile via api.getProfile(), update via api.updateProfile()
• ✅ Use useFocusEffect to reload data when screen gains focus
• ✅ Handle loading and error states for all API calls
• ✅ Show appropriate feedback on successful operations
• ✅ Only store in SecureStore: accessToken, userId, userEmail (technical auth data)

Development

Server Location

• Production: root@91.98.205.156:/var/www/wellnuo-api/
• PM2 process: wellnuo-api

Key Files

• services/api.ts - All API methods
• contexts/BeneficiaryContext.tsx - Beneficiary state management (current selection only)
• app/(tabs)/beneficiaries/ - Beneficiary screens

Running Locally

# Start Expo on port 8081 with iPhone 16 Pro Max
IOS_SIMULATOR_UDID=6BB240A2-0F2F-41E4-B568-9FFAF9B7FBA2 npx expo start --port 8081 --ios