Which library should I use?

Who owns this state?
Who is allowed to change it?
What is the source of truth?
What is the lifecycle?
What is the authority?
What is the invalidation rule?
What is the reset boundary?
What is the failure mode?
How do we test and observe it?

Render describes UI.
Events express intent.
Reducers compute transitions.
Effects synchronize external systems.
Queries synchronize server state.
Machines orchestrate workflows.
Stores share client-owned state.
Context passes scoped dependencies or capabilities.

function UserEditor({ user }: { user: User }) {
  const [name, setName] = useState(user.name);
  const [profile, setProfile] = useState(user);

  // Which one is authoritative?
}

function UserEditor({ user }: { user: User }) {
  const [draft, setDraft] = useState(() => ({ name: user.name }));

  function resetFromUser(nextUser: User) {
    setDraft({ name: nextUser.name });
  }

  function submit() {
    return saveUserName({ userId: user.id, name: draft.name });
  }
}

1. Who creates it?
2. Who reads it?
3. Who writes it?
4. Who resets it?
5. Who persists it?
6. Who invalidates it?
7. Who observes it?
8. Who owns failure recovery?

fetches data
owns form state
owns modal state
checks permission
formats domain data
handles navigation
renders layout
performs mutation
logs analytics
contains retry policy
contains accessibility behavior

microfrontend bridge
analytics event channel
external runtime subscription
cross-tab browser event
WebSocket push event adapter

theme
direction
density
form field metadata
compound component coordination
permission capability
modal service
analytics capability
logger
feature flags
clock/id generator for testing
stable command object

rapidly changing text input
large entity collection
server response cache
scroll position
mouse position
notification feed
every app setting in one AppContext
raw setter bag

Context is a dependency passing mechanism first.
It can carry state, but it is not automatically a good state manager.

Is the provider placed at the smallest correct scope?
Is the context value stable?
Can state and actions be split?
Does every consumer need every field?
Can high-frequency state move to an external store?
Can server state move to a query cache?
Does the provider hide dependencies that should be explicit props?

Rules of Hooks are obeyed.
Render stays pure.
Effects synchronize external systems only.
Effect dependencies reflect reactive values.
No event-specific logic is hidden inside Effects.
Refs are not used to bypass render correctness.
Memoization is not used as a correctness patch.
Custom hooks expose a coherent protocol.
Cleanup is symmetric with setup.
Async work has cancellation or stale-result guards.
Strict Mode does not reveal leaks or hidden assumptions.

const { data, setData, loading, setLoading, error, setError } = useUserThing();

const userProfile = useUserProfile(userId);

userProfile.snapshot;
userProfile.rename({ name: "Ayu" });
userProfile.resetDraft();
userProfile.canSubmit;

type Event =
  | { type: "draft.changed"; field: "name"; value: string }
  | { type: "submit.requested" }
  | { type: "submit.succeeded"; saved: User }
  | { type: "submit.failed"; error: string };

type Event =
  | { type: "setName"; value: string }
  | { type: "setLoading"; value: boolean }
  | { type: "setError"; value: string | null };

Events represent user/system intent.
State shape prevents impossible combinations.
Transitions are pure.
Async work stays outside reducer.
Stale async results are guarded by request ID or machine state.
Selectors hide internal shape.
Transition table can be tested independently.

type Store<T> = {
  getState(): T;
  setState(updater: T | ((prev: T) => T)): void;
  subscribe(listener: () => void): () => void;
};

function useStore<T, S>(
  store: Store<T>,
  selector: (state: T) => S,
  isEqual: (a: S, b: S) => boolean = Object.is,
): S {
  // In production, use useSyncExternalStore or a library that implements it correctly.
  // The important contract: snapshot must be stable if underlying data did not change.
  throw new Error("Sketch only");
}

Does the store own client state, not server cache?
Are snapshots immutable or stable?
Are selectors narrow?
Is equality correct?
Is store lifetime explicit: singleton, provider-scoped, request-scoped, or test-scoped?
Is persistence versioned and validated?
Does SSR/hydration need getServerSnapshot?
Are actions domain-level instead of setter bags?

A global store exists because passing props felt annoying.

What does this UI currently intend?

