Projects/docs/FrontendImplementationPlan.md

# 🧩 Complete Frontend Implementation Plan – Research Platform

Based on the full backend API and the current state of your frontend, here is the **definitive plan** to make the frontend **fully complete**, scalable, and production-ready. This plan assumes your backend now implements all endpoints (including the missing collections, references, preprints, provenance, unified inbox, recent items, etc.). The frontend already has the hooks and many components – now we need to **finalize them, fill gaps, and add architectural best practices**.

---

## 1. Current Frontend Status (Recap)

- **✅ Core features** – Authentication, articles, messaging (private & group), notifications, RAG assistant, lab inventory, peer review, gap analysis, projects, data hub, events, workspace, voice assistant, admin dashboard, analytics, polls, 2FA, export (HTML).
- **🟡 Partially missing UI** – Paper collections, reference manager, preprint submission, provenance timeline, unified inbox filters, scheduled messages UI, global search results, user liked articles endpoint fix, admin tables.
- **🔴 Not yet connected** – Some hooks (`usePaperCollections`, `useReferenceManager`, `usePreprintSubmission`, `useProvenance`, `useUnifiedInbox`) are written but **not used** in any page. No UI pages exist for these features.
- **❌ Missing architectural pieces** – Centralized error handling, request cancellation, offline support (partial), proper loading states, skeleton screens, internationalization (i18n), accessibility (a11y), performance optimizations (code splitting, lazy loading), testing.

---

## 2. Final Frontend Feature Completion Checklist

Below is the exact list of components and pages you must create or finalize. Each item includes the required file and a brief description.

### 2.1 Paper Collections (UI)

| File | Purpose |
|------|---------|
| `src/pages/CollectionsPage.tsx` | Lists all user collections, create/delete. |
| `src/pages/CollectionDetailPage.tsx` | Shows papers inside a collection, remove paper. |
| `src/components/collections/AddToCollectionModal.tsx` | Popup to add current article to a collection. |
| `src/components/collections/CreateCollectionModal.tsx` | Form to create a new collection. |

**Integration**: Add “Save to collection” button on `ArticleDetailPage` and `ArticlesPage` (article card). Add route `/collections` in `MainLayout` sidebar.

### 2.2 Reference Manager

| File | Purpose |
|------|---------|
| `src/pages/ReferenceManagerPage.tsx` | Manage references for a given document (docId from URL or context). |
| `src/components/references/ImportReferenceModal.tsx` | DOI / BibTeX / Zotero / Mendeley import. |
| `src/components/references/ReferencePicker.tsx` | Popup inside `ScientificEditor` to insert citation (`\cite{key}`). |

**Integration**: Add button in `ScientificEditor` toolbar (citation icon) that opens `ReferencePicker`. Add route `/references/:docId`.

### 2.3 Preprint Submission

| File | Purpose |
|------|---------|
| `src/pages/PreprintSubmissionPage.tsx` (complete stub) | Full form (title, abstract, authors, manuscript, cover letter). |
| `src/components/preprint/ScreeningResult.tsx` | Show AI screening feedback (accept/warnings/reject). |

**Integration**: Add link in `MainLayout` or user dropdown. Already has route (check `App.tsx`).

### 2.4 Provenance / Trust

| File | Purpose |
|------|---------|
| `src/components/provenance/ProvenanceTimeline.tsx` (exists, integrate) | Show audit trail on article/research object page. |
| `src/components/provenance/VerifyChainButton.tsx` | Call `verifyChain()` and display result. |

**Integration**: Add a “View provenance” button in `ArticleDetailPage` and `ResearchObjectDetailPage` (if exists). Use `useProvenance(entityId, "article")`.

### 2.5 Unified Inbox (Complete Existing Page)

| File | Missing Piece |
|------|---------------|
| `src/pages/UnifiedInboxPage.tsx` | Re-add `InboxFilterBar.tsx` (filter by origin, priority, date). |

**Integration**: Already in routes. Ensure `useUnifiedInbox` maps data correctly from backend.

### 2.6 Scheduled Messages UI

| File | Missing Piece |
|------|---------------|
| `src/components/messages/ScheduleModal.tsx` (exists) | Add button in `ChatArea` (near send) to open modal. |
| `src/components/messages/ScheduledMessagesPanel.tsx` (exists) | Add clock icon in `MessagesPage` header to open panel. |

### 2.7 Recent Items (Command Palette)

| File | Missing Piece |
|------|---------------|
| `src/App.tsx` | Uncomment / implement fetch to `/api/recent-items`. |

### 2.8 Global Search Modal

| File | Missing Piece |
|------|---------------|
| `src/components/messages/GlobalSearchModal.tsx` | Actually call search endpoints (`/api/conversations/search`, group search) and display results. Currently only shows chat list. |

### 2.9 User Liked Articles

| File | Missing Piece |
|------|---------------|
| `src/pages/LikedArticlesPage.tsx` | Change endpoint to `/api/users/${currentUsername}/liked-articles` or ask backend to add alias. |

### 2.10 Admin Tables

| File | Purpose |
|------|---------|
| `src/components/admin/UserTable.tsx` | List users (GET `/api/admin/users`), delete, promote admin. |
| `src/components/admin/ArticleTable.tsx` | List all articles, delete. |
| `src/components/admin/RagDocTable.tsx` | List RAG documents, delete. |

**Integration**: Add tabs in `AdminPage` (already has stats, add these tables).

---

## 3. Architectural Improvements for Production

Once the above UI is in place, you must also adopt the following **frontend best practices** to ensure scalability, maintainability, and user experience.

### 3.1 State Management

