docs: add agent codebase guide

docs/frontend.md

@@ -0,0 +1,105 @@
+# Dashboard architecture
+
+## Stack and boundary
+
+The operator console is a React 19 + TypeScript + Vite application under `apps/dashboard`. Express serves its production build, private media, API, authentication endpoints, and SSE streams from the same origin. TanStack Query owns server state; React Router owns navigation and route-addressable state.
+
+Shared HTTP/SSE schemas live in `packages/api-contracts`. The server and client should not duplicate transport interfaces by hand.
+
+## Routes
+
+| Route | Responsibility |
+| --- | --- |
+| `/` | Health, per-account delivery/cooldown state, timers, workload, and recent activity. |
+| `/attention` | Human handoffs, delivery failures, account risks, and other actionable items. |
+| `/outreach` | Durable candidate funnel and active candidate detail. |
+| `/conversations` | Searchable account-aware conversation inbox. |
+| `/conversations/:conversationId` | Conversation history, context, suggestions, and guarded sending. |
+| `/media` | Authenticated, privacy-conscious media gallery and sync controls. |
+| `/performance` | Mature outcome trends, strategy/subreddit results, and model usage. |
+| `/operations` | Background jobs, sync state, events, rate limits, and technical logs. |
+| `/settings` | Validated runtime configuration and account/session management. |
+
+Navigation is declared in `app/navigation.ts`; route elements are composed in `app/router.tsx`.
+
+## State model
+
+- Remote state: TanStack Query snapshots parsed by shared Zod schemas.
+- Route/filter/selection state: URL/search params when it should survive navigation or be shareable.
+- Ephemeral UI state: component/provider state, such as dialogs and notification presentation.
+- Persistent presentation state: guarded browser storage only when explicitly useful (for example notification history).
+
+Do not introduce a general global state store unless a demonstrated cross-feature need cannot fit these boundaries.
+
+## HTTP and contracts
+
+`api/request.ts` owns authenticated request mechanics and failure conversion. `api/client.ts`/`api/queries.ts` expose typed calls and query keys. Parse every response at the boundary. Strict schemas are deliberate: when the server adds a field, update the shared contract and its consumers in the same change.
+
+Mutations should display the confirmed server result. Start/stop, config, sync, import, and send actions must not use optimistic success for operational state.
+
+Account delivery state is reported per runtime (`ready`, stopped/failed/login-required, Matrix cooldown, replies prioritized, or pacing). Preserve account attribution when presenting cooldowns and failures; a blocked account does not imply every account is blocked.
+
+## Realtime model
+
+`RealtimeProvider` connects to `/api/events/stream`. Event IDs support bounded replay/resume. Each event family either updates a narrowly safe cache value or invalidates the relevant HTTP snapshot. Reconnect and stale detection live in the app layer, not individual feature pages.
+
+Rules:
+
+- HTTP remains authoritative.
+- Duplicate/replayed events must be harmless.
+- A disconnected stream marks data stale but does not blank useful cached content.
+- Invalid event payloads are contained and repaired with a snapshot refresh.
+- User-triggered outcomes may create toasts; durable/history-worthy events also appear in the notification center/activity views.
+- Raw technical logs belong in Operations, not as general user notifications.
+
+## Authentication and privacy
+
+The login form exchanges the administrator token for an HttpOnly, SameSite=Strict cookie. API clients may use Bearer tokens. Express applies auth before static dashboard assets, APIs, SSE, and `/media`; `/healthz` is the intentional public exception.
+
+Media may be private conversation content. Preserve authenticated URLs, blur/privacy defaults, explicit reveal behavior, safe new-tab links, and no token leakage into query strings or local storage.
+
+## Feature structure
+
+Each route is a slice under `features/<name>/` with page/route components, local styles, and feature-specific helpers. Cross-feature visual/domain components live under `components/`; application lifecycle belongs under `app/`; transport belongs under `api/`.
+
+Keep feature components focused:
+
+- pages compose queries and sections;
+- presentational components render typed props;
+- mutation hooks own cache invalidation;
+- parsing/formatting lives in small pure helpers;
+- destructive or external-message actions require explicit confirmation and accessible focus restoration.
+
+## Accessibility and presentation
+
+- All actions must be keyboard accessible and have visible focus.
+- Dialogs label purpose, trap/restore focus, and distinguish cancel from destructive confirmation.
+- Status must not rely on color alone.
+- Relative times include an exact timestamp where operationally useful.
+- Lists are explicitly sorted after filters rather than relying on backend/incidental order.
+- Loading, empty, stale, partial, and error states are distinct.
+- Show sample sizes and low-confidence context for performance metrics.
+
+## Testing
+
+Dashboard behavior is tested with Vitest, jsdom, Testing Library, and controlled HTTP boundaries. Focus on observable behavior:
+
+- representative payloads parse and malformed payloads fail;
+- route/search state and navigation;
+- loading/error/empty/stale views;
+- mutation confirmation and server read-back;
+- SSE ordering, replay, reconnect, duplicate handling, and snapshot repair;
+- authentication/private media boundaries;
+- keyboard/focus behavior for dialogs and controls.
+
+Run focused `npx vitest run tests/dashboard/<file>`, then `npm run dashboard:typecheck`, `npm run dashboard:build`, and the full suite before publishing a frontend change.
+
+## Adding a dashboard capability
+
+1. Define/extend the shared Zod contract.
+2. Make the server route return that contract and add a route test.
+3. Add a typed client/query key.
+4. Build the feature slice and observable UI states.
+5. Map relevant realtime events to cache updates/invalidations.
+6. Add component/realtime/contract coverage.
+7. Update `api.md` when the operation catalog changed and update this or the relevant product/flow document.