core: build resilient API client with token refresh and offline queue

[EmeditWeb]

Problem

The learner app targets users on unreliable mobile connectivity, but the API
client is not resilient. register.tsx swallows registration failures in an
empty catch with only a TODO (#44), stores do not persist (#38, #39), and
api.ts has no centralized 401 refresh-and-retry, no backoff for transient
network errors, and no offline request queue. A dropped connection during a
mutation is silently lost with no user feedback and no retry.

Before Starting

Read ALL of these before writing any code:

• context/architecture-context.md
• context/code-standards.md

What To Build

A resilient API client layer:

1. An interceptor-based client with automatic 401 handling: refresh the token
   once, retry the original request, and hard-logout on refresh failure.
2. Exponential backoff with jitter for idempotent requests on transient
   network/5xx errors, with a request-timeout ceiling.
3. A durable offline mutation queue (secure/persisted storage) that captures
   writes made while offline and replays them on reconnect, with per-request
   idempotency keys to avoid duplicates.
4. Consistent typed error surfacing so screens can show real feedback instead
   of swallowing errors.

Files To Touch

• services/api.ts (interceptors, refresh, retry)
• src/offline/* (mutation queue + replay)
• app/register.tsx (real error handling)
• services/auth.service.ts

Acceptance Criteria

• 401s trigger a single refresh + retry; refresh failure logs out
• Transient failures retried with exponential backoff + jitter
• Offline mutations queued durably and replayed on reconnect
• Idempotency keys prevent duplicate submissions on replay
• register.tsx surfaces real errors; no empty catch blocks remain
• Tests cover refresh, retry, and offline replay

Mandatory Checks Before Opening PR

• All context/ files read and understood
• npx expo export --platform web passes
• No TypeScript errors
• No hardcoded hex colors (constants/colors.ts only)
• Icons from lucide-react-native only
• Loading, error, and empty states handled
• PR references this issue number

[alepsisl04]

Hi team,

I would love to claim this issue and build a highly resilient API and offline architecture for the mobile app, aligning perfectly with the core and security requirements.

Here is my engineering approach to solve this drift:

1. Interceptor & Token Refresh: Refactor services/api.ts and services/auth.service.ts to implement a centralized interceptor loop. It will catch 401 errors, execute a single token refresh attempt, retry the failed request upon success, or trigger a clean hard-logout on failure.
2. Exponential Backoff with Jitter: Implement a robust retry mechanism for transient network or 5xx errors on idempotent requests, applying exponential backoff with random jitter to protect backend stability.
3. Durable Offline Queue: Design a persistent offline mutation queue in src/offline/* leveraging secure storage. It will capture mutations made offline, assign mandatory idempotency keys, and seamlessly replay them once connectivity is restored to prevent duplication.
4. Error Handling & UX: Refactor app/register.tsx to get rid of empty catch blocks, ensuring strongly-typed errors surface correctly on screen to handle loading, error, and empty states.

I will rigorously read all architectural context files, make sure npx expo export --platform web passes with zero TS errors, and follow the layout/color constraints closely. Please assign this issue to me!

[Olisachukwuma1]

i have very good experience with react and would like to work on this

[Danielodingz]

Hey maintainer, please i would like to work on this issue.

[Exploit34]

Hi maintainer, please let me handle this issue.

[Davichi-1]

Hello, I’m interested in fixing this issue and can provide a well-structured solution along with a clean pull request.