familysync/.planning/phases/04-shared-lists-live-sync/04-PATTERNS.md

# Phase 4: Shared Lists + Live Sync — Pattern Map

**Mapped:** 2026-06-09
**Files analyzed:** 18 new/modified files
**Analogs found:** 16 / 18

---

## File Classification

| New/Modified File | Role | Data Flow | Closest Analog | Match Quality |
|-------------------|------|-----------|----------------|---------------|
| `apps/api/src/db/schema.ts` | model (modify) | CRUD | self | exact |
| `apps/api/src/db/migrations/0002_lists_schema.sql` | migration | batch | `0001_calendars_user_url_unique.sql` | role-match |
| `apps/api/src/lib/listEmitter.ts` | utility | event-driven | none in codebase | no analog |
| `apps/api/src/routes/lists.ts` | route/controller | CRUD | `apps/api/src/routes/events.ts` | exact |
| `apps/api/src/routes/sse.ts` | route (modify) | streaming | self | exact |
| `apps/api/src/index.ts` | config (modify) | request-response | self | exact |
| `apps/pwa/src/App.tsx` | component (modify) | request-response | self | exact |
| `apps/pwa/src/components/BottomTabBar.tsx` | component | request-response | `apps/pwa/src/components/AppNav.tsx` | role-match |
| `apps/pwa/src/routes/ListsIndex.tsx` | component | CRUD | `apps/pwa/src/components/CalendarShell.tsx` | role-match |
| `apps/pwa/src/routes/ListDetail.tsx` | component | CRUD + event-driven | `apps/pwa/src/components/CalendarShell.tsx` | role-match |
| `apps/pwa/src/components/ListCard.tsx` | component | request-response | `apps/pwa/src/components/DeleteConfirmationDialog.tsx` | role-match |
| `apps/pwa/src/components/ItemRow.tsx` | component | event-driven | `apps/pwa/src/components/DeleteConfirmationDialog.tsx` | role-match |
| `apps/pwa/src/components/AddItemInput.tsx` | component | request-response | `apps/pwa/src/components/DeleteConfirmationDialog.tsx` | role-match |
| `apps/pwa/src/components/CreateListSheet.tsx` | component | request-response | `apps/pwa/src/components/DeleteConfirmationDialog.tsx` | role-match |
| `apps/pwa/src/components/LiveSyncIndicator.tsx` | component | event-driven | none — novel | no analog |
| `apps/pwa/src/components/ListsEmptyState.tsx` | component | request-response | `apps/pwa/src/components/SkeletonCalendar.tsx` | role-match |
| `apps/pwa/src/hooks/useListSSE.ts` | hook | event-driven | none in codebase | no analog |
| `apps/pwa/src/api/listsClient.ts` | utility | request-response | `apps/pwa/src/api/client.ts` | exact |
| `apps/pwa/src/store/listsStore.ts` | store | request-response | `apps/pwa/src/store/calendarStore.ts` | exact |

---

## Pattern Assignments

### `apps/api/src/db/schema.ts` (model, CRUD — append new tables)

**Analog:** self — read `apps/api/src/db/schema.ts` lines 1–163 in full above.

**Imports pattern** (lines 1–13):
```typescript
import {
  mysqlTable,
  varchar,
  int,
  timestamp,
  boolean,
  index,
  unique,
} from 'drizzle-orm/mysql-core'
```
Note: `mysqlEnum` is imported for `calendarOutbox` but is not needed for list tables. Import only what the new tables use.

**Table definition pattern** (lines 40–54, `memberCredentials` — simplest table with FK):
```typescript
export const memberCredentials = mysqlTable(
  'member_credentials',
  {
    id: int().primaryKey().autoincrement(),
    userId: int('user_id')
      .notNull()
      .references(() => users.id, { onDelete: 'cascade' }),
    encryptedPassword: text('encrypted_password').notNull(),
    createdAt: timestamp('created_at').defaultNow().notNull(),
    updatedAt: timestamp('updated_at').defaultNow().onUpdateNow(),
  },
  (t) => [index('idx_member_credentials_user_id').on(t.userId)],
)
```