What do we currently believe about remote authority?

query identity
freshness policy
cache lifetime
invalidation policy
mutation lifecycle
optimistic strategy
rollback or compensation
refetch triggers
SSR/hydration strategy
error taxonomy
permission drift handling

const casesKeys = {
  all: ["cases"] as const,
  list: (tenantId: string, filters: CaseFilters) =>
    ["cases", tenantId, "list", canonicalizeFilters(filters)] as const,
  detail: (tenantId: string, caseId: string) =>
    ["cases", tenantId, "detail", caseId] as const,
};

Is the command idempotent?
Can duplicate submit happen?
What query keys are affected?
Is optimistic UI safe?
What is rollback behavior?
What is conflict behavior?
Should cache be directly updated or invalidated?
What happens after navigation?
How is server validation displayed?

search query
filters
sort
page/cursor
selected tab when meaningful
view mode
entity id
modal route when deep-linkable

password/token/private data
large unsaved draft
high-frequency cursor position
non-serializable state
internal implementation flags

Is it serializable?
Is it canonicalized?
Is it validated at read boundary?
Does changing it reset dependent state?
Does it affect query keys?
Does browser back/forward behave correctly?
Does it leak sensitive information?

multi-step onboarding
approval lifecycle
upload with retry/cancel
payment flow
bulk action confirmation
review/submit/rollback
case escalation
permission-sensitive task flow

type State = {
  isOpen: boolean;
  isSubmitting: boolean;
  isSuccess: boolean;
  isError: boolean;
  isRetrying: boolean;
  isCancelled: boolean;
};

type State =
  | { status: "idle" }
  | { status: "editing"; draft: Draft }
  | { status: "submitting"; draft: Draft; requestId: string }
  | { status: "failed"; draft: Draft; error: string }
  | { status: "succeeded"; result: Result };

Are states explicit?
Are transitions named?
Are illegal states impossible?
Are guards centralized?
Are effects invoked from transition boundaries?
Is cancellation modeled?
Is retry modeled?
Is stale async result impossible or ignored?
Is navigation/back-button behavior defined?
Is observability evented by transition?

1. What state changed?
2. Who owns that state?
3. How large is the render radius?
4. Which identities changed?
5. Which context providers changed?
6. Which external store selectors changed?
7. Which effects ran after commit?
8. Which layout work blocked paint?
9. Which list or subtree is too large?
10. Which network/cache behavior caused churn?

Add useMemo everywhere.

Is there a measured bottleneck?
Is the calculation expensive?
Is identity stability needed by memoized children or effect dependencies?
Can state be moved lower instead?
Can context be split instead?
Can selector subscription reduce rerender radius?
Will React Compiler handle this in compatible code?
Does memoization hide a correctness bug?

keyboard behavior
focus entry
focus return
focus containment
active descendant or roving tabindex model
ARIA roles/states/properties
labeling relationship
disabled/readonly behavior
screen reader announcement strategy
error message association

Test behavior, contracts, and invariants.
Do not test implementation choreography unless choreography is the contract.

type UiTelemetryEvent = {
  name: string;
  feature: string;
  entityType?: string;
  entityId?: string;
  correlationId?: string;
  workflowId?: string;
  fromState?: string;
  toState?: string;
  command?: string;
  outcome?: "started" | "succeeded" | "failed" | "cancelled" | "ignored";
  durationMs?: number;
  errorCode?: string;
};

user intent
command requested
mutation started/succeeded/failed
query invalidated/refetched
workflow transition
optimistic applied/rolled back
permission decision
modal opened/resolved/cancelled
navigation committed
error boundary triggered
performance hot path

Log structure and identifiers only when allowed.
Do not log private field values, credentials, tokens, or sensitive free text.

1. Name the state and owner.
2. Remove redundant derived state.
3. Move event-specific logic out of Effects.
4. Replace setter bags with intent callbacks.
5. Extract reducer when transitions are related.
6. Move server-owned data to query cache.
7. Move URL-worthy state to URL.
8. Split context by domain and volatility.
9. Move high-frequency shared state to external store with selectors.
10. Model workflow with machine/actor when transition space grows.
11. Extract page orchestration from view components.
12. Add tests for invariants before deeper refactor.
13. Add observability for production transition failures.

