MOS Field — Native Android App Plan

MOS Field for Android is the same product as the iOS app — same roles, same phases, same backend contract — expressed natively in Kotlin, Jetpack Compose, and Material Design 3. It does not chase pixel-parity with iOS; it chases behavior parity: a field crew member on a Pixel and one on an iPhone can run the same day the same way. Everything platform-shaped (navigation, theming, storage, background work) follows Android idiom.

Every pillar of the Android constitution, mapped to the concrete decision in this plan. As on iOS, exactly one deviation exists and it is explicitly authorized by the product owner — the same deviation, for the same reason.

Strict MVVM with a core/repository spine, instantiated with MOS feature names under com.mikeodellsurveys.mosfield. Phase A packages are created at kickoff; later-phase packages only when their phase begins (no speculative scaffolding, constitution §4).

/app/src/main/java/com/mikeodellsurveys/mosfield/
  /app
    MainActivity.kt              ← single Activity; FLAG_SECURE in release
    AppNavigation.kt             ← one NavHost; routes as a sealed class
    AppContainer.kt              ← manual constructor-injection graph (no Hilt)
  /features
    /auth          /ui /viewmodel /model
    /jobs          /ui /viewmodel /model    ← list, detail, status updates
    /notes         /ui /viewmodel /model
    /documents     /ui /viewmodel /model
    /photos        /ui /viewmodel /model    ← Phase A
    /fieldreports  /ui /viewmodel /model    ← Phase A
    /timetracking  /ui /viewmodel /model    ← Phase B
    /mileage       /ui /viewmodel /model    ← Phase B
    /equipment     /ui /viewmodel /model    ← Phase B
    /dashboard     /ui /viewmodel /model    ← Phase C (owner/PM)
    /search        /ui /viewmodel /model    ← Phase C
    /voicereports  /ui /viewmodel /model    ← Phase D
  /core
    /network       NetworkService.kt · ApiEndpoints.kt · NetworkResult.kt · CertPinnedConnectionFactory.kt
    /repository    JobRepository.kt · NoteRepository.kt · DocumentRepository.kt
                   TimeEntryRepository.kt · UploadQueueRepository.kt
    /database      AppDatabase.kt · JobDao.kt · NoteDao.kt · UploadQueueDao.kt
    /security      KeystoreManager.kt · BiometricManager.kt · EncryptedPreferencesManager.kt
    /auth          AuthManager.kt           ← GoTrue REST client + token refresh mutex
    /sync          SyncWorker.kt · PhotoUploadWorker.kt   ← WorkManager
  /shared
    /components    PrimaryButton.kt · InputField.kt · LoadingIndicator.kt
                   StatusPill.kt · RoleBadge.kt · DataStateContent.kt
    /extensions    ContextExtensions.kt · StringExtensions.kt
    /constants     AppConstants.kt · ApiConstants.kt
    /utils         Logger.kt · Validator.kt
  /theme
    Theme.kt · Color.kt · Typography.kt · Shape.kt

Layer contract

// The UiState + DI pattern used by every screen in the app
data class JobListUiState(
    val isLoading: Boolean = false,
    val jobs: List<Job> = emptyList(),
    val pendingSyncCount: Int = 0,
    val errorMessage: String? = null
)

class JobListViewModel(
    private val jobRepository: JobReadable
) : ViewModel() {
    private val _uiState = MutableStateFlow(JobListUiState())
    val uiState: StateFlow<JobListUiState> = _uiState.asStateFlow()

    fun loadAssignedJobs() = viewModelScope.launch {
        _uiState.update { it.copy(isLoading = true) }
        when (val result = jobRepository.assignedJobs()) {
            is NetworkResult.Success -> _uiState.update { it.copy(isLoading = false, jobs = result.data) }
            is NetworkResult.Error   -> _uiState.update { it.copy(isLoading = false, errorMessage = result.error.toUserMessage()) }
        }
    }
}

Identical auth contract to iOS: Supabase Auth (GoTrue) consumed as plain HTTPS REST — no Supabase Kotlin SDK — so the whole stack is HttpsURLConnection + EncryptedSharedPreferences + BiometricPrompt, all inside the constitution's allowed surface.

Token lifecycle

Role-aware navigation (single NavHost)

• field_crew → NavigationBar: My Jobs · Photos · Reports · Time (Time appears in Phase B).
• project_manager → Jobs · Crews · Documents · Reports with create/assign actions enabled.
• office_staff → Schedule · Jobs · Clients (Phase C scope; read-mostly before that).
• owner → everything plus Dashboard (Phase C). Multiple roles merge destinations (3–5 max, per M3).
• Routes defined as a sealed class in AppNavigation.kt; start destination chosen by session state: SignedOut → login, Locked → biometricGate, Active(roles) → home(roles). Predictive back gesture enabled.

One interface-driven layer on HttpsURLConnection, exactly per constitution §7 — the constitution's own contracts, extended with the MOS endpoint catalog and error mapping.

interface NetworkServiceInterface {
    suspend fun <T> request(endpoint: Endpoint, deserializer: DeserializationStrategy<T>): NetworkResult<T>
}

data class Endpoint(
    val path: String,
    val method: HttpMethod,                 // GET · POST · PUT · DELETE · PATCH
    val headers: Map<String, String> = emptyMap(),
    val body: String? = null
)

sealed class NetworkResult<out T> {
    data class Success<T>(val data: T) : NetworkResult<T>()
    data class Error(val error: AppError) : NetworkResult<Nothing>()
}