**Composite unique key pattern** (lines 61–86, `calendars`):
```typescript
(t) => [
  index('idx_calendars_user_id').on(t.userId),
  unique('uniq_calendar_user_url').on(t.userId, t.url),
]
```

**New tables to append** — follow the schema from RESEARCH.md §Database Schema Design exactly:
- `lists` — int PK, `owner_id` FK to `users`, `name varchar(255)`, `is_shared boolean DEFAULT true`, `created_at`, `updated_at`; index on `owner_id`
- `listShares` — int PK, `list_id` FK to `lists` cascade, `user_id` FK to `users` cascade, `created_at`; unique on `(list_id, user_id)`, index on `user_id`
- `listItems` — int PK, `list_id` FK to `lists` cascade, `text varchar(500)`, `checked boolean DEFAULT false`, `rank varchar(255)`, `created_at`, `updated_at`; composite index on `(list_id, rank)`, index on `(list_id, checked)`

---

### `apps/api/src/routes/lists.ts` (route, CRUD)

**Analog:** `apps/api/src/routes/events.ts` (full file above)

**File header doc-block pattern** (lines 1–22 of events.ts):
```typescript
/**
 * Lists router — list + item CRUD with SSE fan-out trigger.
 *
 * Security:
 *   - All endpoints resolve currentUserId via resolveUserId (returns null → 401).
 *   - Access control: list must be owned by currentUser OR appear in list_shares.
 *   - Drizzle parameterized queries prevent SQL injection.
 *   - zod validates all write payloads (name max 255, text max 500).
 *
 * Mounted under /api/* in index.ts — behind oidcAuthMiddleware.
 */
```

**Imports pattern** (lines 24–37 of events.ts):
```typescript
import { Hono } from 'hono'
import { zValidator } from '@hono/zod-validator'
import { z } from 'zod'
import { and, or, eq } from 'drizzle-orm'
import { db } from '../db/client.js'
import { lists, listItems, listShares, users } from '../db/schema.js'
import { getAuth } from '../auth/middleware.js'
import { upsertUser, deriveDisplayName } from '../auth/user.js'
import { publishListEvent } from '../lib/listEmitter.js'
import '../auth/devBypass.js'

export const listsRouter = new Hono()
```

**`resolveUserId` helper** — copy verbatim from `events.ts` lines 59–76. This function is duplicated per router (not extracted to a shared module) — maintain that pattern.

**Zod schema pattern** (lines 82–105 of events.ts):
```typescript
const createListSchema = z.object({
  name: z.string().min(1).max(255),
  isShared: z.boolean().default(true),
})

const createItemSchema = z.object({
  text: z.string().min(1).max(500),
})

// Per-field PATCH — enforce exactly one field per D-08
const patchItemSchema = z
  .object({
    checked: z.boolean(),
    text: z.string().min(1).max(500),
    position: z.string().min(1).max(255),
  })
  .partial()
  .refine((obj) => Object.keys(obj).length === 1, {
    message: 'PATCH must update exactly one field',
  })
```

**Route handler pattern** — GET with auth + access check + try/catch (lines 122–221 of events.ts):
```typescript
listsRouter.get('/', async (c) => {
  const currentUserId = await resolveUserId(c)
  if (currentUserId === null) return c.json({ error: 'Unauthorized' }, 401)

  try {
    // SELECT lists WHERE owner_id = ? OR id IN (SELECT list_id FROM list_shares WHERE user_id = ?)
    const rows = await db
      .select({ /* ... */ })
      .from(lists)
      .where(or(eq(lists.ownerId, currentUserId), /* join with listShares */ ))

    return c.json({ lists: rows })
  } catch (err) {
    console.error('[lists] DB query failed:', err)
    return c.json({ error: 'Service unavailable' }, 503)
  }
})
```

**Fan-out trigger pattern** — call after every successful write:
```typescript
// After insert/update/delete succeeds:
publishListEvent(listId, { type: 'item:added', listId, payload: newItem })
```

