smoa/docs/reference/DEVICE-COMPATIBILITY.md

# Device compatibility – Samsung Galaxy Z Fold5 (primary target)

This document describes SMOA compatibility with the **Samsung Galaxy Z Fold5** (model **SM-F946U1**) as the primary target device, and what has been done to ensure the app works correctly on it.

---

## Required target (mandatory minimum)

| Aspect | Required minimum |
|--------|-------------------|
| **Device** | Samsung Galaxy Z Fold5 (SM-F946U1) or equivalent (foldable, 4G/5G capable). |
| **OS** | Android 10 (API 29) or higher; primary target Android 16 (API 36). |
| **App SDK** | `minSdk 24`, `targetSdk 34` (forward compatible on Android 16). |
| **Network** | Cellular (4G LTE or 5G NR) and/or Wi‑Fi; optional dual SIM. |
| **Permissions** | INTERNET, ACCESS_NETWORK_STATE; RECORD_AUDIO, CAMERA for meetings; READ_BASIC_PHONE_STATE optional for 5G MW detection. |

Below minSdk 24 the app does not build. For full Android 16 behavior and testing, targetSdk 36 is recommended once the project upgrades the Android Gradle Plugin.

---

## Target device summary

| Attribute | Value |
|-----------|--------|
| **Device** | Samsung Galaxy Z Fold5 (SM-F946U1) |
| **OS** | Android 16, One UI 8.0 |
| **Cellular** | 4G LTE, 5G NR, 5G millimeter wave (5G MW) capable |
| **Connectivity** | Dual SIM (physical + eSIM), e.g. Dark Star + US Mobile |
| **Security** | SE for Android (Enforcing), Knox 3.12, DualDAR 1.8.0 |
| **Form factor** | Foldable (cover screen + inner large screen) |

## App compatibility measures

### 1. SDK and API level

- **Current:** `compileSdk = 34`, `targetSdk = 34`, `minSdk = 24` (see `buildSrc/.../AppConfig.kt`).
- **Android 16** uses **API level 36**. The app is **forward compatible**: it runs on Android 16 with existing targetSdk 34; the system applies compatibility behavior.
- **Recommendation for full Android 16 optimization:** When upgrading the project’s Android Gradle Plugin (e.g. to 8.9+), set `compileSdk = 36` and `targetSdk = 36` and test against Android 16.

### 2. Foldable support

- **FoldableStateManager** (`core/common`) tracks folded vs unfolded state using a 600 dp width threshold, suitable for Z Fold5 (narrow cover vs wide inner screen).
- **MainActivity** calls `foldableStateManager.updateFoldState(configuration)` in `onCreate` and **onConfigurationChanged**, so fold/unfold updates the UI without requiring an activity recreate when combined with manifest `configChanges`.
- **Manifest:** `MainActivity` declares  
  `android:configChanges="orientation|screenSize|smallestScreenSize|screenLayout"`  
  so that fold/unfold and size changes are delivered to `onConfigurationChanged` and the activity is not recreated unnecessarily.
- **MainScreen** receives `foldableStateManager` and can adapt layout (e.g. list/detail, panels) for folded vs unfolded.
- **PolicyManager** supports a “lock on fold” option for security when the device is folded.

### 3. 4G LTE, 5G, and 5G MW (smart routing)

- **ConnectivityManager** (`core/common`):
  - **getActiveTransportType()** – WIFI, CELLULAR, VPN, ETHERNET, UNKNOWN.
  - **getCellularGeneration()** – when transport is CELLULAR, returns LTE_4G, NR_5G, or NR_5G_MW.
- **Cellular generation logic:**
  - LTE → `LTE_4G`.
  - NR (5G) + `TelephonyDisplayInfo.overrideNetworkType == OVERRIDE_NETWORK_TYPE_NR_ADVANCED` (value 5) → **NR_5G_MW** (millimeter wave); otherwise → **NR_5G**.
- **Permissions:** `READ_BASIC_PHONE_STATE` is declared (optional) to improve accuracy of 4G/5G/5G MW detection on API 29+. Not required for basic connectivity.
- **Smart routing** (e.g. `MediaRoutingPolicy`, `NetworkPathSelector`) uses transport type and cellular generation to prefer 5G / 5G MW over 4G where appropriate.

