ADR-037 — Bilko Native Mobile + Entra External ID Auth

ADR-037 — Bilko Native Mobile Companion and Entra External ID Auth 
 
 Status: Accepted for mobile direction / Phase 0 backend work required 
 Date: 2026-06-04 
 Scope: Bilko customer-facing mobile companion app for iPhone and Samsung/Android 
 
 Context 
 Bilko has existing web-first documentation that previously assumed a PWA path for MVP mobile support. Dedicated mobile docs later proposed React Native + Expo, but the architecture doc still marked the decision as recommended/not final and the implementation spec was marked ready for dispatch despite unresolved backend/auth blockers. 
 The product direction is now native mobile delivery for iPhone and Samsung/Android, not PWA as the primary mobile companion path. 
 Current backend auth evidence reviewed before this ADR: 
 
 apps/api/src/main/kotlin/no/alai/bilko/routes/AuthRoutes.kt uses httpOnly refresh-cookie behavior for web. 
 apps/web/lib/api.ts uses browser-oriented credentials: include refresh handling. 
 React Native must not depend on browser httpOnly cookie refresh semantics. 
 
 Decision 
 
 Bilko Mobile Companion will use React Native + Expo for iOS and Android. 
 The previous PWA-for-MVP assumption is superseded for the mobile companion workstream. Responsive/PWA web may still exist as web capability. 
 Customer login for mobile should use Microsoft Entra External ID with OIDC Authorization Code + PKCE . 
 Bilko backend must provide an auth bridge that validates Entra identity, maps/creates Bilko user/org/role context, and issues/refreshes Bilko API/session tokens without relying on browser-only cookies. 
 Phase 1 mobile build is not dispatch-ready until Phase 0 auth/backend prerequisites are closed. 
 
 Phase 0 Backend Prerequisites 
 
 Entra External ID tenant/app registration for Bilko customer login. 
 Redirect URI configuration for Expo development, staging, and production builds. 
 Backend token validation against Entra issuer/audience/JWKS. 
 Bilko user, organization, and role mapping/provisioning. 
 Mobile-safe session/API token issuance and refresh path. 
 Logout/revocation behavior definition. 
 Document upload size limit aligned between backend and docs. 
 
 Phase 1 Scope Boundary 
 Phase 1 includes: 
 
 Entra/Bilko login and logout. 
 Today dashboard and read-only invoice/expense lists. 
 Receipt camera capture and expense attachment upload. 
 Basic HR travel-order quick-add only if backend payload is confirmed. 
 
 Phase 1 excludes: 
 
 Durable offline queue / SQLite sync. 
 OCR extraction. 
 Push notifications or push-token registration. 
 Full /mobile/* BFF implementation unless separately scoped. 
 Mobile regulatory e-invoice submission logic. 
 
 Consequences 
 
 Mobile docs and the tech-stack spec must treat PWA notes as legacy/superseded for this workstream. 
 Web Zustand stores can be mirrored/adapted, but not reused verbatim because mobile auth/storage differs. 
 Existing /api/v1/* endpoints are preferred for Phase 1 where live; /mobile/* BFF is a Phase 2+ decision. 
 Security review is required before production rollout because customer identity and financial data are involved. 
 
 Related Documents 
 
 docs/mobile/MOBILE-PRD.md 
 docs/mobile/MOBILE-ARCHITECTURE.md 
 docs/mobile/MOBILE-IMPL-SPEC-PHASE1.md 
 /Users/makinja/system/specs/bilko-tech-stack.md