“We use this store/provider/cache because someone chose it two years ago, but nobody remembers why.”

const [selectedCaseId, setSelectedCaseId] = useState<string | null>(null);

We decided to use Zustand because it is simple.

We decided to use a feature-scoped Zustand store for the case workbench selection model because:
- selection is shared across toolbar, table, keyboard shortcuts, and side panel
- update frequency is moderate but affects many non-parent/child components
- URL should contain only committed filter/search state, not volatile selection
- Context caused unnecessary rerender fan-out during keyboard navigation
- Redux Toolkit is not needed because transitions are feature-local and do not require organization-wide middleware/governance

[ ] Choosing Context vs Zustand vs Redux Toolkit
[ ] Introducing TanStack Query / RTK Query / custom server-state cache
[ ] Moving route filters into URL state
[ ] Creating a shared provider used by many features
[ ] Creating a global overlay/modal orchestration layer
[ ] Introducing a state machine for a workflow
[ ] Persisting client state in localStorage/IndexedDB
[ ] Sharing state across microfrontends
[ ] Introducing React Compiler constraints
[ ] Changing component library controlled/uncontrolled policy
[ ] Centralizing permission-aware UI behavior
[ ] Normalizing client-side entity state
[ ] Creating a cross-feature event bus

[ ] Local input state inside one component
[ ] useState vs useReducer for a tiny isolated component
[ ] Internal ref for focus or timer
[ ] One-off memoization after profiler finding
[ ] Component-specific derived value

# ADR-XXXX: <Decision Title>

## Status

Proposed | Accepted | Superseded | Deprecated | Rejected

## Date

YYYY-MM-DD

## Decision Drivers

- <force 1>
- <force 2>
- <force 3>

## Context

What problem are we solving?
What state exists?
Who reads it?
Who mutates it?
What are the failure modes today?

## State Classification

- State kind: local | lifted | context | URL | server | external store | workflow | persistent | capability
- Owner:
- Mutators:
- Observers:
- Lifecycle:
- Authority:
- Reset boundary:
- Serialization requirement:
- Performance sensitivity:

## Options Considered

### Option A — <name>

Pros:
- ...

Cons:
- ...

Failure modes:
- ...

### Option B — <name>

Pros:
- ...

Cons:
- ...

Failure modes:
- ...

## Decision

We will ...

## Consequences

Positive:
- ...

Negative:
- ...

Neutral / accepted trade-offs:
- ...

## Implementation Rules

- ...

## Migration Plan

1. ...
2. ...
3. ...

## Enforcement

- tests
- lint rules
- code owners
- package boundaries
- review checklist

## Review Date

YYYY-MM-DD or condition

## References

- ...

State kind:
Owner:
Mutators:
Observers:
Lifecycle:
Authority:
Reset boundary:
Serialization:
Performance sensitivity:
Concurrency risk:
Persistence/privacy risk:

State kind: URL state + server state
Owner: route/search params own committed filters; backend owns result data
Mutators: filter form submit, saved view selection, back/forward navigation
Observers: search page, export button, dashboard breadcrumb
Lifecycle: survives reload and can be shared
Authority: URL for filter intent, backend for data
Reset boundary: route change or clear filters action
Serialization: required, compact, non-sensitive
Performance sensitivity: medium; query key changes trigger fetch
Concurrency risk: low
Persistence/privacy risk: avoid personal notes and raw free-text if logging policy disallows it

# ADR-0017: Store committed case search filters in URL search params

## Status

Accepted

## Date

2026-07-08

## Decision Drivers

- Search results must be shareable between investigators.
- Browser back/forward must restore filter state.
- Reload should not lose committed search state.
- Draft input while typing should not trigger every query.
- Filters must become part of TanStack Query key.

## Context

The case search page currently keeps filters in component state. Users copy links but recipients see default filters. Back/forward navigation also loses intent. Several components need to observe committed filters: results table, export button, saved-search indicator, and breadcrumb.

## State Classification

- State kind: URL state for committed filters, local state for draft inputs
- Owner: router/search params
- Mutators: submit filter form, clear filters, saved-search load, browser navigation
- Observers: table query hook, export action, breadcrumb, saved-search indicator
- Lifecycle: survives reload/share/back-forward
- Authority: URL owns filter intent; backend owns result data
- Reset boundary: clear filters or route change
- Serialization requirement: compact query params
- Performance sensitivity: medium; committed change triggers query refetch

## Options Considered

### Option A — Keep filters in local component state

Pros:
- Simple
- No serialization

