REDESIGN_PLAN.md

REDESIGN_PLAN.md

1. Current Structure

• Frontend: React 19, Vite, React Router DOM, Tailwind CSS (v4), Motion, React Query, React Hook Form, Zod.
• Backend: Express server (server.ts) acting as a BFF proxy, serving API routes and Vite middleware in dev / static in production.
• Routing: Client-side routing via React Router DOM.
• Data Fetching: @tanstack/react-query & axios.

2. Rebuild Plan per Screen

• AI Dashboard (/): Main AI chat interface. Implement SSE streaming for chat with typed events (message, ui_block). Render rich UI blocks (company_list, contact_list). Research progress overlay.
• Campaigns (/campaigns): List with status badges, cursor pagination, activate/pause actions, create modal.
• Campaign Detail (/campaigns/:id): Analytics charts, schedule editor, sending-status diagnostics.
• Unibox (/unibox, was /inbox): Two-pane thread list + thread view. Mobile-responsive stacking.
• Account Health (/accounts, was /email-accounts): Sending accounts status, warmup toggles, vitals tests.
• CRM / Contacts (/contacts, was /leads): Tabs (all / from_research / csv). Deep-link param parsing (?tab=from_research&job=<id>).
• Reporting (/reporting, was /analytics): Workspace-wide KPIs, date filtering, CSV export.
• Settings (/settings): Instantly connection panel (admin-only), webhook settings.
• Auth (/login): Login layout for short-lived JWT/sessions.
• Notifications (/notifications): Webhook-driven activity feed.
• Admin (/admin): Users & roles management, audit log table.

3. Component Guidelines

• Strict max ~20KB file size per component.
• Design Tokens: Defined in index.css via Tailwind variables (dark-first, off-black, desaturated accent).
• Typography: Unique font (will use Geist or similar, falling back to standard if unavailable, tabular-nums for metrics).
• Motion: motion/react for AnimatePresence, staggered lists.

4. Migration Order

1. Design Tokens & Shell: Update index.css, index.html (app name, fonts), AppLayout.tsx.
2. Backend Proxy & Webhook Receiver: Enhance server.ts with rate-limiting, backoff logic, and correct proxy endpoints for Instantly API v2.
3. Core API Client: Build lib/instantly/client.ts with retries and jitter.
4. Screens Implementation:
   • Dashboard (SSE & UI blocks)
   • Contacts (Fixing URL param & research filter bugs)
   • Campaigns & CampaignDetail
   • Unibox
   • Accounts
   • Reporting
   • Settings
   • Auth, Admin, Notifications
5. Testing & QA: Responsive design, WCAG contrast, mock mode.
6. Dockerizing & Polish: Update Dockerfile, README.md.

5. Audit Bugs to Fix

1. Wrong-column research filter: Filter on research_job_id = 'lead-list:<jobId>'.
2. Missing polling interval: Use refetchInterval: 5000 in React Query for active research jobs.
3. Missing URL param support: Use useSearchParams to parse ?tab=from_research&job=<id> and set initial state.
4. Missing SSE ui_block handler: Parse ui_block in SSE stream and render specific React components instead of text.
5. Missing "View results" link: Ensure overlay deep-links to /contacts?tab=from_research&job=<id>.
6. Cache not invalidated: Call queryClient.invalidateQueries when research completes.
7. Monster components: Keep files modular (<20KB). Split large widgets.
8. No error handling for polling: Add retry logic, timeout, and exponential backoff.
9. Two repository variants: Unified here.
10. Hardcoded magic strings: Extract to src/constants/index.ts.
11. Missing error boundary: Create and wrap overlays in <ErrorBoundary />.
12. Inconsistent query cache TTL: Centralize in src/config/query.ts.
13. Console logs disabled: Use proper error tracking (mocked Sentry) and leave console.error/warn.
14. Unused backup files: N/A in current clean state.
15. Missing TypeScript strict flags: Verified tsconfig.json has strict mode (will ensure strictNullChecks).