# 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).