feat(frontend): align with modern TanStack Router + React Query patterns

lib/api.ts:
- replace ApiClient class with plain request() function + api object
- add typed ApiError(status, message, body) so callers can check e.status
- handle 204 No Content (return undefined instead of trying to parse JSON)

services/auth.ts (new):
- sessionQueryOptions: canonical queryOptions factory for auth state
  queryKey ["auth","session"], staleTime 5min
- single definition reused by root loader, components, and mutations

routes/__root.tsx:
- add beforeLoad that calls ensureQueryData(sessionQueryOptions)
- return { session } into router context so all child routes have it
  without a per-page network request

routes/dashboard.tsx:
- replace useQuery + imperative navigate with beforeLoad auth guard
- throw redirect({ to: "/login" }) if context.session is null
- use Route.useRouteContext() to read session — no loading state needed
- invalidate sessionQueryOptions on logout before navigating

routes/login.tsx + register.tsx:
- add beforeLoad to redirect authenticated users to /dashboard
- remove useState(isLoading) — use form.Subscribe(s => s.isSubmitting)
- invalidate sessionQueryOptions after successful auth before navigating

docs/PATTERNS.md:
- Service files with queryOptions factories
- beforeLoad auth guards (protected routes + public redirects)
- form.Subscribe(isSubmitting) over useState
- ApiError handling pattern

docs/DECISIONS.md:
- queryOptions() over inline query objects
- beforeLoad over component-level redirects (no flash, no loading state)
- plain fetch over HTTP client libraries
- no global auth state — query cache is the single source of truth

Author: Adjanour

apps/frontend/docs/DECISIONS.md

