5a8c26cf5d
- Backend: ShallowEtagHeaderFilter for /api/v1/*, API-VERSIONING.md, README (tenant, CORS, Flyway, ETag) - k8s: backend-deployment.yaml (Deployment, Service, Secret/ConfigMap) - Web: scaffold with directory pull, 304 handling, touch-friendly UI - Android 16: ANDROID-16-TARGET.md; BuildConfig STUN/signaling, SMOAApplication configures InfrastructureManager - Domain: CertificateManager revocation stub, ReportService signReports, ZeroTrust/ThreatDetection minimal docs - TODO.md and IMPLEMENTATION_STATUS.md updated; communications README for endpoint config Co-authored-by: Cursor <cursoragent@cursor.com>
102 lines
5.9 KiB
Markdown
102 lines
5.9 KiB
Markdown
# 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
|