RedditBot/docs/frontend-migration.md

React Dashboard Migration

Outcome

The inline dashboard has been replaced by a typed, accessible React application. Express remains the authenticated API, SSE, private-media, and production static-asset host.

Current status

The current routes are Overview, Conversations (including route-addressable detail), Media, Performance, Operations, and validated Settings and Access. Shared HTTP and realtime schemas live in packages/api-contracts, and /api/events/stream supplies the typed SSE transport.

npm run build compiles the server and writes the Vite application to apps/dashboard/dist. src/web/dashboard-assets.ts requires that build and fails startup with an actionable error if it is absent. The legacy HTML has been removed. Root pages, assets, APIs, SSE, and private media share the same timing-safe dashboard authentication boundary.

Architecture

• apps/dashboard: React, TypeScript, Vite, React Router, and TanStack Query.
• packages/api-contracts: shared Zod schemas for HTTP and realtime transport.
• src/web: existing Express host, gradually adapted to the shared contracts.
• Backend service and database types stay private to the backend. Transport contracts must not expose database rows as an accidental public API.
• Server state lives in TanStack Query. Route, filter, and selection state lives in URLs. Local component state is reserved for ephemeral presentation state.
• Do not add a global client-state library until a demonstrated cross-feature state requirement cannot be met by those boundaries.

Navigation

The application shell provides a responsive sidebar or drawer with these routes:

Route	Responsibility
/	Health, metrics, timers, limits, and important recent activity
/conversations	Searchable conversation inbox
/conversations/:id	Conversation history, context, suggestions, and sending
/media	Private blurred-by-default gallery and sync controls
/performance	Trends, strategies, subreddits, and successful examples
/operations	Domain activity, background jobs, and diagnostics
/settings	Validated runtime configuration and Reddit access state

Overview surfaces bot state, dry-run state, cooldowns, timers, and the guarded start/stop control. Operations owns connection health, sync state, activity, and the bounded technical console.

Realtime model

HTTP snapshots are authoritative. A typed SSE event stream updates or invalidates the relevant query cache. Every event has an ID, type, occurrence timestamp, and validated payload. The stream supports bounded replay and Last-Event-ID resume. Relevant events invalidate TanStack Query keys so the next HTTP read remains authoritative. Connection loss marks cached state stale while EventSource reconnects.

Required event families are bot status, message sent or failed, conversation updated, reply received, sync lifecycle and progress, rate-limit state, Reddit session state, and technical logs.

Important domain events appear in a readable activity timeline. Raw logs remain in Operations. Toasts are reserved for user-triggered outcomes requiring timely feedback. Realtime disconnection never blanks cached content; it marks it stale and falls back to visibility-aware polling where necessary.

Feature slices

1. Capture and validate existing HTTP contracts and critical legacy journeys.
2. Add the frontend build, application shell, authentication handling, routing, error boundaries, design tokens, query client, and test harness.
3. Deliver Overview as the first production vertical slice.
4. Add the typed realtime event core, SSE transport, reconnection, and query invalidation.
5. Migrate Conversations, including explicit suggestion and send mutations.
6. Migrate Media, preserving authentication and blur-by-default privacy.
7. Migrate Performance with sample sizes and low-confidence warnings.
8. Migrate Operations, access/login, and route-backed validated Settings.
9. Run feature parity and security audits, switch Express to the Vite output, remove the legacy HTML, and update operator and deployment documentation.

All slices now run from the React application; the migration phases above are retained as implementation history.

Engineering gates

• New behavior follows red-green-refactor with Vitest.
• Component tests use Testing Library and test observable behavior.
• HTTP tests use a controlled boundary such as MSW rather than mocking fetch throughout feature tests.
• Contract tests prove representative current responses parse and malformed payloads fail.
• Realtime tests cover ordering, replay, duplicate handling, reconnection, and cache repair.
• Browser tests cover authentication, start/stop, conversation inspection, sending confirmation, sync, settings persistence, and private media.
• Interactive controls are keyboard accessible and restore focus after dialogs.
• No production frontend or backend code uses any or console.log.
• Mutations display the confirmed server outcome and do not rely on optimistic success for operational controls.
• Production builds are deterministic. The server serves only generated React assets plus authenticated private content.

Cutover evidence

Cutover verification covers API and SSE authentication, private media access, SSE recovery, responsive navigation, frontend type-check/build, backend build, the complete Vitest suite, and browser smoke journeys.