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
5a8c26cf5d