mobile-learner-flow

Start by checking the feature parity file, then find the matching pattern in the web frontend and the API endpoint in the backend routes. Plan screens, components, hooks, and API calls before writing code, and confirm with the team if the change spans more than three files.

Never call APIs directly inside components. Use TanStack Query's useQuery with select for reads and useMutation for writes, keeping server state out of local stores. Token refresh is handled automatically in the API layer, not in components.

This setup uses TanStack Query for server state, React Context with SecureStore for auth, Zustand for local state like coins and streaks, and useReducer for practice and exam session state. Each tool has a defined scope and they should not be mixed.

Tokens are stored in SecureStore and refreshed automatically inside the shared API client, so components never handle refresh manually. On a 401 response the user is logged out and redirected to the login screen.

Avoid navigating in render bodies, direct API calls in components, TypeScript 'as' casts in business logic, non-null assertions, mock data in components, and hardcoded hex colors. Use useEffect for navigation, discriminated unions, early returns, and theme tokens instead.