**Ownership verification pattern** (lines 326–339 of events.ts):
```typescript
// Verify list access before any item mutation
const [listRow] = await db
  .select({ ownerId: lists.ownerId })
  .from(lists)
  .where(eq(lists.id, listId))

if (!listRow) return c.json({ error: 'Not found' }, 404)

const isOwner = listRow.ownerId === currentUserId
const [shareRow] = isOwner ? [{}] : await db
  .select({ listId: listShares.listId })
  .from(listShares)
  .where(and(eq(listShares.listId, listId), eq(listShares.userId, currentUserId)))

if (!isOwner && !shareRow) return c.json({ error: 'Access denied' }, 403)
```

---

### `apps/api/src/routes/sse.ts` (route, streaming — extend existing)

**Analog:** self — `apps/api/src/routes/sse.ts` lines 1–40 (full file above).

**Core streamSSE pattern** (lines 28–40):
```typescript
sseRouter.get('/heartbeat', (c) => {
  return streamSSE(c, async (stream) => {
    let id = 0
    while (!stream.aborted) {
      await stream.writeSSE({
        data: JSON.stringify({ ts: new Date().toISOString(), id }),
        event: 'heartbeat',
        id: String(id++),
      })
      await stream.sleep(10_000)
    }
  })
})
```

**New `/lists` endpoint** extends this with:
- `resolveUserId(c)` call first → 401 on null (same as events.ts pattern)
- `getAccessibleListIds(userId)` DB query before `streamSSE` call
- `subscribeListEvents(listId, handler)` loop inside `streamSSE`
- Heartbeat loop at 30s cadence (not 10s — Pangolin smoke test used 10s for the heartbeat, 30s is fine for production load)
- Cleanup: `unsubscribers.forEach(unsub => unsub())` after the while loop exits

```typescript
sseRouter.get('/lists', async (c) => {
  const userId = await resolveUserId(c)
  if (!userId) return c.json({ error: 'Unauthorized' }, 401)

  const accessibleListIds = await getAccessibleListIds(userId)

  return streamSSE(c, async (stream) => {
    const unsubscribers: Array<() => void> = []

    for (const listId of accessibleListIds) {
      const unsub = subscribeListEvents(listId, async (event) => {
        if (stream.aborted) return
        await stream.writeSSE({
          data: JSON.stringify(event),
          event: event.type,
          id: `${listId}-${Date.now()}`,
        })
      })
      unsubscribers.push(unsub)
    }

    let tick = 0
    while (!stream.aborted) {
      await stream.writeSSE({
        data: JSON.stringify({ ts: new Date().toISOString() }),
        event: 'heartbeat',
        id: String(tick++),
      })
      await stream.sleep(30_000)
    }

    unsubscribers.forEach((unsub) => unsub())
  })
})
```

---

### `apps/api/src/lib/listEmitter.ts` (utility, event-driven)

**No codebase analog** — this is new. Use the pattern from RESEARCH.md Finding 1 verbatim:

```typescript
import { EventEmitter } from 'node:events'

const emitter = new EventEmitter()
emitter.setMaxListeners(200)

export type ListEvent = {
  type: 'item:added' | 'item:updated' | 'item:deleted' | 'list:updated' | 'list:deleted'
  listId: number
  payload: unknown
}

export function publishListEvent(listId: number, event: ListEvent): void {
  emitter.emit(`list:${listId}`, event)
}

export function subscribeListEvents(
  listId: number,
  handler: (event: ListEvent) => void,
): () => void {
  const channel = `list:${listId}`
  emitter.on(channel, handler)
  return () => emitter.off(channel, handler)
}
```

---

### `apps/api/src/index.ts` (config, modify)

**Analog:** self — lines 1–83 (full file above).

**Route mount pattern** (lines 59–61):
```typescript
app.route('/api/me', meRouter)
app.route('/api/events', eventsRouter)
app.route('/api/sse', sseRouter)
```

**Add after `sseRouter` mount:**
```typescript
import { listsRouter } from './routes/lists.js'
// ...
app.route('/api/lists', listsRouter)
```