@@ -435,3 +435,144 @@ routes/
     PostCard.tsx
     PostForm.tsx
 ```
+
+---
+
+## `queryOptions()` Factories over Inline Query Objects
+
+**Choice**: Define query options in service files, not inline in components.
+
+**Why**:
+
+Defining a query inline in a component creates three problems:
+
+1. You cannot use the same query in a route `loader` without duplicating the `queryKey` and `queryFn`.
+2. The query key is scattered — invalidating it requires remembering the exact string used in the component.
+3. It's harder to test; you'd need to render the component just to test the fetch logic.
+
+`queryOptions()` solves all three:
+
+```typescript
+// services/auth.ts — one definition, used everywhere
+export const sessionQueryOptions = queryOptions({
+  queryKey: ["auth", "session"] as const,
+  queryFn: () => authClient.getSession().then((r) => r.data ?? null),
+  staleTime: 1000 * 60 * 5,
+});
+
+// In a route loader:
+loader: ({ context: { queryClient } }) =>
+  queryClient.ensureQueryData(sessionQueryOptions),
+
+// In a component:
+const session = Route.useLoaderData();
+
+// When invalidating after a mutation:
+queryClient.invalidateQueries({ queryKey: sessionQueryOptions.queryKey });
+```
+
+One object. All usages point to the same key, staleTime, and fetcher. Rename it and TypeScript catches every consumer.
+
+**Trade-offs**:
+
+- One more file to create per domain
+- Pattern requires understanding TanStack Router's loader + context model
+
+---
+
+## `beforeLoad` for Auth Guards over Component-Level Redirects
+
+**Choice**: Auth checks in `beforeLoad`, not inside the rendered component.
+
+**Why**:
+
+The old pattern — `useQuery` for session inside the component, then `navigate()` if null — has three problems:
+
+1. **Flash of unauthenticated content**: The component renders (briefly showing the protected content or a loading spinner) before the redirect fires. With `beforeLoad`, the component never mounts if the guard fails.
+
+2. **Dependent state management**: You need `isLoading` + `if (!session) return null` — two extra states the component has to manage.
+
+3. **Escape from the component lifecycle**: Calling `navigate()` inside a `useEffect` or render is a side effect of the render phase, not a declarative description of what the route requires.
+
+`beforeLoad` is a declarative contract: "this route requires a session." The router enforces it before the component touches the DOM.
+
+```typescript
+// ✗ Component-level guard — the old React Router mental model
+function DashboardPage() {
+  const { data: session, isLoading } = useQuery({ queryKey: ["session"], ... });
+  if (isLoading) return <Spinner />;
+  if (!session) { navigate({ to: "/login" }); return null; }
+  return <div>{session.user.name}</div>;
+}
+
+// ✓ Router-level guard — declarative, no flash, no loading state
+export const Route = createFileRoute("/dashboard")({
+  beforeLoad: ({ context }) => {
+    if (!context.session) throw redirect({ to: "/login" });
+  },
+  component: DashboardPage,
+});
+
+function DashboardPage() {
+  const { session } = Route.useRouteContext();
+  if (!session) return null;  // Defensive — never reached
+  return <div>{session.user.name}</div>;
+}
+```
+
+The root route's `beforeLoad` fetches the session once and injects it into router context. All child routes read `context.session` without fetching again.
+
+**Trade-offs**:
+
+- Requires understanding TanStack Router's context model
+- `context.session` is typed as `Session | null` even on protected routes (TS can't narrow through `throw redirect()`); requires a defensive null check
+
+---
+
+## Plain Fetch API over HTTP Client Libraries
+
+**Choice**: `fetch` directly, wrapped in a thin `request()` function.
+
+**Why**:
+
+The browser's `fetch` API is a web standard. Libraries like `axios`, `ky`, and `got` add:
+- Interceptors (you can do this with a wrapper function)
+- Automatic retries (handle in `queryOptions.retry`)
+- Request cancellation (use `AbortSignal` from the `loader` context)
+- Error normalisation (our `ApiError` class does this)
+
+None of these require a library. `fetch` supports all of them natively or via `@tanstack/react-query`'s built-in mechanisms.
+
+The `api` object in `lib/api.ts` is a plain object of functions — not a class instance. This is intentionally simpler: no `new`, no `this`, tree-shakeable, testable by calling the functions directly.
+
+**The shift**: `ApiError` is thrown for non-2xx responses and carries `status` and `body`. Callers check `instanceof ApiError` for specific status handling and fall back to a generic message otherwise. This replaces the opaque `Error("Request failed")` that an unmaintained class was throwing.
+
+**Trade-offs**:
+
+- No interceptors (add a wrapper if upload progress or auth headers become necessary)
+- Manual `Content-Type` header (acceptable — all our API calls are JSON)
+
+---
+
+## No Global Auth State (Zustand/Context) — Use the Query Cache
+
+**Choice**: Session state lives in the React Query cache (`["auth", "session"]`), not a Zustand store or React context.
+
+**Why**:
+
+A common pattern is to create a `useAuthStore` or `AuthContext` to hold the current user. This creates a redundant source of truth that can drift from the server state.
+
+The query cache *is* the client-side state for server data. The session is server state. It:
+- Has a known staleness (5 minutes)
+- Must be re-fetched after mutations (signIn/signOut)
+- Can be invalidated from anywhere via `queryClient.invalidateQueries`
+
+Zustand is reserved for *UI state* — things with no server equivalent (sidebar open/closed, modal state, selected tab). Anything that has a server source lives in the React Query cache.
+
+| State | Solution |
+|---|---|
+| Current user session | React Query `sessionQueryOptions` |
+| Server resource (posts, users) | React Query `queryOptions` |
+| Form state | TanStack Form |
+| URL/navigation state | TanStack Router search params |
+| UI-only state (modals, sidebar) | Zustand |

apps/frontend/docs/PATTERNS.md

@@ -804,3 +804,173 @@ if (error) {
   );
 }
 ```