### 4. Dual SIM / multi-carrier

- The app uses the system’s **default data network** and **active network capabilities** via `ConnectivityManager` and `NetworkCapabilities`. It does not bind to a specific subscription ID.
- On dual-SIM devices (e.g. physical SIM + eSIM), the system chooses the active data subscription; SMOA’s connectivity and cellular generation logic apply to whichever subscription is currently used for data. No code changes are required for dual SIM per se.

### 5. Permissions (manifest)

- **Network:** INTERNET, ACCESS_NETWORK_STATE.
- **Phone state (optional):** READ_BASIC_PHONE_STATE (for 4G/5G/5G MW detection).
- **Communications:** RECORD_AUDIO, MODIFY_AUDIO_SETTINGS, CAMERA (meetings).
- **Security:** USE_BIOMETRIC, USE_FINGERPRINT, BIND_VPN_SERVICE.
- **Storage:** READ/WRITE_EXTERNAL_STORAGE with `maxSdkVersion="32"` where applicable.

### 6. Knox and SE Android

- The app does not use Knox APIs. It runs as a normal Android app; Knox/SE for Android enforce system policy (e.g. device attestation, MDM) independently.
- If future versions need Knox integration (e.g. Knox SDK for secure storage or VPN), the same device and OS support the required Knox API level (e.g. 39).

## Testing on Z Fold5

- **Fold/unfold:** Open app on cover screen, unfold and fold; confirm layout updates and no unnecessary activity restarts.
- **Network:** Switch between Wi‑Fi and cellular; on cellular, confirm 4G vs 5G (and 5G+ where available) is reflected if you surface cellular generation in UI or logs.
- **Dual SIM:** Use one SIM for data, then switch default data to the other; confirm connectivity and routing still work.
- **Meetings/WebRTC:** Verify camera, microphone, and smart routing (e.g. path selection, codec selection) on both Wi‑Fi and 5G.

---

## Aspects which scale (client / device)

These dimensions scale with usage, device variety, or backend load. The required target above is the floor.

| Aspect | What it scales with | How it scales |
|--------|---------------------|----------------|
| **API level (minSdk / targetSdk)** | Newer devices, Android 16+ features | Raise minSdk/targetSdk when dropping older OS support; use `Build.VERSION.SDK_INT` checks for optional APIs (e.g. 5G MW on API 31+). |
| **Screen size / density** | Folded vs unfolded, different devices | `FoldableStateManager` (600 dp threshold); responsive layouts; `configChanges` so fold/unfold doesn’t recreate Activity. |
| **Network type** | Wi‑Fi vs 4G vs 5G vs 5G MW | `ConnectivityManager.getActiveTransportType()` and `getCellularGeneration()`; smart routing and adaptive codecs use these. |
| **Concurrent backend load** | Number of devices syncing / pulling | Backend scales (see [PROXMOX-VE-TEMPLATE-REQUIREMENTS.md](../infrastructure/PROXMOX-VE-TEMPLATE-REQUIREMENTS.md)); app uses rate limit and retries. |
| **WebRTC sessions** | Number of participants, video quality | Adaptive codec policy and connection-quality tier; TURN/signaling and backend infra scale with sessions. |
| **Sync volume** | Directory/orders/evidence/reports per device | Backend disk and DB; app queues and syncs by type; no fixed device-side limit. |
| **Dual SIM / multi-carrier** | Multiple subscriptions | App uses default data network; no per-SIM logic; scales to any number of SIMs as chosen by system. |
| **Permissions** | Features used (meetings, 5G detection) | Optional permissions (e.g. READ_BASIC_PHONE_STATE) scale with feature set; core works without them. |

---

## References

- **Smart routing / QoS:** [SMART-ROUTING-AND-QOS.md](SMART-ROUTING-AND-QOS.md)
- **Media codecs (P2M, adaptive):** [MEDIA-CODECS-AND-P2M.md](MEDIA-CODECS-AND-P2M.md)
- **Backend sync:** `backend/README.md`, `backend/docs/BACKEND-GAPS-AND-ROADMAP.md`
- **Backend/infra scaling:** [PROXMOX-VE-TEMPLATE-REQUIREMENTS.md](../infrastructure/PROXMOX-VE-TEMPLATE-REQUIREMENTS.md)