# ADR: <Decision Title>

## Status
Proposed | Accepted | Deprecated | Superseded

## Context
What problem are we solving?
What state exists?
Who reads it?
Who writes it?
Who owns authority?
What failure modes exist today?

## Decision
We will use <local state | reducer | context | external store | query cache | URL state | state machine> for <scope>.

## Ownership
- Source of truth:
- Writers:
- Readers:
- Reset boundary:
- Invalidation rule:
- Persistence rule:

## Alternatives Considered
1. Alternative A
   - Pros:
   - Cons:
2. Alternative B
   - Pros:
   - Cons:

## Consequences
Positive:
Negative:
Operational risk:
Testing impact:
Observability impact:
Migration impact:

## Review Trigger
Revisit this decision when:
- update frequency changes
- sharing radius changes
- server authority changes
- performance budget is violated
- workflow complexity grows

Is every state value classified?
Is there exactly one source of truth?
Are derived values computed instead of stored?
Are reset semantics explicit?
Is state colocated as low as possible but as high as necessary?

Are hooks called only at valid locations?
Are effects actual synchronization, not derivation?
Are dependencies correct?
Is async work race-safe?
Are refs used only as escape hatches?

Does each component have a clear role?
Are public props stable and meaningful?
Are callbacks intent-based?
Are controlled/uncontrolled semantics documented?
Are accessibility contracts met?

Is Context scoped narrowly?
Is provider value stable?
Is high-frequency state outside broad Context?
Are external store snapshots stable?
Are selectors narrow and equality rules correct?

Are query keys complete and canonical?
Is freshness policy intentional?
Is invalidation scoped correctly?
Is optimistic behavior safe?
Are duplicate commands handled?

Are legal states explicit?
Are illegal states impossible?
Are transitions named?
Are permission/precondition checks explicit?
Are retry/cancel/failure paths modeled?

Was performance measured before optimizing?
Is render radius acceptable?
Are large lists virtualized when needed?
Are context/provider fan-outs controlled?
Are layout effects minimized?

Are reducer/machine invariants tested?
Are server-state flows tested with isolated cache?
Are UI interactions tested at observable boundary?
Are important transitions observable in production?
Are sensitive values excluded from telemetry?

case detail header
permission-aware actions
case timeline
editable notes
document upload
approval workflow
related entities tab
notifications
modal confirmation
server validation
optimistic status update
route-shareable filters

Put everything in one page component and pass props.
If prop drilling hurts, create CaseContext.
If that gets slow, add useMemo.

Server authority:
- case detail query
- timeline query
- related entities query
- upload mutation
- approval mutation

URL authority:
- active tab
- timeline filters
- related entity filters

Local state:
- note draft
- upload drag state
- unsaved modal state

Workflow state:
- approval command lifecycle
- upload lifecycle
- discard-confirmation flow

Context/capability:
- permission decision service
- modal service
- analytics service
- design-system form field context

External store:
- notification connection status
- cross-page notification badge if client-owned and high-frequency

Component composition:
- headless tabs
- modal orchestrator
- permission gate
- form field primitives

Testing:
- query key tests
- mutation rollback tests
- reducer/machine transition tests
- page integration test
- Storybook state scenarios

Observability:
- command requested/succeeded/failed
- optimistic applied/rolled back
- permission denied
- workflow transition
- stale update ignored

State should be owned, not scattered.
Render should describe, not execute.
Effects should synchronize, not derive.
Context should pass capability, not hide everything.
Callbacks should express intent, not expose internals.
Reducers should encode transitions, not setter aliases.
Stores should share client-owned state, not server truth.
Queries should model server authority, freshness, and invalidation.
URL should hold shareable navigation state.
Machines should protect workflows from impossible states.
Performance should be profiled, not guessed.
Accessibility should be a contract, not decoration.
Testing should protect behavior and invariants.
Observability should make state transitions visible.
ADRs should preserve why, not only what.

Part 123 — Final Architecture Playbook

runtime model
hook correctness
state topology
composition
context passing
component communication
client stores
server state
concurrency
workflow orchestration
architecture boundaries
testing
observability
case studies
build-from-scratch systems