# 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

1. Bilko Mobile Companion will use **React Native + Expo** for iOS and Android.
2. The previous **PWA-for-MVP** assumption is superseded for the mobile companion workstream. Responsive/PWA web may still exist as web capability.
3. Customer login for mobile should use **Microsoft Entra External ID** with **OIDC Authorization Code + PKCE**.
4. 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.
5. 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`