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:

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:

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.