smoa/docs/architecture/MENU-AND-ENDPOINTS.md

Android app: menu navigation and REST endpoints

Purpose: One view of how the drawer / NavHost (user-visible “menu”) relates to hosted config, pull GETs, sync POST/DELETE, and local caches.
Scope: Android app (app, core/common sync, Retrofit services) and backend /api/v1 contract.

---

Single diagram (Mermaid)

Render this in any Mermaid-capable viewer (GitHub, GitLab, many IDEs, Notion, etc.).

flowchart TB
  subgraph MENU["From menu — Drawer / Home → NavHost"]
    direction TB
    HM[("☰ Menu / Home hub")]
    HM --> R0["route: home — startDestination"]
    HM --> R1["route: credentials — always in menu"]
    HM --> R6["route: orders — always in menu"]
    HM --> R7["route: evidence — always in menu"]
    HM --> R8["route: reports — always in menu"]
    HM --> R2["route: directory — RBAC DIRECTORY"]
    HM --> R3["route: communications — RBAC COMMUNICATIONS"]
    HM --> R4["route: meetings — RBAC MEETINGS"]
    HM --> R5["route: browser — RBAC BROWSER"]
    HM --> R9["route: user_settings — always"]
    R0 --> S0[HomeScreen — module shortcuts + launcher settings]
    R1 --> S1[CredentialsModule — template Cards]
    R6 --> S6[OrdersModule]
    R7 --> S7[EvidenceModule]
    R8 --> S8[ReportGenerationScreen]
    R2 --> S2[DirectoryModule — DirectoryListScreen]
    R3 --> S3[CommunicationsModule]
    R4 --> S4[MeetingsModule]
    R5 --> S5[BrowserModule]
    R9 --> S9[UserSettingsScreen — account + log out]
  end

  subgraph NET["Shared networking — not one endpoint per menu row"]
    direction TB
    CFG["GET hosted client-config JSON\n(SMOA_CONFIG_URL / ClientConfigFetcher)"]
    RS[(RemoteEndpointStore +\nRetrofit base URL + API key)]
    SS[SyncService.startSync\nwhen online and Backend Pull/Sync active]
    CFG --> RS
    RS --> SS
    SS --> PULL[Pull phase — all resource types]
    SS --> PUSH[Queue phase — POST/DELETE sync items]
  end

  subgraph API["Backend — same host /api/v1"]
    direction TB
    subgraph PULL_EP["Pull"]
      G1[GET /directory]
      G2[GET /orders]
      G3[GET /evidence]
      G4[GET /credentials]
      G5[GET /reports]
    end
    subgraph SYNC_EP["Sync"]
      P1[POST /sync/directory]
      P2[POST /sync/order]
      P3[POST /sync/evidence]
      P4[POST /sync/credential]
      P5[POST /sync/report]
      D1[DELETE /sync/directory/{id}]
      D2[DELETE /sync/order/{id}]
      D3[DELETE /sync/evidence/{id}]
      D4[DELETE /sync/credential/{id}]
      D5[DELETE /sync/report/{id}]
    end
  end

  subgraph LOCAL["Local persistence"]
    CC[("Credential Room cache")]
    SN[("sync_conflict_snapshots\norder / evidence / directory / report")]
  end

  PULL --> G1
  PULL --> G2
  PULL --> G3
  PULL --> G4
  PULL --> G5
  PUSH --> P1
  PUSH --> P2
  PUSH --> P3
  PUSH --> P4
  PUSH --> P5
  PUSH --> D1
  PUSH --> D2
  PUSH --> D3
  PUSH --> D4
  PUSH --> D5

  G4 -->|merge pull JSON| CC
  P4 -->|success upsert| CC
  D4 -->|remove row| CC

  PUSH --> CR[Conflict + remoteData]
  CR -->|credential| CC
  CR -->|other resource types| SN

---

Reading the diagram

Area	Meaning
MENU	NavigationDrawer + HomeScreen + SMOANavigation (SMOARoute). Start: home. Always listed: credentials, orders, evidence, reports, user settings. RBAC-gated: directory, communications, meetings, browser.
NET	Hosted config is optional; when present it updates RemoteEndpointStore and thus Retrofit’s base URL. SyncService.startSync runs pull (all listed GETs) then drains the outbound sync queue (POST/DELETE). Individual screens do not own dedicated REST calls for that batch.
API	Matches BackendPullApiService / BackendSyncApiService and Spring PullController / SyncController. Headers such as X-API-Key and X-Unit are as implemented in the app.
LOCAL	Credential cache: pull merge, successful credential sync, conflict remoteData, UseLocal restore, delete. Snapshots table: raw JSON for non-credential conflicts only (SyncConflictSnapshotStore / SyncConflictSnapshotRepository).

---

Related documentation

Topic	Location
Backend sync/delete and audit	backend/README.md
OpenAPI / drift	development/OPENAPI-SYNCHRONIZATION.md
OpenAPI artifact	api/api-specification.yaml
Room / credential_cache	database/DATABASE_SCHEMA.md
Frontend–backend contract	reference/REQUIREMENTS-ALIGNMENT.md

---

Source references (implementation)

• Menu and routes: app/.../ui/navigation/NavigationDrawer.kt, NavigationModule.kt (SMOARoute, SMOANavigation).
• Shell: app/.../ui/main/MainScreen.kt.
• Retrofit: app/.../api/BackendPullApiService.kt, BackendSyncApiService.kt, SyncRetrofitHolder.kt.
• Pull/sync orchestration: core/common/.../SyncService.kt.
• Backend: backend/.../api/PullController.kt, SyncController.kt.