# 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
```bash
# Start Expo on port 8081 with iPhone 16 Pro Max
IOS_SIMULATOR_UDID=6BB240A2-0F2F-41E4-B568-9FFAF9B7FBA2 npx expo start --port 8081 --ios
```