**Auto-migrate pattern** — add before `startBrokerPoller()` (line 65):
```typescript
import { migrate } from 'drizzle-orm/mysql2/migrator'
// ...
await migrate(db, { migrationsFolder: './src/db/migrations' })
```

---

### `apps/pwa/src/App.tsx` (component, modify)

**Analog:** self — lines 1–5 (full file above). Currently a one-liner.

**Transform to** (pattern from RESEARCH.md Finding 5):
```tsx
import { BrowserRouter, Routes, Route, Navigate } from 'react-router'
import { CalendarShell } from './components/CalendarShell.js'
import { ListsIndex } from './routes/ListsIndex.js'
import { ListDetail } from './routes/ListDetail.js'
import { BottomTabBar } from './components/BottomTabBar.js'

export default function App() {
  return (
    <BrowserRouter>
      <AppShell />
    </BrowserRouter>
  )
}

function AppShell() {
  return (
    <>
      <Routes>
        <Route path="/" element={<Navigate to="/calendar" replace />} />
        <Route path="/calendar" element={<CalendarShell />} />
        <Route path="/lists" element={<ListsIndex />} />
        <Route path="/lists/:listId" element={<ListDetail />} />
      </Routes>
      <BottomTabBar />
    </>
  )
}
```

---

### `apps/pwa/src/components/BottomTabBar.tsx` (component, request-response)

**Analog:** `apps/pwa/src/components/AppNav.tsx` (nav component with active-state links — check that file if needed for CSS token conventions)

**Key pattern** — NavLink with isActive callback (from RESEARCH.md Finding 5):
```tsx
import { NavLink } from 'react-router'
import { CalendarDays, List } from 'lucide-react'

export function BottomTabBar() {
  return (
    <nav
      style={{
        position: 'fixed',
        bottom: 0,
        left: 0,
        right: 0,
        height: '56px',
        display: 'flex',
        background: 'var(--color-surface)',
        borderTop: '1px solid var(--color-border)',
        zIndex: 100,
      }}
    >
      <NavLink
        to="/calendar"
        className={({ isActive }) => isActive ? 'tab tab--active' : 'tab'}
      >
        <CalendarDays size={22} aria-hidden="true" />
        <span>Calendar</span>
      </NavLink>
      <NavLink
        to="/lists"
        className={({ isActive }) => isActive ? 'tab tab--active' : 'tab'}
      >
        <List size={22} aria-hidden="true" />
        <span>Lists</span>
      </NavLink>
    </nav>
  )
}
```

CSS tokens: use `var(--color-surface)`, `var(--color-border)`, `var(--color-text-primary)`, `var(--color-text-secondary)` — the existing token layer from Phase 2.

---

### `apps/pwa/src/api/listsClient.ts` (utility, request-response)

**Analog:** `apps/pwa/src/api/client.ts` lines 1–53 (full pattern above).

**Imports + credential pattern**:
```typescript
// credentials: 'include' on every fetch — session cookie required (same as client.ts)
const BASE = '/api'

async function apiFetch(path: string, init?: RequestInit): Promise<Response> {
  const res = await fetch(`${BASE}${path}`, {
    credentials: 'include',
    ...init,
  })
  if (!res.ok) throw new Error(`${init?.method ?? 'GET'} ${path} failed: ${res.status}`)
  return res
}
```

**Type + function pattern** (mirrors client.ts):
```typescript
export interface List {
  id: number
  name: string
  isShared: boolean
  ownerId: number
}

export interface ListItem {
  id: number
  listId: number
  text: string
  checked: boolean
  rank: string
}

export async function fetchLists(): Promise<{ lists: List[] }> {
  return apiFetch('/lists').then((r) => r.json())
}

export async function createList(payload: { name: string; isShared: boolean }): Promise<{ id: number }> {
  return apiFetch('/lists', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(payload),
  }).then((r) => r.json())
}

export async function patchListItem(
  itemId: number,
  patch: { checked?: boolean } | { text: string } | { position: string },
): Promise<void> {
  await apiFetch(`/list-items/${itemId}`, {
    method: 'PATCH',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(patch),
  })
}
```