Currently you use React `useState` + `useEffect` + custom hooks (which is fine). For complex features (e.g., unified inbox, command palette), consider using **React Context** or **Zustand** to avoid prop drilling.  
- **Recommendation**: Keep as is for now; no global store needed until you see performance issues.

### 3.2 API Client & Error Handling

Create a unified API client (wrapper around `axios`) that:

- Automatically attaches JWT token.
- Handles 401 → refresh token or redirect to login.
- Displays toast errors for non-200 responses.
- Supports request cancellation (you already have abort controllers in many hooks – ensure consistency).

**File**: `src/lib/apiClient.ts`

### 3.3 Lazy Loading & Code Splitting

All page components are currently imported statically in `App.tsx`. Convert them to **React.lazy** + `Suspense` to reduce initial bundle size.

Example:
```tsx
const CollectionsPage = lazy(() => import("@/pages/CollectionsPage"));
```

Already present for some pages; extend to all.

### 3.4 Loading Skeletons

Replace simple `<div>Loading...</div>` with skeleton components (e.g., `ChatSkeleton`, `ArticleCardSkeleton`) for better UX. Use a library like `react-loading-skeleton` or custom Tailwind-based shimmers.

### 3.5 Error Boundaries

Wrap the app in an error boundary to catch rendering errors and show a fallback UI.

### 3.6 Offline Support (PWA)

- Add service worker using `vite-plugin-pwa`.
- Integrate `OfflineCollaborationQueue` into `ChatArea` to queue messages when offline and retry when online.
- Cache API responses (e.g., article list, user profile) using Workbox.

### 3.7 Internationalization (i18n)

Prepare for multi-language support:
- Use `react-i18next`.
- Store translations in JSON files.
- Detect locale from browser or user preference (store in backend).

### 3.8 Accessibility (a11y)

- Ensure all interactive elements have `aria-label` where needed.
- Use semantic HTML (`<button>`, `<nav>`, `<main>`).
- Test with keyboard navigation and screen readers (VoiceOver, NVDA).

### 3.9 Performance Monitoring

- Integrate **Sentry** for error tracking.
- Use **React DevTools** and **Lighthouse** to measure performance.

### 3.10 Testing

Write tests for critical flows:
- **Unit tests** for hooks (`useAuth`, `useMessaging`) – use React Hooks Testing Library.
- **Integration tests** for pages (Login, Messages) – use React Testing Library.
- **E2E tests** for key user journeys (login → send message → like article) – use Playwright.

---

## 4. Deployment & CI/CD

- **Build**: `npm run build` (Vite outputs static files to `dist/`).
- **Serve**: Deploy to **Netlify**, **Vercel**, or **AWS S3 + CloudFront**.
- **Environment variables**: Use `.env.production` for API base URL, WebSocket URL, etc.
- **CI/CD**: GitHub Actions – run tests, lint, build, and deploy to staging on every push; production on tag.

Example GitHub Actions workflow:
```yaml
name: Deploy Frontend
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm ci
      - run: npm run build
      - uses: actions/upload-artifact@v4
        with: { name: dist, path: dist }
  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v4
        with: { name: dist, path: dist }
      - run: ... (upload to S3 or Netlify)
```

---

## 5. Final Checklist – Frontend Completion

Use this checklist to track progress. Mark items as done when you have implemented them.

### Phase 1 – Missing UI (Must have)

- [ ] `CollectionsPage.tsx` + `CollectionDetailPage.tsx`
- [ ] `AddToCollectionModal.tsx` (integrate with article pages)
- [ ] `ReferenceManagerPage.tsx` + `ImportReferenceModal.tsx` + `ReferencePicker.tsx`
- [ ] Complete `PreprintSubmissionPage.tsx` (full form)
- [ ] `ScreeningResult.tsx` component
- [ ] Integrate `ProvenanceTimeline` into `ArticleDetailPage`
- [ ] Re‑add `InboxFilterBar.tsx` to `UnifiedInboxPage`
- [ ] Add `ScheduleModal` button in `ChatArea`
- [ ] Add `ScheduledMessagesPanel` button in `MessagesPage`
- [ ] Fix `LikedArticlesPage` endpoint
- [ ] Implement `GlobalSearchModal` with actual search calls
- [ ] Add admin tables (`UserTable`, `ArticleTable`, `RagDocTable`) to `AdminPage`

### Phase 2 – Architectural Improvements (Should have)

- [ ] Unify API client with error handling and token refresh
- [ ] Lazy load all page components
- [ ] Add skeleton loading states for all major pages
- [ ] Add error boundary component
- [ ] Implement offline queue integration (optional but recommended)
- [ ] Configure PWA (service worker)
- [ ] Set up i18n infrastructure (even if not translating yet)
- [ ] Run accessibility audit and fix issues

### Phase 3 – Testing & CI/CD (Nice to have)

- [ ] Write unit tests for core hooks
- [ ] Write integration tests for critical pages
- [ ] Set up Playwright for E2E tests
- [ ] Create GitHub Actions workflow for build and deploy
- [ ] Set up environment variables for production

---

## 6. Summary

Your frontend is already **80% complete**. The missing parts are mostly **UI pages that call existing hooks**. By creating the 10+ files listed above, you will achieve **feature parity** with the backend. Then, by adding the architectural best practices (lazy loading, error handling, PWA, testing), you will transform the frontend into a **production-grade, scalable research platform**.

All the necessary **hooks** (`usePaperCollections`, `useReferenceManager`, etc.) and **API endpoints** are ready – you only need to **build the UI components**. The rest of the code (routing, layout, existing pages) already works.

**Estimated effort for Phase 1 (missing UI):** 3–5 days for an experienced developer.  
**Phase 2 (architectural):** 2–3 days.  
**Phase 3 (testing/CI):** 2 days.