Cons:
- Not shareable
- Back/forward broken
- Export button needs prop threading

Failure modes:
- User thinks link includes filters but it does not

### Option B — Store filters in Context

Pros:
- Easy subtree sharing

Cons:
- Not shareable
- Still not reload-safe
- Provider lifetime unclear

Failure modes:
- Context becomes page-global dumping ground

### Option C — Store committed filters in URL; keep draft local

Pros:
- Shareable
- Back/forward works
- Query key is deterministic
- Draft typing does not refetch

Cons:
- Requires parse/serialize schema
- URL privacy rules required

Failure modes:
- Poor canonicalization can create duplicate URLs

## Decision

We will store committed case search filters in URL search params. Draft filter input remains local until the user submits or applies filters.

## Consequences

Positive:
- Search links become reproducible
- Query key can derive from canonical filters
- Export and breadcrumb can read committed state

Negative:
- Need parser/canonicalizer
- Need URL privacy policy

## Implementation Rules

- Use `parseCaseSearchParams(searchParams)`.
- Use `serializeCaseSearchParams(filters)`.
- Unknown values are ignored or canonicalized.
- Free-text filters are included only if allowed by privacy policy.
- Query keys must use parsed canonical filter object.

## Enforcement

- Unit tests for parser/serializer round trip
- E2E test for back/forward navigation
- Review checklist for new filters

# ADR-0021: Use TanStack Query for case-management server state

## Status

Accepted

## Decision Drivers

- Multiple pages fetch overlapping server resources.
- Manual `useEffect` fetch logic creates duplicate request, race, and stale UI bugs.
- Mutations need invalidation and optimistic update patterns.
- Loading/error state must be consistent across product surfaces.

## Context

Case detail, task list, comments, penalties, and activity timeline are server-owned resources. Current pages fetch with local Effects and store results in component state. There is no shared invalidation model after mutation.

## State Classification

- State kind: server state cache
- Owner: backend owns truth; QueryClient owns cache
- Mutators: mutations through domain API hooks
- Observers: route-level pages and feature components
- Lifecycle: cache lifetime controlled by query config
- Authority: backend
- Reset boundary: query invalidation, logout, tenant change
- Serialization requirement: query keys must be serializable
- Performance sensitivity: high on case detail pages

## Options Considered

### Option A — Continue fetching in `useEffect`

Pros:
- No new library

Cons:
- Manual race handling
- No global invalidation
- Repeated boilerplate
- SSR/preload harder

### Option B — Store server data in Redux/Zustand

Pros:
- One familiar shared store

Cons:
- Requires custom cache lifecycle
- Server freshness/invalidation becomes hand-rolled
- High risk of treating cache as authority

### Option C — Use TanStack Query

Pros:
- Query key model
- Cache lifecycle
- Invalidation
- Mutations
- Optimistic update support
- Devtools and ecosystem

Cons:
- Requires query key governance
- Requires clear distinction between server state and client state

## Decision

We will use TanStack Query for server-owned state. Client workflow state remains in local reducers/state machines or feature stores.

## Implementation Rules

- Every query uses a query key factory.
- Query hooks live in feature/domain API layer.
- Mutations must define invalidation or direct cache update policy.
- Do not copy query data into client store unless creating a deliberate draft.
- Logout clears sensitive query cache.

## Enforcement

- ESLint/review rule against new `useEffect` data fetching in pages without justification
- Query key factory tests
- Mutation impact map in feature docs

# ADR-0028: Use selector-based feature store for workbench selection state

## Status

Accepted

## Decision Drivers

- Selection changes frequently via mouse and keyboard.
- Toolbar, side panel, table rows, shortcut manager, and bulk action bar need selection state.
- Context caused broad rerenders on every selection change.
- State is not shareable/bookmarkable and should not be in URL.

## Context

The enforcement workbench needs row selection state across non-parent/child components. Initial implementation used Context with `{ selectedIds, setSelectedIds }`. Profiling showed wide rerender fan-out during keyboard selection.

## State Classification

- State kind: shared client state, feature-scoped external store
- Owner: workbench feature
- Mutators: row selection commands, keyboard shortcuts, clear action
- Observers: toolbar, row checkbox, bulk panel, side panel
- Lifecycle: route/page lifetime
- Authority: client
- Reset boundary: route leave, dataset change, explicit clear
- Serialization: not required
- Performance sensitivity: high

## Options Considered

### Option A — Keep Context

Pros:
- Simple
- No external dependency