---

### `apps/pwa/src/store/listsStore.ts` (store, request-response)

**Analog:** `apps/pwa/src/store/calendarStore.ts` lines 1–89 (full file above).

**Imports + create pattern** (lines 26–27 of calendarStore.ts):
```typescript
import { create } from 'zustand'

export interface ListsStore {
  // UI-only state — no server data
  activeTab: 'calendar' | 'lists'
  createListSheetOpen: boolean
  // ...

  setActiveTab: (tab: 'calendar' | 'lists') => void
  setCreateListSheetOpen: (open: boolean) => void
}

export const useListsStore = create<ListsStore>()((set) => ({
  activeTab: 'calendar',
  createListSheetOpen: false,
  setActiveTab: (tab) => set({ activeTab: tab }),
  setCreateListSheetOpen: (open) => set({ createListSheetOpen: open }),
}))
```

Convention from calendarStore.ts: no `persist` middleware used in this project — state is ephemeral (view persistence done manually with localStorage in calendarStore; lists UI state does not need persistence).

---

### `apps/pwa/src/routes/ListsIndex.tsx` (component, CRUD)

**Analog:** `apps/pwa/src/components/CalendarShell.tsx` lines 1–60 (header shown above).

**Data fetching pattern** — useQuery with credentials (from CalendarShell + client.ts):
```tsx
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
import { fetchLists, createList, deleteList } from '../api/listsClient.js'

const { data, isLoading, isError } = useQuery({
  queryKey: ['lists'],
  queryFn: fetchLists,
})
```

**State branches** — mirror CalendarShell: `isLoading` → skeleton/empty, `isError` → error state with retry, `data` → render list. CalendarShell uses `isLoading` / `isError` / success branches explicitly.

**useMutation with optimistic update** (from RESEARCH.md Finding 6):
```tsx
const queryClient = useQueryClient()

const deleteMutation = useMutation({
  mutationFn: (listId: number) => deleteList(listId),
  onMutate: async (listId) => {
    await queryClient.cancelQueries({ queryKey: ['lists'] })
    const previous = queryClient.getQueryData(['lists'])
    queryClient.setQueryData(['lists'], (old: any) => ({
      ...old,
      lists: old.lists.filter((l: any) => l.id !== listId),
    }))
    return { previous }
  },
  onError: (_err, _vars, context) => {
    if (context?.previous) queryClient.setQueryData(['lists'], context.previous)
  },
  onSettled: () => {
    queryClient.invalidateQueries({ queryKey: ['lists'] })
  },
})
```

**DeleteConfirmationDialog reuse** — import from `../components/DeleteConfirmationDialog.js` and render conditionally. The existing dialog is tightly coupled to `calendarStore`; create a new list-delete confirmation component (`ListDeleteDialog`) that mirrors its structure but is driven by `listsStore`. Do NOT modify the existing dialog — it is stable (D-06 says reuse, but the implementation is wired to calendarStore).

---

### `apps/pwa/src/routes/ListDetail.tsx` (component, CRUD + event-driven)

**Analog:** `apps/pwa/src/components/CalendarShell.tsx`

**SSE + polling pattern** (from RESEARCH.md Finding 4):
```tsx
import { useListSSE } from '../hooks/useListSSE.js'

const { data } = useQuery({
  queryKey: ['list', listId],
  queryFn: () => fetchListItems(listId),
  refetchInterval: 30_000, // D-12: polling fallback always active
})

useListSSE({ listId, onStateChange: setSyncState })
```

**Active / completed section split** (D-05):
```tsx
const activeItems = items.filter((i) => !i.checked).sort(/* by rank ASC */)
const completedItems = items.filter((i) => i.checked)
```

---

### `apps/pwa/src/components/DeleteConfirmationDialog.tsx` (reuse — no modification)

