Kordant/tasks/shieldai-unified-restructure/37-android-api-client.md

# 37. Android App — API Client, tRPC Bridge, and Offline Support

meta:
  id: shieldai-unified-restructure-37
  feature: shieldai-unified-restructure
  priority: P1
  depends_on: [shieldai-unified-restructure-34, shieldai-unified-restructure-35, shieldai-unified-restructure-36]
  tags: [android, kotlin, api, networking, offline, mobile]

objective:
- Build the API client layer for the Android app that communicates with the unified monolith's tRPC endpoints. Use a thin HTTP bridge approach with Retrofit or Ktor Client, plus offline support with Room caching and WorkManager request queuing.

deliverables:
- `android/app/src/main/java/com/shieldai/android/data/remote/` — Remote data layer:
  - `TRPCApiService.kt` — Retrofit interface or Ktor client defining all tRPC endpoints:
    - `@POST("api/trpc/user.me")`, `@POST("api/trpc/darkwatch.getWatchlist")`, etc.
    - Request/response wrappers for tRPC batch format
  - `TRPCResponse.kt` / `TRPCError.kt` — Data classes for tRPC response/error parsing
  - `AuthInterceptor.kt` — OkHttp interceptor injecting JWT from EncryptedSharedPreferences
  - `ErrorHandler.kt` — Centralized error handling with retry logic
- `android/app/src/main/java/com/shieldai/android/data/local/` — Local data layer:
  - `ShieldAIDatabase.kt` — Room database with entities:
    - `UserEntity`, `SubscriptionEntity`, `WatchlistItemEntity`, `ExposureEntity`, `AlertEntity`, `VoiceEnrollmentEntity`, `VoiceAnalysisEntity`, `SpamRuleEntity`, `PropertyEntity`, `RemovalRequestEntity`, `BrokerListingEntity`
  - `DAO` interfaces for each entity with CRUD operations
  - `CacheManager.kt` — TTL-based cache logic using Room
- `android/app/src/main/java/com/shieldai/android/data/repository/` — Repository layer:
  - `UserRepository.kt`, `DarkWatchRepository.kt`, `VoicePrintRepository.kt`, etc.
  - Each repository: remote fetch → cache to Room → return flow/coroutine
  - `RepositoryModule.kt` — Hilt module for DI
- `android/app/src/main/java/com/shieldai/android/data/model/` — Data models:
  - `User.kt`, `Subscription.kt`, `WatchlistItem.kt`, `Exposure.kt`, `Alert.kt`, etc.
  - All models as Kotlin data classes with `Parcelable` where needed
  - Enum classes matching backend enums
- `android/app/src/main/java/com/shieldai/android/data/sync/` — Offline support:
  - `OfflineWorker.kt` — WorkManager worker for retrying queued requests
  - `PendingRequestDao.kt` — Room table for queued mutations
  - `SyncManager.kt` — Manages queue, triggers WorkManager on connectivity restore
- `android/app/src/main/java/com/shieldai/android/di/` — Dependency injection:
  - `NetworkModule.kt` — Retrofit/OkHttp setup
  - `DatabaseModule.kt` — Room database provider
  - `RepositoryModule.kt` — Repository bindings

steps:
1. Add dependencies to `build.gradle.kts`:
   - Retrofit: `com.squareup.retrofit2:retrofit`, `converter-gson` or `converter-kotlinx-serialization`
   - OkHttp: `logging-interceptor`
   - Room: `androidx.room:room-runtime`, `room-ktx`, `room-compiler`
   - WorkManager: `androidx.work:work-runtime-ktx`
   - Hilt: `com.google.dagger:hilt-android`, `hilt-compiler`
   - Kotlinx Serialization: `org.jetbrains.kotlinx:kotlinx-serialization-json`
2. Create `TRPCApiService.kt`:
   - Define POST endpoints for each tRPC procedure
   - Request body: `{"0": {"json": { ... }}}` (tRPC batch format for single call)
   - Response: `TRPCResponse<T>` with `result.data` field
   - Use Kotlinx Serialization for JSON parsing
3. Create data models:
   - Kotlin data classes with `@Serializable` annotation
   - Enum classes with `@Serializable` and custom serializers if needed
   - Date parsing using `kotlinx.datetime` or `java.time.Instant`
4. Create Room database:
   - `ShieldAIDatabase` abstract class extending `RoomDatabase`
   - Entity classes with `@Entity`, `@PrimaryKey`, `@ColumnInfo`
   - DAO interfaces with `@Dao`, `@Query`, `@Insert`, `@Update`, `@Delete`
   - Type converters for complex types (enums, dates, JSON)
5. Create repositories:
   - Each repository has `remoteDataSource` (API service) and `localDataSource` (DAO)
   - `getData()`: check cache first, if stale or missing → fetch remote → save to cache → return
   - Return `Flow<T>` or `suspend` functions with `Result<T>`
6. Create offline support:
   - `PendingRequest` entity: `endpoint`, `method`, `body`, `timestamp`, `retryCount`
   - `SyncManager`: add request to pending queue when offline
   - `OfflineWorker`: periodic WorkManager task that processes pending requests
   - Network monitor using `ConnectivityManager` to trigger immediate sync
7. Create DI modules:
   - `NetworkModule`: provide `Retrofit`, `OkHttpClient` with auth interceptor and logging
   - `DatabaseModule`: provide `ShieldAIDatabase` singleton
   - `RepositoryModule`: bind repository interfaces to implementations
8. Test all layers with mocked dependencies.

steps:
- Unit: Retrofit service creates correct HTTP requests
- Unit: Room DAO inserts and retrieves entities correctly
- Unit: Repository returns cached data when offline
- Unit: SyncManager queues requests when network unavailable
- Integration: API client successfully calls `user.me` against local dev server

acceptance_criteria:
- [ ] Retrofit/Ktor client makes authenticated HTTP requests to tRPC endpoints
- [ ] tRPC response format is correctly parsed into Kotlin data classes
- [ ] Room database caches API responses with TTL-based invalidation
- [ ] Offline mutations are queued and retried when connectivity restored
- [ ] All common API procedures have type-safe Kotlin wrappers
- [ ] Network errors trigger retry with exponential backoff
- [ ] Repository layer provides clean abstraction over remote and local data
- [ ] Hilt dependency injection is configured for all layers
- [ ] API configuration supports different environments (dev, staging, prod)

validation:
- Point API client to local dev server (`http://10.0.2.2:3000` for emulator)
- Call `user.me()` and verify response parsed into `User` model
- Disconnect network, attempt a mutation, verify it queues in Room
- Reconnect network, verify WorkManager processes queued request
- Verify cache hit by calling same endpoint twice with network disabled
- Run `./gradlew test` for unit tests

notes:
- Retrofit with Kotlinx Serialization is the recommended stack. Gson works too but Kotlinx Serialization has better null safety.
- For tRPC, the Android client cannot use tRPC's type-safe client directly. The HTTP bridge is the pragmatic approach.
- The tRPC batch link sends multiple procedures in one HTTP request. For simplicity, use single-procedure requests.
- Room database schema should mirror the Drizzle schema closely, but can be simplified (fewer columns) for caching purposes.
- WorkManager requires `androidx.work:work-runtime-ktx`. It handles background execution reliably across Android versions.
- For network monitoring, `ConnectivityManager.registerDefaultNetworkCallback` is the modern approach (API 24+).
- Use `Result<T>` or sealed classes (`Success`, `Error`, `Loading`) for API state management in ViewModels.