Professional Frontend State Architecture

# TaskFlow Phase 23 Reference Snapshot

This snapshot demonstrates state ownership decisions. It is intentionally small and does not add a global state library.

Owners:
- TanStack Query: server state
- Next.js URL: filters/pagination/shareable navigation
- React Hook Form: unsaved form drafts
- Supabase Auth: authentication session
- React local state/reducer: ephemeral UI interaction
- Focused Context: only stable cross-tree convenience values

# Sources

- React - Sharing State Between Components: https://react.dev/learn/sharing-state-between-components - Single source of truth; lift shared state to the closest common owner.
- React - Managing State: https://react.dev/learn/managing-state - Avoid redundant/duplicate state; structure state intentionally.
- Next.js - useSearchParams: https://nextjs.org/docs/app/api-reference/functions/use-search-params - URL query state in the App Router.
- TanStack Query - Query State / Cache: https://tanstack.com/query/latest/docs/framework/react/reference/interfaces/QueryState - Server-state cache is separate from local UI state.
- TanStack Query - SSR/Hydration: https://tanstack.com/query/latest/docs/framework/react/guides/ssr - Request-scoped QueryClient and cache isolation.

# TaskFlow State Ownership Matrix

| Value | Owner | Why | Reset / lifetime |
|---|---|---|---|
| Task collection | TanStack Query | Remote server state | Cache freshness/auth lifecycle |
| status/search/page | URL | Shareable navigation | Route change |
| Task edit draft | React Hook Form | Intentional unsaved divergence | reset/cancel/success |
| Supabase session | Supabase Auth | Identity provider owns session | logout/expiry |
| mobile menu open | local useState | Ephemeral shell interaction | close/unmount |
| selected Task rows | local reducer | Feature interaction state | clear/filter/page change |
| current workspace slug | URL route scope | Reconstructable tenant scope | navigation |
| resolved workspace metadata | focused Context | convenient deep distribution | route/workspace change |
| completed count | derived | Calculated from authoritative result | render |

// Anti-pattern kept only as documentation. Do not use in TaskFlow.

const tasksQuery = useQuery(taskListOptions(query))
const [tasks, setTasks] = useState<Task[]>([])

useEffect(() => {
  if (tasksQuery.data) setTasks(tasksQuery.data.data)
}, [tasksQuery.data])

// Prefer:
const tasks = tasksQuery.data?.data ?? []

export type SelectionState = {
  ids: Set<string>
}

export type SelectionAction =
  | { type: "toggle"; id: string }
  | { type: "replace"; ids: string[] }
  | { type: "clear" }

export function selectionReducer(
  state: SelectionState,
  action: SelectionAction,
): SelectionState {
  switch (action.type) {
    case "toggle": {
      const ids = new Set(state.ids)
      ids.has(action.id) ? ids.delete(action.id) : ids.add(action.id)
      return { ids }
    }
    case "replace":

"use client"

import { useReducer } from "react"
import { useQuery } from "@tanstack/react-query"

export function TasksClientRegion({ query }: { query: TaskListQuery }) {
  const tasksQuery = useQuery(taskListOptions(query))
  const [selection, dispatch] = useReducer(selectionReducer, { ids: new Set<string>() })

  // Server rows are rendered directly from the query cache.
  const tasks = tasksQuery.data?.data ?? []

  const completedCount = tasks.filter(task => task.status === "DONE").length

  return (
    <TasksView
      tasks={tasks}
      completedCount={completedCount}
      selectedIds={selection.ids}
      onToggle={(id) => dispatch({ type: "toggle", id })}

"use client"

import { createContext, useContext } from "react"

export type WorkspaceSummary = {
  id: string
  slug: string
  name: string
}

const WorkspaceContext = createContext<WorkspaceSummary | null>(null)

export function WorkspaceProvider({
  workspace,
  children,
}: {
  workspace: WorkspaceSummary
  children: React.ReactNode
}) {
  return (

export type TaskListQuery = {
  page: number
  pageSize: number
  search?: string
  status?: string
  priority?: string
}

export function normalizeTaskListQuery(
  searchParams: URLSearchParams,
): TaskListQuery {
  return {
    page: Math.max(1, Number(searchParams.get("page") ?? 1)),
    pageSize: Math.min(100, Math.max(1, Number(searchParams.get("pageSize") ?? 20))),
    search: searchParams.get("search")?.trim() || undefined,
    status: searchParams.get("status") || undefined,
    priority: searchParams.get("priority") || undefined,
  }
}

# Phase 23 State Architecture Test Matrix

1. Change status filter -> URL changes, page resets to 1.
2. Refresh -> same filter/page reconstructs.
3. Back/Forward -> collection follows browser history.
4. Background query refetch -> Task table updates without a copied local array.
5. Dirty edit form -> query refetch does not overwrite unsaved draft.
6. Successful save -> form reset + relevant query cache updated/invalidated.
7. Mobile menu -> local interaction only; no global store.
8. Logout -> Query cache cleared; previous user server data not shown.
9. Workspace route change -> resolved workspace Context updates from route/server owner.
10. Derived completed count -> changes automatically with task data, no effect synchronization.