**This file is not modified.** A new `ListDeleteDialog.tsx` mirrors its structure:
- Same modal layout: fixed backdrop + centered dialog
- Same CSS tokens: `var(--color-overlay)`, `var(--color-surface-raised)`, `var(--color-destructive)`, `var(--space-*)`, `var(--text-*)`, `var(--font-family-base)`
- Same `useMutation` + `onSuccess` → close pattern (lines 64–76 of DeleteConfirmationDialog.tsx)
- Same accessibility: `role="dialog"`, `aria-modal="true"`, Escape key listener, `tabIndex={-1}` + focus on open

Key lines to copy for the modal skeleton (lines 86–208 of DeleteConfirmationDialog.tsx) — swap the heading text to "Delete list?" and the body text to "All items in this list will be permanently deleted."

---

### `apps/pwa/src/components/ItemRow.tsx` (component, event-driven)

**Analog:** `apps/pwa/src/components/DeleteConfirmationDialog.tsx` (for mutation + CSS token patterns)

**dnd-kit drag handle pattern** (from RESEARCH.md Finding 7):
```tsx
import { useSortable } from '@dnd-kit/sortable'
import { CSS } from '@dnd-kit/utilities'
import { GripVertical } from 'lucide-react'

export function ItemRow({ item, onCheck, onDelete }) {
  const { attributes, listeners, setNodeRef, transform, transition, isDragging } =
    useSortable({ id: item.id })

  return (
    <div
      ref={setNodeRef}
      style={{
        transform: CSS.Transform.toString(transform),
        transition: transition ?? 'transform 150ms ease-out', // D-14: animate remote reorders
        opacity: isDragging ? 0.8 : 1,
        display: 'flex',
        alignItems: 'center',
        gap: 'var(--space-2)',
        minHeight: '44px', // touch target
      }}
      {...attributes}
    >
      {/* Drag handle — listeners on handle only (not whole row) */}
      <button
        {...listeners}
        aria-label="Drag to reorder"
        style={{ background: 'none', border: 'none', cursor: 'grab', padding: 'var(--space-1)' }}
      >
        <GripVertical size={16} color="var(--color-text-secondary)" />
      </button>
      {/* ... checkbox, text, delete button */}
    </div>
  )
}
```

---

### `apps/pwa/src/hooks/useListSSE.ts` (hook, event-driven)

**No codebase analog.** Use the pattern from RESEARCH.md Finding 4 verbatim. Key conventions:
- `useCallback` for `connect` to keep the `useEffect` dependency stable
- `esRef`, `attemptsRef`, `timerRef` — all `useRef` (not state) to avoid re-render loops
- Close `es` on error before scheduling retry (prevents browser auto-reconnect stacking with manual reconnect)
- `withCredentials: true` on `new EventSource(...)` — required for session cookie (Pitfall 7)
- Return `syncState` so the caller can render `LiveSyncIndicator`

---

## Shared Patterns

### Auth / User Resolution
**Source:** `apps/api/src/routes/events.ts` lines 59–76
**Apply to:** `apps/api/src/routes/lists.ts`
```typescript
async function resolveUserId(c: any): Promise<number | null> {
  const devUser = c.get('user') as { id: number } | undefined
  if (devUser) return devUser.id

  const auth = await getAuth(c)
  if (!auth) return null

  const iss = (auth.iss as string | undefined) ?? ''
  const sub = auth.sub ?? ''
  const displayName = deriveDisplayName(auth)
  const user = await upsertUser(iss, sub, displayName)
  return user?.id ?? null
}
```
Copy verbatim — do not extract to a shared module (existing convention duplicates this per router).