Cons:
- Provider value changes rerender broad subtree
- Needs heavy component splitting/memoization

### Option B — Lift state to page and prop drill

Pros:
- Explicit

Cons:
- Prop threading through unrelated layers
- Still broad render radius

### Option C — Feature-scoped selector store

Pros:
- Fine-grained subscription
- Feature-owned
- No URL leakage
- Better keyboard performance

Cons:
- More abstraction
- Requires store lifecycle discipline

## Decision

Use a feature-scoped selector-based store for workbench selection state.

## Implementation Rules

- Store is created per workbench route instance.
- Expose hooks such as `useIsCaseSelected(caseId)` and commands such as `toggleCaseSelection(caseId)`.
- Do not expose raw root state.
- Reset when dataset identity changes.

## Enforcement

- Performance regression test for large selection list
- Unit tests for selection invariants
- Public API exports only from `features/workbench-selection`

# ADR-0034: Model approval submission as a finite state machine

## Status

Accepted

## Decision Drivers

- Approval workflow has mutually exclusive states.
- Several invalid transitions currently occur in edge cases.
- Async server validation can complete after user cancels.
- Audit and permission decisions must be explainable.

## Context

Approval UI currently uses booleans: `isSubmitting`, `isConfirmOpen`, `hasError`, `isSuccess`, `isValidating`. Bug reports show impossible states such as success banner while confirmation modal remains open.

## State Classification

- State kind: workflow state
- Owner: approval feature
- Mutators: workflow events
- Observers: approval panel, confirmation modal, audit note, submit button
- Lifecycle: case detail route lifetime
- Authority: client owns UI phase; backend owns final approval state
- Reset boundary: case change or completed action
- Serialization: no, except audit command payload
- Performance sensitivity: low
- Concurrency risk: high due to async validation/submit

## Options Considered

### Option A — Continue with booleans

Pros:
- Minimal rewrite

Cons:
- Impossible states remain possible
- Edge transitions spread across handlers

### Option B — `useReducer` transition model

Pros:
- Consolidates transitions
- Easy to test

Cons:
- Invoked async lifecycle still manual

### Option C — State machine with invoked services

Pros:
- Explicit states/transitions
- Guards/actions separated
- Async service cancellation model
- Better visualization/testing

Cons:
- New mental model for some engineers

## Decision

Use a finite state machine for approval submission workflow.

## Implementation Rules

- Machine states must be named by product phase, not booleans.
- Backend mutation remains in service/action boundary.
- Every async response must match current request id or actor lifecycle.
- Permission denial is an expected transition, not generic error.

## Enforcement

- Transition table tests
- Storybook stories for every state
- E2E test for cancel-while-submitting

# ADR-0042: Do not share a mutable domain store across microfrontends

## Status

Accepted

## Decision Drivers

- Microfrontends are independently deployed.
- Shared mutable store creates release coupling.
- Backend owns case lifecycle authority.
- Cross-MFE coordination should be explicit and versioned.

## Context

Several remotes need to react when a case is updated. A proposal suggested a shared `caseStore` utility module imported by every remote.

## State Classification

- State kind: server state + cross-app notification event
- Owner: backend owns case state; shell owns event bridge
- Mutators: API mutations through feature remotes
- Observers: other remotes via invalidation/refetch
- Lifecycle: entity lifecycle is server-owned
- Authority: backend
- Reset boundary: logout/tenant switch/cache invalidation
- Serialization: event payload must be versioned
- Release risk: high

## Options Considered

### Option A — Shared mutable case store

Pros:
- Immediate in-browser synchronization

Cons:
- Hidden coupling
- Version drift risk
- Cache becomes mistaken for authority
- Hard to audit mutation source

### Option B — Each remote fetches independently, no coordination

Pros:
- Strong isolation

Cons:
- Stale UI after mutation
- Poor UX consistency

### Option C — Versioned invalidation events + server refetch

Pros:
- Explicit contract
- Backend remains authority
- Remotes stay independently deployable
- Event payload stays small

Cons:
- Requires event schema and invalidation handling

## Decision

Use versioned invalidation events and server refetch. Do not share mutable domain store across remotes.

## Implementation Rules

- Mutation remote publishes `case.updated` with `{ caseId, reason }`.
- Receiving remotes invalidate/refetch their own query cache.
- Event payload does not carry full canonical entity.
- Event schema includes `version`.

## Enforcement

- Package boundary rule preventing import of remote internals
- Contract tests for event schema
- Shell integration test for mutation/refetch flow

Consequences: cleaner state management.

