network-layer-architect

Configure an OkHttpClient with connect, read, and call timeouts plus auth and logging interceptors, then build Retrofit with a base URL and Moshi converter. Wrap calls in an ApiService consumed by a Repository that returns domain types, never raw Response objects.

Use Retrofit with OkHttp for Android-only apps with REST/JSON and a mature ecosystem. Choose Ktor Client for Kotlin Multiplatform projects sharing code with iOS, or when you need heavy WebSocket and streaming support.

Implement an auth interceptor that adds the Authorization header, and on a 401 response closes it, refreshes the token, and retries the request once. Use a mutex for single-flight refresh so concurrent 401s do not trigger duplicate refreshes, and never refresh on the refresh endpoint itself.

Retry only network IOExceptions, 5xx server errors, and transient codes like 429 with Retry-After or 503. Use exponential backoff with jitter, such as 200ms doubling per attempt plus random jitter, and never retry 4xx client errors.

Use MockWebServer for OkHttp/Retrofit or MockEngine for Ktor to unit test the layer. Explicitly test auth refresh paths and error mapping, and reset MockWebServer in an @After method so tests do not pollute each other.

Leaking DTOs couples the UI to the API shape, so every API change breaks the UI. Repositories should translate HTTP responses into domain types or sealed result types, keeping Response, Call, and HttpException invisible to ViewModels.