+
+---
+
+## Service Files — `queryOptions` Factories
+
+Define query options in a service file, not inline in a component. This makes them reusable across loaders, components, and tests — and keeps the query key co-located with the fetcher.
+
+```typescript
+// services/auth.ts
+import { queryOptions } from "@tanstack/react-query";
+import { authClient } from "@/lib/auth-client";
+
+export const sessionQueryOptions = queryOptions({
+  queryKey: ["auth", "session"] as const,
+  queryFn: () => authClient.getSession().then((r) => r.data ?? null),
+  staleTime: 1000 * 60 * 5,
+});
+```
+
+Use the same options object in the router loader and the component:
+
+```typescript
+// Route loader — runs before render, no loading state needed
+loader: ({ context: { queryClient } }) =>
+  queryClient.ensureQueryData(sessionQueryOptions),
+
+// Component — reads from cache, no extra fetch
+const session = Route.useLoaderData();
+```
+
+Name service files after the domain they serve: `services/auth.ts`, `services/users.ts`, `services/posts.ts`.
+
+---
+
+## Auth Guards with `beforeLoad`
+
+Protect routes at the router level — not inside the component. `beforeLoad` runs before the component mounts; if a redirect is thrown, the component never renders.
+
+### Protected route
+
+```typescript
+// routes/dashboard.tsx
+export const Route = createFileRoute("/dashboard")({
+  beforeLoad: ({ context }) => {
+    // context.session was set by the root beforeLoad.
+    // If null, redirect to /login before the page loads.
+    if (!context.session) {
+      throw redirect({ to: "/login" });
+    }
+  },
+  component: DashboardPage,
+});
+
+function DashboardPage() {
+  // session is null-narrowed away by the guard above.
+  // The null check here is defensive — it satisfies TypeScript.
+  const { session } = Route.useRouteContext();
+  if (!session) return null;
+
+  return <div>Hello, {session.user.name}</div>;
+}
+```
+
+### Redirect authenticated users away from login/register
+
+```typescript
+// routes/login.tsx
+export const Route = createFileRoute("/login")({
+  beforeLoad: ({ context }) => {
+    if (context.session) {
+      throw redirect({ to: "/dashboard" });
+    }
+  },
+  component: LoginPage,
+});
+```
+
+### How the root feeds session into context
+
+```typescript
+// routes/__root.tsx
+export const Route = createRootRouteWithContext<RouterContext>()({
+  beforeLoad: async ({ context }) => {
+    const session = await context.queryClient.ensureQueryData(sessionQueryOptions);
+    return { session };  // Available as context.session on all child routes
+  },
+});
+```
+
+### After a mutation that changes auth state (signIn, signOut, signUp)
+
+```typescript
+// Invalidate first, then navigate.
+// The router re-runs beforeLoad, which calls ensureQueryData.
+// Because the query is stale (invalidated), it refetches, and context.session
+// is updated before the new route's component renders.
+await queryClient.invalidateQueries({ queryKey: sessionQueryOptions.queryKey });
+navigate({ to: "/dashboard" });
+```
+
+---
+
+## Form Submitting State
+
+TanStack Form tracks its own submitting state. You do not need `useState`.
+
+```typescript
+// ✗ Don't do this
+const [isLoading, setIsLoading] = useState(false);
+const form = useForm({
+  onSubmit: async ({ value }) => {
+    setIsLoading(true);
+    try { /* ... */ } finally { setIsLoading(false); }
+  },
+});
+<button disabled={isLoading}>{isLoading ? "Loading..." : "Submit"}</button>
+
+// ✓ Do this
+const form = useForm({
+  onSubmit: async ({ value }) => {
+    // TanStack Form sets isSubmitting = true automatically for onSubmit's duration.
+    // No manual state management needed.
+  },
+});
+
+<form.Subscribe selector={(s) => s.isSubmitting}>
+  {(isSubmitting) => (
+    <button type="submit" disabled={isSubmitting}>
+      {isSubmitting ? "Loading..." : "Submit"}
+    </button>
+  )}
+</form.Subscribe>
+```
+
+---
+
+## Handling API Errors
+
+`api.ts` throws `ApiError` for non-2xx responses. Check the status code for specific handling:
+
+```typescript
+import { api, ApiError } from "@/lib/api";
+
+try {
+  await api.post("/api/posts", data);
+} catch (e) {
+  if (e instanceof ApiError) {
+    if (e.status === 409) {
+      toast.error("A post with that title already exists");
+      return;
+    }
+    if (e.status === 422) {
+      toast.error("Invalid data");
+      return;
+    }
+  }
+  toast.error("Something went wrong");
+}
+```
+
+For queries, use `onError` or `throwOnError` in `queryOptions`:
+
+```typescript
+export const postsQueryOptions = queryOptions({
+  queryKey: ["posts"],
+  queryFn: () => api.get<ApiSuccess<Post[]>>("/api/posts"),
+});
+```
+
+Errors surface in `useQuery()` as `error: ApiError` — typed, not opaque.