Positive:
- Query invalidation becomes consistent.
- Fetch race handling moves out of components.
- Loading/error states become easier to standardize.

Negative:
- Engineers must learn query key design.
- Cache lifetime decisions need review.
- Tests need QueryClient harness.

Accepted risks:
- Some mutation flows may initially over-invalidate.
- Query key namespace may need refactoring as API grows.

features/case-search/
  model/
  api/
  ui/
  index.ts   <-- public API only

What state kind is this?
Who owns it?
Who mutates it?
What resets it?
Could it be derived?
Does it need persistence?
Does it need URL/shareability?
Does it duplicate server state?
Does it widen render radius?
Does it need an ADR update?

ADR-0010-zustand.md

ADR-0010-use-feature-scoped-selector-store-for-workbench-selection.md

ADR-0011-tanstack-query.md

ADR-0011-use-server-state-cache-for-case-api-resources.md

docs/
  adr/
    0001-use-url-state-for-case-search-filters.md
    0002-use-server-state-cache-for-case-api-resources.md
    0003-use-state-machine-for-approval-submission.md
    index.md

docs/
  adr/
    frontend/
      state/
      routing/
      design-system/
      microfrontend/
    backend/
    platform/

# Architecture Decision Records

| ADR | Title | Status | Owner | Date |
|---|---|---|---|---|
| 0017 | Store committed case search filters in URL search params | Accepted | Case Platform | 2026-07-08 |
| 0021 | Use server-state cache for case API resources | Accepted | Frontend Platform | 2026-07-08 |
| 0034 | Model approval submission as a finite state machine | Accepted | Enforcement Workflow | 2026-07-08 |
| 0042 | Do not share mutable domain store across microfrontends | Accepted | Frontend Architecture | 2026-07-08 |

// ADR-0021: server-owned case resources use TanStack Query.
export function useCaseDetail(caseId: string) {
  return useQuery({
    queryKey: caseKeys.detail(caseId),
    queryFn: () => caseApi.getCase(caseId),
  });
}

1. Keep existing Provider API.
2. Introduce internal feature store behind Provider.
3. Replace broad `useWorkbenchContext()` reads with selector hooks.
4. Measure render radius.
5. Deprecate raw context export.
6. Remove old provider value shape after two releases.

- symptom
- profiler evidence
- current actualDuration/baseDuration if available
- interaction affected
- target behavior
- options considered
- expected blast radius
- validation plan after implementation

Profiling keyboard row selection showed that selecting one row re-rendered the entire workbench subtree. The broad render radius came from Context value identity changes. We will replace selection Context with a feature-scoped selector store and validate with React Profiler on a 5,000-row virtualized list fixture.

Is frontend permission only UX guard?
Where is final authorization enforced?
What does disabled vs hidden mean?
How is denial reason represented?
How are stale permission decisions handled?
What is logged/audited?

Frontend permission gates may hide navigation affordances for unavailable capabilities, but destructive action buttons remain visible as disabled with reason tooltip when the user can see the resource but lacks action permission. Backend remains final enforcement point. Permission API returns structured decision objects.

ADR-0050: Modal components emit structured close reasons

Decision:
All modal-like primitives emit `onOpenChange(nextOpen, meta)` where `meta.reason` is one of `escape`, `backdrop`, `close-button`, `programmatic`, or `submit-success`.

Consequence:
Consumers can distinguish accidental dismissal from successful completion without reverse-engineering DOM events.

We chose Redux because it is scalable.

We chose Redux Toolkit because this state is mutated by six teams, needs action logging, middleware-based workflow integration, normalized entity storage, and stronger governance than feature-scoped stores.

Use Context carefully.

Context may be used for low-frequency subtree dependencies. High-frequency interaction state must use local state, selector store, or reducer boundary. Provider values containing objects/functions must be memoized or split.

[ ] Does it classify the state kind?
[ ] Does it name the owner?
[ ] Does it name mutators and observers?
[ ] Does it define lifecycle and reset boundary?
[ ] Does it distinguish client-owned from server-owned state?
[ ] Does it explain why simpler options were rejected?
[ ] Does it include negative consequences?
[ ] Does it define implementation rules?
[ ] Does it define enforcement?
[ ] Does it mention migration/reversal path?
[ ] Does it include tests or observability impact?
[ ] Does it have a review/supersession condition?

Should this state be in URL?
Should this use Context?
Why do we use TanStack Query here?
Why not put this in Redux?
Why is this workflow a state machine?
Why can't this remote import that store?
Why does this component expose close reason?