sealed class AppError {
    object NetworkUnavailable : AppError()
    object Unauthorized : AppError()
    object Forbidden : AppError()          // role gate — server said no
    object DecodingFailed : AppError()
    data class ValidationFailed(val message: String) : AppError()
    data class HttpError(val code: Int, val message: String) : AppError()
    object SyncConflict : AppError()
}

• HTTPS only — android:usesCleartextTraffic="false"; connections created through a single factory that rejects non-TLS URLs.
• Certificate pinning — network_security_config.xml pins the production API host's public keys with an expiry and backup pin; DEBUG builds get a separate config permitting localhost only.
• Typed decoding immediately — kotlinx.serialization with explicit @SerialName (snake_case API → camelCase Kotlin); raw String/JSONObject never reaches a ViewModel; Any is banned.
• Explicit status mapping — 401 → single-flight refresh then Unauthorized; 403 → Forbidden; 422 → ValidationFailed; 5xx → HttpError; IOException → NetworkUnavailable.
• All calls suspend on Dispatchers.IO; no callbacks; connection/read timeouts tuned for rural LTE.
• Environments in ApiConstants per build type: DEBUG → local FastAPI; RELEASE → the production API domain. No keys in source; R8 keep rules cover serialization models.

Same product decision as iOS — the local store is the read source of truth and writes queue when offline — implemented the Android way: Room for domain data, WorkManager for guaranteed background sync.

Room entities (repositories only — never touched from UI or ViewModel)

• SyncWorker drains the write queue oldest-first, scheduled by WorkManager with a network constraint — WorkManager's guaranteed execution replaces iOS's BGAppRefreshTask and is strictly stronger. Failures retry with exponential backoff; a quiet "pending sync" badge surfaces state, never a blocking dialog.
• Photos are persisted to app-private storage first, then uploaded by PhotoUploadWorker against a presigned URL — multi-MB site photos finish even if the crew pockets the phone.
• Documents cached in app-private encrypted-at-rest storage (FBE devices, minSdk 29 guarantees it); rendered natively via the platform PDF renderer.
• Storage discipline: tokens → EncryptedSharedPreferences; domain data → Room; benign preferences (jobs sort order, theme choice) → Preferences DataStore. Constitution §8/§11 exactly.

Identical feature scope to the iOS phases, with each feature naming its MVVM units and the Android/Jetpack-native API that satisfies the dependency rule. Later phases are planned here but scaffolded only when they begin.

Nearly identical to the iOS list — by design. The one Android-specific addition is FCM delivery alongside APNs in the push service.

• Encrypted storage only — typed EncryptedPreferencesManager (saveToken/getToken/clearToken, SecureKey enum) over EncryptedSharedPreferences with MasterKey AES256_GCM; tokens never in plain SharedPreferences, DataStore, rememberSaveable, or logs.
• Biometric gate — BiometricPrompt on re-entry with device-credential fallback; sign-out clears encrypted prefs and the Room cache.
• Cleartext ban — android:usesCleartextTraffic="false"; every connection built by one TLS-only factory.
• Certificate pinning — network_security_config.xml pins the production API host (primary + backup pin, expiry set); DEBUG config permits localhost only and never ships.
• Typed trust boundary — kotlinx.serialization with explicit @SerialName on every model; no JSONObject, no Any, no raw String past the network layer.
• Screen capture protection — FLAG_SECURE on the MainActivity window in release builds (job sites, client addresses, and financials stay out of the app switcher).
• Backup lockdown — android:allowBackup="false"; nothing sensitive leaves the device via device backup.
• R8 hardening — full mode in release with explicit keep rules for serialization models and Keystore classes; minification never disabled in production.
• PII-safe logging — custom Logger that redacts emails/tokens/coordinates in release; diagnostics behind BuildConfig.DEBUG.
• Input validation — shared Validator rules (lengths, formats) applied before values reach ViewModels or the wire.
• No secrets in source — only the publishable Supabase anon key ships (public by design); APNs/FCM server keys and DB credentials exist server-side only.
• Server-side authority — client role checks are UX only; FastAPI re-verifies the ES256 JWT via JWKS and enforces RBAC from the database on every request (already live: require_roles()).

Testing standards (constitution §12)

• Unit tests for every ViewModel and Repository (JUnit + kotlinx-coroutines-test, UnconfinedTestDispatcher); interface-based fakes, no mocking frameworks (FakeAuthRepository : AuthRepositoryInterface…); >80% coverage on business logic.
• DAO tests against an in-memory Room database; sync-queue ordering and conflict cases covered.
• Compose UI tests (ui-test-junit4) for the critical flows: sign-in + biometric gate, job list → detail → status update, photo capture → queued upload, daily report submit.
• Accessibility pass per screen with TalkBack enabled + Accessibility Scanner; font-scale checks at 1.0× and 2.0×; WCAG 2.1 AA contrast verified against the brand scheme.
• Release-build gate — every milestone exit runs the R8 release build and smoke-tests it (obfuscation breaks serialization if keep rules drift).
• No feature merges with failing tests.

Distribution & quality telemetry

• Play Console — internal testing track for the crew from the first Phase A build; then closed testing for the whole company.
• Production: managed Google Play private app (organization-restricted) — internal operations tool, not a public listing.
• Android Vitals watched from the first internal build: crash rate, ANR rate, excessive wakeups — the Android analogue of the iOS plan's TestFlight feedback loop.
• Baseline Profiles generated for the jobs flow so cold start stays fast on mid-range field devices.

Milestones

Android App Constitution — the governing document for all Android work on this project, reproduced as supplied.