smoa/docs/reference/PLATFORM-REQUIREMENTS.md

# SMOA platform requirements – Android, iOS, Web

This document defines **required targets** and **supported platforms** for SMOA: **Android** (primary), **iOS** (last three generations), and **Web Dapp** (Desktop/Laptop including touch). All platforms use the same backend API contract.

---

## 1. Required target (all platforms)

| Aspect | Required minimum |
|--------|-------------------|
| **Backend API** | REST `/api/v1` (sync, pull, delete); JSON request/response; optional X-API-Key auth; CORS for web. |
| **Sync contract** | POST sync (directory, order, evidence, credential, report); DELETE for sync delete; GET for pull; `SyncResponse` with success, itemId, serverTimestamp, conflict, remoteData (base64 when conflict). |
| **Auth** | API key via header `X-API-Key` or query `api_key`; when key is set, all `/api/v1/*` require it. |
| **Network** | HTTPS in production; same-origin or configured CORS for web. |

---

## 2. Android (primary)

| Aspect | Required / supported |
|--------|----------------------|
| **OS** | Android 10 (API 29) or higher; primary device Android 16 (API 36). |
| **App SDK** | minSdk 24, targetSdk 34 (forward compatible on 16). |
| **Device** | Primary: Samsung Galaxy Z Fold5 (SM-F946U1) or equivalent foldable with 4G/5G. |
| **Features** | Sync (push/pull/delete), foldable UI, 4G/5G/5G MW detection, WebRTC-ready, VPN-aware routing, biometric. |
| **Details** | See [DEVICE-COMPATIBILITY.md](DEVICE-COMPATIBILITY.md). |

---

## 3. iOS (last three generations)

SMOA supports **iOS clients** for the same backend; an iOS app is a separate codebase (e.g. Swift/SwiftUI or shared logic via KMP).

| Aspect | Required / supported |
|--------|----------------------|
| **OS** | **iOS 15, iOS 16, iOS 17** (last three major generations). Minimum deployment target: **iOS 15.0**. |
| **Devices** | iPhone and iPad: models that run iOS 15+ (e.g. iPhone 6s and later, iPad Air 2 and later, and subsequent generations). |
| **Auth** | Same as backend: `X-API-Key` header or `api_key` query; store key in Keychain. |
| **Sync** | Same REST contract: POST to `/api/v1/sync/*`, DELETE to `/api/v1/sync/{resource}/{id}`, GET to `/api/v1/directory`, `/api/v1/orders`, etc. |
| **Data** | Decode `SyncResponse.remoteData` as base64 when `conflict == true`; use same DTO field names as backend. |
| **Networking** | URLSession or Alamofire; certificate pinning optional; respect rate limit (429). |
| **Offline** | Queue sync when offline; retry when online; optional local persistence (Core Data / SwiftData). |
| **Touch** | Native touch; support pointer events where applicable (iPad). |
| **Gaps to implement** | iOS app project (Swift/SwiftUI or cross-platform); Keychain for API key; optional Face ID / Touch ID for app unlock. |

---

## 4. Web Dapp (Desktop / Laptop, including touch)

SMOA supports a **browser-based Web Dapp** for Desktop and Laptop, including **touch devices** (e.g. touch laptops, tablets in browser).

| Aspect | Required / supported |
|--------|----------------------|
| **Browsers** | Chrome, Firefox, Safari, Edge (current versions); Desktop and Laptop. |
| **Viewports** | Responsive layout: desktop (e.g. 1280px+), laptop (1024px+), and tablet/touch (768px+). |
| **Input** | Mouse + keyboard; **touch** (touchstart/touchend/pointer events) for touch laptops and tablets. |
| **Auth** | Same backend: `X-API-Key` header or `api_key` query; store in secure storage (e.g. sessionStorage for session, or secure cookie if served from same origin). |
| **Sync** | Same REST contract; use `fetch` or axios; CORS must allow the web origin (backend `smoa.cors.allowed-origins`). |
| **Data** | Same JSON DTOs; decode `remoteData` base64 when `conflict == true`. |
| **Offline** | Optional: Service Worker + Cache API; queue sync in IndexedDB/localStorage and flush when online. |
| **HTTPS** | Required in production; backend behind TLS; web app served over HTTPS. |
| **PWA (optional)** | Installable; optional offline shell; same API contract. |
| **Gaps to implement** | Web app codebase (e.g. React, Vue, Svelte); build and host; configure CORS for web origin. |

---

## 5. Backend support for all clients

The backend **already supports** Android, iOS, and Web:

| Feature | Backend | Android | iOS | Web |
|---------|---------|---------|-----|-----|
| **Sync POST** | ✅ | ✅ | Same contract | Same contract |
| **Sync DELETE** | ✅ | ✅ | Same contract | Same contract |
| **Pull GET** | ✅ | ✅ | Same contract | Same contract |
| **API key auth** | ✅ | ✅ | Same contract | Same contract |
| **CORS** | ✅ configurable | N/A | N/A | ✅ use allowed-origins |
| **Rate limit** | ✅ per key/IP | ✅ | Same | Same |
| **Health / info** | ✅ GET /health, GET /api/v1/info | ✅ | Same | Same |

- **CORS:** Set `smoa.cors.allowed-origins` to the web app origin(s) (e.g. `https://smoa.example.com`) when deploying the Web Dapp; use `*` only for dev if acceptable.
- **Discovery:** GET `/api/v1/info` returns endpoint list so any client (Android, iOS, Web) can discover sync, delete, and pull URLs.

---

## 6. Scaling (all platforms)

| Aspect | Scales with | Notes |
|--------|-------------|--------|
| **Concurrent devices** | Number of Android + iOS + Web clients | Backend rate limit and VM sizing; see [PROXMOX-VE-TEMPLATE-REQUIREMENTS.md](../infrastructure/PROXMOX-VE-TEMPLATE-REQUIREMENTS.md). |
| **Sync volume** | Entities per user, pull page size | Backend DB and disk; clients use since/limit on GET. |
| **Web origins** | Multiple Dapp domains | Add all origins to `smoa.cors.allowed-origins` (comma-separated). |

---

## 7. References

- [DEVICE-COMPATIBILITY.md](DEVICE-COMPATIBILITY.md) – Android device (Z Fold5) and app
- [REQUIREMENTS-ALIGNMENT.md](REQUIREMENTS-ALIGNMENT.md) – Frontend–backend contract and gaps
- [BACKEND-GAPS-AND-ROADMAP.md](../../backend/docs/BACKEND-GAPS-AND-ROADMAP.md) – Backend API and ops
- [PROXMOX-VE-TEMPLATE-REQUIREMENTS.md](../infrastructure/PROXMOX-VE-TEMPLATE-REQUIREMENTS.md) – Infra sizing