Twelve decisions before a line of code
Planning the DevOnboard auth frontend as twelve explicit decisions, scaffolding it in one session, and letting a code review humble the result.
This week was the auth frontend for DevOnboard — the piece that takes a GitHub OAuth login and turns it into a working session in a React app.
I didn’t start with code. I started by writing down every decision the feature would force me to make — twelve of them — and resolving each one on paper first: where the JWT lives, how the OAuth callback flow works, where the 401 interceptor sits, how protected routes are structured, the full router shape, API client setup, TanStack Query defaults, state ownership rules, loading/error patterns, and the visual identity.
A few that mattered most:
- JWT lives in a Zustand store, in memory only. No localStorage, no XSS surface.
Components subscribe reactively; non-React code reads it via
getState(). - The 401 interceptor uses a refresh-lock. If three queries fire at once and all get 401s, you don’t want three simultaneous refresh calls. A refresh-in-flight flag plus a pending queue means one refresh happens and every queued request retries with the new token.
- State ownership as a project-wide rule, not a per-feature debate. Came from the
API → TanStack Query. Client flow state that survives navigation → Zustand.
Everything else → local
useState. Deciding this once means never re-litigating it.
With the decisions locked (and recorded as ADRs), the actual build went fast: the full auth layer — store, axios client with interceptors, protected route components, login and callback pages, a 10-route router — scaffolded in a single session with 19 passing tests.
The build surfaced bugs the plan couldn’t have predicted. An inline Zustand object selector was creating a new reference every render and triggering an infinite re-render loop — fixed with separate primitive selectors. And the refresh call needed its own bare axios instance, because if the refresh endpoint itself returns a 401, the interceptor would try to refresh again, forever.
Then a code review pass found six more issues in code I’d considered done. The one
worth sharing: my AdminRoute was redirecting unauthorized (but authenticated) users
to /login. Wrong semantics — the user isn’t unauthenticated, they’re unauthorized.
They now land on an error page that says so, instead of bouncing through a confusing
three-hop redirect.
The lesson I keep re-learning: planning up front made the build fast, and the review made it right. Neither replaces the other.