### Error Handling (API routes)
**Source:** `apps/api/src/routes/events.ts` (every handler's catch block)
**Apply to:** `apps/api/src/routes/lists.ts`
```typescript
try {
  // ... db operations ...
  return c.json({ /* result */ })
} catch (err) {
  console.error('[lists/<endpoint>] DB operation failed:', err)
  return c.json({ error: 'Service unavailable' }, 503)
}
```
Pattern: 503 on caught exceptions, not 500. `console.error` with a `[module/endpoint]` prefix tag.

### 401 Guard Pattern
**Source:** `apps/api/src/routes/events.ts` (every handler, lines 125–126):
```typescript
const currentUserId = await resolveUserId(c)
if (currentUserId === null) return c.json({ error: 'Unauthorized' }, 401)
```
First two lines of every protected handler.

### CSS Token Usage (PWA components)
**Source:** `apps/pwa/src/components/DeleteConfirmationDialog.tsx` (all inline styles)
**Apply to:** all new PWA components
Token set in use:
- `var(--color-surface)`, `var(--color-surface-raised)`, `var(--color-overlay)`
- `var(--color-text-primary)`, `var(--color-text-secondary)`
- `var(--color-destructive)`, `var(--color-border)`
- `var(--space-1)` through `var(--space-6)`
- `var(--text-body-size)`, `var(--text-heading-size)`, `var(--text-label-size)`, `var(--font-family-base)`
- Minimum touch target: `minHeight: '44px'` (buttons/rows)

### Fetch with Credentials (PWA API client)
**Source:** `apps/pwa/src/api/client.ts` lines 36–39
**Apply to:** `apps/pwa/src/api/listsClient.ts`
```typescript
const res = await fetch('/api/...', {
  credentials: 'include',
  redirect: 'manual', // only for /api/me; not required for data endpoints
})
```
All list API calls use `credentials: 'include'`. `redirect: 'manual'` is only needed for the initial session check (`/api/me`) — not for list CRUD endpoints.

### TanStack Query Keys
**Apply to:** `apps/pwa/src/routes/ListsIndex.tsx`, `apps/pwa/src/routes/ListDetail.tsx`
```typescript
// List of lists
queryKey: ['lists']

// Items for a specific list
queryKey: ['list', listId]  // listId is a number
```
Invalidate `['lists']` after create/delete list. Invalidate `['list', listId]` after any item mutation or SSE event for that list.

### Lucide Icons (PWA)
**Source:** `apps/pwa/src/components/DeleteConfirmationDialog.tsx` line 27, CalendarShell.tsx line 43
**Apply to:** all new PWA components
```tsx
import { Trash2 } from 'lucide-react'
// Usage: <Trash2 size={16} aria-hidden="true" />
```
Always pass `aria-hidden="true"` to decorative icons. Use `size={16}` for inline/dense contexts, `size={22}` for navigation tabs.

### Zustand Store Shape
**Source:** `apps/pwa/src/store/calendarStore.ts`
**Apply to:** `apps/pwa/src/store/listsStore.ts`
- Use `create<StoreInterface>()((set) => ({ ... }))` — no `persist`, no `immer`
- Actions are inline setter functions, not separate files
- UI-only state: no server data, no async in store actions (mutations live in components via `useMutation`)

### Plain-text XSS Guard (PWA)
**Source:** `apps/pwa/src/components/DeleteConfirmationDialog.tsx` (comment `/* Plain text — XSS guard */` on every text node, line 133 etc.)
**Apply to:** all new PWA components that render user-supplied strings (list names, item text)
Never use `dangerouslySetInnerHTML`. All user content is a JSX text child.

---

## No Analog Found

| File | Role | Data Flow | Reason |
|------|------|-----------|--------|
| `apps/api/src/lib/listEmitter.ts` | utility | event-driven | No EventEmitter or pub/sub pattern exists in the codebase. Use RESEARCH.md Finding 1 pattern. |
| `apps/pwa/src/components/LiveSyncIndicator.tsx` | component | event-driven | No live-sync state indicator exists. Novel UI component — use CSS token conventions and the "disconnected / updates paused" UX from D-11. |
| `apps/pwa/src/hooks/useListSSE.ts` | hook | event-driven | No custom hooks exist in the codebase. Novel — use RESEARCH.md Finding 4 pattern. |

---

## Metadata

**Analog search scope:** `apps/api/src/routes/`, `apps/api/src/db/`, `apps/api/src/lib/`, `apps/api/src/index.ts`, `apps/pwa/src/`, `apps/pwa/src/components/`, `apps/pwa/src/api/`, `apps/pwa/src/store/`
**Files scanned:** 12 source files read in full
**Pattern extraction date:** 2026-06-09