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>
104 lines
5.3 KiB
Markdown
104 lines
5.3 KiB
Markdown
# SMOA requirements alignment – frontend and backend
|
||
|
||
This document maps **requirements** between the **device application** (Android; future iOS and Web) and the **backend**, and lists **gaps** with ownership (device vs backend).
|
||
|
||
---
|
||
|
||
## 1. Sync contract (frontend ↔ backend)
|
||
|
||
All clients (Android, iOS, Web) use the same REST contract.
|
||
|
||
| Requirement | Backend | Android app | iOS (to build) | Web Dapp (to build) |
|
||
|-------------|---------|-------------|-----------------|----------------------|
|
||
| **POST sync** (directory, order, evidence, credential, report) | ✅ SyncController | ✅ SyncAPI + SyncService | Same contract | Same contract |
|
||
| **SyncResponse** (success, itemId, serverTimestamp, conflict, remoteData, message) | ✅ | ✅ core/common SyncResponse | Same | Same |
|
||
| **Conflict** (server returns conflict + base64 remoteData) | ✅ | ✅ SyncService handles ConflictException | Same | Same |
|
||
| **DELETE** (sync delete) | ✅ | ✅ SyncAPI.delete* + SyncService on SyncOperation.Delete | Same | Same |
|
||
| **Pull GET** (directory, orders, evidence, credentials, reports) | ✅ PullController | ✅ Use GET with since/limit | Same | Same |
|
||
| **Auth** (X-API-Key or api_key) | ✅ | ✅ Send header/query when configured | Same | Same |
|
||
| **Rate limit** (429, configurable RPM) | ✅ | ✅ Retry with backoff | Same | Same |
|
||
|
||
---
|
||
|
||
## 2. API surface (backend)
|
||
|
||
| Endpoint | Method | Purpose |
|
||
|----------|--------|---------|
|
||
| `/health` | GET | Liveness; db status. |
|
||
| `/api/v1/info` | GET | Discovery: name, version, list of sync/pull/delete endpoints. |
|
||
| `/api/v1/sync/directory` | POST | Sync directory entry. |
|
||
| `/api/v1/sync/order` | POST | Sync order. |
|
||
| `/api/v1/sync/evidence` | POST | Sync evidence. |
|
||
| `/api/v1/sync/credential` | POST | Sync credential. |
|
||
| `/api/v1/sync/report` | POST | Sync report. |
|
||
| `/api/v1/sync/directory/{id}` | DELETE | Delete directory entry. |
|
||
| `/api/v1/sync/order/{orderId}` | DELETE | Delete order. |
|
||
| `/api/v1/sync/evidence/{evidenceId}` | DELETE | Delete evidence. |
|
||
| `/api/v1/sync/credential/{credentialId}` | DELETE | Delete credential. |
|
||
| `/api/v1/sync/report/{reportId}` | DELETE | Delete report. |
|
||
| `/api/v1/directory` | GET | List directory (optional unit, X-Unit). |
|
||
| `/api/v1/orders` | GET | List orders (since, limit, jurisdiction / X-Unit). |
|
||
| `/api/v1/evidence` | GET | List evidence (since, limit, caseNumber). |
|
||
| `/api/v1/credentials` | GET | List credentials (since, limit, holderId). |
|
||
| `/api/v1/reports` | GET | List reports (since, limit). |
|
||
|
||
---
|
||
|
||
## 3. DTO alignment (device → backend)
|
||
|
||
Device sends JSON that matches backend request DTOs; backend returns JSON that matches device expectations.
|
||
|
||
| Resource | Request (device → backend) | Response (backend → device) |
|
||
|----------|----------------------------|-----------------------------|
|
||
| Directory | DirectorySyncRequest (id, name, title, unit, …; lastUpdated) | SyncResponse |
|
||
| Order | OrderSyncRequest (orderId, orderType, title, content, …; clientUpdatedAt) | SyncResponse |
|
||
| Evidence | EvidenceSyncRequest (evidenceId, caseNumber, …; clientUpdatedAt) | SyncResponse |
|
||
| Credential | CredentialSyncRequest (credentialId, holderId, …; clientUpdatedAt) | SyncResponse |
|
||
| Report | ReportSyncRequest (reportId, reportType, title, format, …; clientUpdatedAt) | SyncResponse |
|
||
|
||
**Enums (validation):** orderType, status, evidenceType, reportType, format — backend uses `@Pattern`; device must send allowed values (see backend SyncRequest.kt).
|
||
|
||
---
|
||
|
||
## 4. Gaps and ownership
|
||
|
||
### 4.1 Filled by device (Android)
|
||
|
||
| Gap | Status | Notes |
|
||
|-----|--------|--------|
|
||
| **Real SyncAPI implementation** | ✅ Done | BackendSyncAPI (app) calls backend when BuildConfig.SMOA_BACKEND_BASE_URL set; build with -Psmoa.backend.baseUrl=http://host:8080. |
|
||
| **SyncService uses SyncAPI** | ✅ Done | CommonModule provides SyncService(syncAPI); AppModule provides SyncAPI (BackendSyncAPI or DefaultSyncAPI). |
|
||
| **Delete operation** | ✅ Done | SyncService calls syncAPI.delete*(item.id) when item.operation == SyncOperation.Delete. |
|
||
| **Pull on connect** | Optional | On connectivity restored, call GET endpoints and merge into local DB. |
|
||
|
||
### 4.2 Filled by backend
|
||
|
||
| Gap | Status | Notes |
|
||
|-----|--------|--------|
|
||
| **CORS for Web** | ✅ | smoa.cors.allowed-origins; set to web app origin(s) for production. |
|
||
| **Info endpoint** | ✅ | GET /api/v1/info lists all sync, delete, and pull endpoints for client discovery. |
|
||
| **Auth for all clients** | ✅ | API key required when smoa.api.key set; same for Android, iOS, Web. |
|
||
|
||
### 4.3 Filled by iOS (when built)
|
||
|
||
| Gap | Owner | Notes |
|
||
|-----|--------|--------|
|
||
| **iOS app** | iOS | Swift/SwiftUI or KMP; same REST contract; Keychain for API key. |
|
||
| **Offline queue** | iOS | Queue sync when offline; retry when online. |
|
||
|
||
### 4.4 Filled by Web Dapp (when built)
|
||
|
||
| Gap | Owner | Notes |
|
||
|-----|--------|--------|
|
||
| **Web app** | Web | SPA (e.g. React/Vue); responsive + touch; same REST contract. |
|
||
| **CORS origin** | Backend config | Set smoa.cors.allowed-origins to web origin. |
|
||
| **Secure storage** | Web | sessionStorage or secure cookie for API key/session. |
|
||
|
||
---
|
||
|
||
## 5. References
|
||
|
||
- **Backend API:** `backend/README.md`, OpenAPI `/v3/api-docs`, `/swagger-ui.html`
|
||
- **Mobile contract:** `core/common/SyncAPI.kt`, `SyncService.kt`
|
||
- **Platforms:** [PLATFORM-REQUIREMENTS.md](PLATFORM-REQUIREMENTS.md)
|