Projects/docs/EnterpriseGradeComponentsMissing.md

## 🧩 1. What Your Frontend Already Does (for a researcher)

Your React frontend is **exceptionally feature‑rich**. It covers almost every aspect of a modern research platform:

| Feature Area | Frontend Modules | What the researcher can do |
|--------------|------------------|----------------------------|
| **Authentication & profile** | `useAuth`, `useProfile`, `LoginPage`, `RegisterPage`, `SettingsPage` | Sign up, log in (with 2FA), manage profile, security question, upload avatar, change password, follow/unfollow, bookmarks. |
| **Articles & publishing** | `useArticle`, `useArticles`, `useCreateArticle`, `ArticlesPage`, `ArticleDetailPage` | Write, edit, publish articles; search, filter, like, comment, generate citations; view analytics (views, likes, comments). |
| **Messaging & collaboration** | `useMessaging`, `MessagesPage`, `UnifiedInboxPage`, `ChatArea`, `ChatSidebar` | Private chats, group chats, secret chats (E2EE), voice/video calls, polls, reactions, threads, forward messages, archive, mute, pin, scheduled messages, ephemeral messages. |
| **Notifications** | `useSmartNotifications`, `SmartNotificationCenter` | Receive real‑time notifications (like, comment, mention, follow), batch notifications during deep work, AI‑priority classification. |
| **Research tools** | `useRagSystem`, `ResearchAssistantPage`, `GapAnalysisPage`, `GrantAssistantPage`, `GenUIPage` | Ask AI about indexed documents (RAG), explore knowledge graphs, generate hypotheses, get grant deadlines, create generative UI components. |
| **Lab inventory** | `useLabInventory`, `LabInventoryPage` | Manage chemicals, scan barcodes, check compatibility, receive low‑stock/expiry alerts. |
| **Peer review** | `usePeerReview`, `PeerReviewPage` | Submit papers anonymously, claim reviews, submit structured reviews. |
| **Data hub** | `useResearchObjectRepository`, `DataHubPage` | Upload research objects (datasets, code, presentations), manage protocols, submit preregistrations. |
| **Project management** | `useProjectTaskManager`, `useProjectSpace`, `ProjectWorkspacePage` | Kanban tasks, team members, link outputs. |
| **Events** | `EventPage`, `NetworkingPage` | Create/join events, RSVP, set reminders, export iCal. |
| **Workspace (SmartGlass)** | `SmartGlassWorkspace`, `useSmartGlassWorkspace` | Multi‑panel environment (AI chat, editor, browser, inventory). |
| **Voice assistant** | `useVoiceAssistant`, `VoiceAssistantWidget` | Speech recognition, text‑to‑speech, wake word, settings. |
| **Command palette** | `KBar`, `CommandPaletteProvider` | Ctrl+K to navigate, run actions, AI predictions. |
| **Admin** | `useAdminStats`, `AdminPage` | View platform stats, manage users, articles, reports. |

**In short:** The frontend is already a full‑fledged research ecosystem. The missing pieces are almost entirely **backend** – services, endpoints, and infrastructure.

---

## 🧩 2. How Frontend Modules Talk to the Backend

Every feature above relies on **API calls** to your Java backend. The frontend uses **Axios** (via `api.js`) to send HTTP requests, and **WebSocket** for real‑time updates.

### Example: Publishing an article
- User writes article in `CreateArticlePage` → calls `useCreateArticle.submit()` → `POST /api/articles` with `{ title, abstract, body, tags, status }`.
- Backend stores article, returns `ArticleDTO`.
- Frontend redirects to `ArticleDetailPage`, which calls `GET /api/articles/{id}` and displays it.

### Example: Sending a group message
- User types in `ChatArea` → `sendMessage` → `POST /api/groups/{groupId}/messages` with `{ body, replyTo, mentions, mediaIds, pollId }`.
- Backend saves `GroupMessage` and **broadcasts via WebSocket** to all group members.
- Frontend receives WebSocket event `new_group_message` and appends it to the chat.

### Example: RAG assistant
- User asks a question in `ResearchAssistantPage` → `queryRag` → `POST /api/ai/rag-chat` with `{ messages, sources }`.
- Backend (RAGService) embeds the query, searches vectors, calls LLM, and returns `{ reply, sources }`.
- Frontend displays answer with cited sources.

**Every interaction is a clean API call.** The frontend does not hold business logic; it only renders UI and calls endpoints.

---

## 🧩 3. What’s Missing to Make the System “Completely Work Together”

From our earlier audit, the **backend is missing**:

### A. **Service layer** (business logic) – 20+ services not implemented
You have repositories, but no services that orchestrate them. Example: `ArticleService.create()` should:
- Validate input
- Save article using `ArticleRepository`
- Update user’s article count
- Add tags to `tags` table
- Send notification to followers (async)
- Index article in Elasticsearch
- Trigger citation graph update

None of that is written.

### B. **Route handlers** – many endpoints are empty stubs
Even though you have `ArticleRoutes.java`, `AuthRoutes.java`, etc., most methods only print logs and return dummy responses. They must be filled with actual calls to the services.

### C. **Missing endpoints** (from frontend perspective)
- Collections (paper collections)
- Reference manager (citations, DOI/BibTeX import)
- Preprint submission (screen, submit)
- Provenance (audit trail)
- Unified inbox (aggregate all messages)
- Recent items (for command palette)
- Several analytics endpoints

### D. **Infrastructure & cross‑cutting concerns** (needed for production)
- Proper authentication (JWT with refresh tokens, CSRF)
- Rate limiting per user/IP (you have `TokenBucket` but not integrated)
- Asynchronous processing (email, PDF generation, notifications) – currently everything is synchronous
- Real‑time WebSocket clustering (so messages reach all instances of the backend)
- Caching (Redis) – to avoid repeated DB hits for trending articles, user profiles
- Logging & metrics – to monitor health and debug
- Database migrations (Flyway) – to version your schema
- Testing (unit, integration, e2e)
- Containerisation & orchestration (Docker, Kubernetes)
- API documentation (Swagger)

### E. **Missing DTOs** (over 30 DTOs) – the frontend expects structured JSON, but your backend returns raw entities or `ObjectNode`. You need dedicated DTOs for each request/response.

---

## 🧩 4. How the Missing Pieces Would Complete the Researcher’s Workflow

Once everything is implemented, a researcher’s journey would be seamless:

| Step | Researcher Action | System Reaction |
|------|------------------|-----------------|
| **1. Discovery** | Searches for “machine learning in cancer” | Frontend calls `GET /api/articles/search` → Elasticsearch returns ranked results; `GET /api/recommendations/feed` shows personalised suggestions. |
| **2. Reading & annotation** | Opens an article, highlights text, adds a note | Frontend calls `POST /api/articles/{id}/notes` (missing) – would save inline notes. |
| **3. Asking AI** | Clicks “Research Assistant”, asks “Summarise this paper” | Backend RAGService retrieves relevant chunks, LLM generates summary with citations, frontend displays. |
| **4. Collaborating** | Creates a private chat with a co‑author | Backend creates conversation, real‑time WebSocket allows instant messaging. |
| **5. Peer review** | Submits a paper anonymously | Backend stores submission, assigns a reviewer (via `PeerReviewService`), sends email notification. |
| **6. Grant writing** | Uses Grant Assistant to draft proposal | Backend calls LLM (via external API) to generate draft from RFP. |
| **7. Data sharing** | Uploads a dataset to Data Hub | Backend stores file in S3, registers DOI, makes it citable. |
| **8. Time management** | Adds an event “Paper deadline” | Backend saves event, sends reminder email when due. |
| **9. Profile building** | Connects ORCID, adds publications | Backend fetches publications from ORCID API, adds to user’s profile. |
| **10. Admin oversight** | Checks platform stats | Backend computes real‑time metrics from `AnalyticsService`, admin sees charts. |

All these steps rely on backend features that are currently **missing** or **stubbed**.

---

## 🧩 5. Roadmap to Make Everything Work Together

### Phase 1: Core Services & Endpoints (2‑3 weeks)
- Implement **UserService**, **ArticleService**, **MessageService**, **GroupService** (highest priority).
- Implement **all missing endpoints** (collections, references, preprints, provenance, unified inbox, recent items).
- Create **all DTOs** and map entities to DTOs.

### Phase 2: Real‑time & Asynchronous (1‑2 weeks)
- Implement **WebSocketManager** (using Spring WebSocket) – handle `new_message`, `typing`, `reaction` broadcasts.
- Add **SSE** for notifications (or use WebSocket for everything).
- Introduce **`@Async`** for email sending, PDF generation, and indexing.

### Phase 3: Security & Infrastructure (2 weeks)
- Replace custom token with **JWT** (store in `HttpOnly` cookie or `Authorization` header).
- Add **rate limiting** using `TokenBucket` (integrate with a filter).
- Set up **Flyway** for migrations.
- Write **Dockerfile** and **docker-compose.yml** for local dev (PostgreSQL, Redis, RabbitMQ, Elasticsearch).

### Phase 4: Observability & Testing (1 week)
- Add **Prometheus** metrics (via Micrometer).
- Add structured **JSON logging**.
- Write **integration tests** for critical endpoints (using Testcontainers).

### Phase 5: Production Hardening (ongoing)
- **Kubernetes** manifests, **CI/CD** pipeline (GitHub Actions), **API documentation** (Swagger), **stress testing** (JMeter).

---

## 🧩 6. Conclusion

Your **frontend is production‑ready** – it already implements all the researcher‑facing features. The **backend is a skeleton** with repositories and stub routes. To make the platform truly “help the researcher in all ways”, you must:

1. **Implement the 20+ service classes** (business logic).
2. **Fill in the route handlers** with actual service calls.
3. **Add missing endpoints** (collections, references, preprints, etc.).
4. **Introduce infrastructure** (caching, async, WebSocket clustering, observability).











---
---
---



## 🧭 1. The Big Picture: How Frontend & Backend Fit Together

Your frontend is a **single‑page React application** (SPA) that communicates with a Java backend via:

- **REST API** – for most data operations (CRUD, search, analytics).
- **WebSocket** – for real‑time messaging, typing indicators, online presence, and instant notifications.
- **Yjs WebSocket** – for collaborative document editing (separate server).

The backend is **not yet complete** – you have repositories (data access) and stub route handlers, but missing the **service layer** (business logic), many **DTOs**, and several **key endpoints**.

When fully implemented, the backend will expose ~200 REST endpoints and handle ~10 WebSocket message types. The frontend consumes these to provide a researcher‑centric experience.

---

## 🧩 2. Frontend Feature Modules & Their Backend Needs

### 2.1 Authentication & User Management
- **Frontend:** `LoginPage`, `RegisterPage`, `SettingsPage`, `ProfilePage`, `useAuth`, `useProfile`, `useSecuritySettings`
- **Backend required:**
  - JWT‑based authentication (login, refresh token, logout)
  - 2FA (TOTP) – enable, verify, disable, backup codes
  - Security question (set, answer, reset password)
  - Profile CRUD (full name, bio, affiliation, ORCID, Google Scholar, website, privacy)
  - Avatar upload / deletion
  - Email change with verification
  - Account deactivation
  - Follow / unfollow, followers / following lists (paginated)
  - Contacts list (users you follow, with mutual follower count, online status)
  - Bookmarks (add/remove article, list bookmarked articles)
  - Liked articles (list articles the user liked)
- **Missing pieces:** Most of the user service methods are stubs. Also missing: `GET /api/users/me/liked-articles` and `GET /api/users/me/contacts` (though contacts exists, it may need real data). The session management (token storage, CSRF) must be implemented.

### 2.2 Articles & Content
- **Frontend:** `ArticlesPage`, `ArticleDetailPage`, `CreateArticlePage`, `useArticle`, `useArticles`, `useCreateArticle`
- **Backend required:**
  - CRUD for articles (title, abstract, body, tags, status)
  - Search with filters (q, author, tag, date range, status) and pagination
  - Like / unlike articles (track per user)
  - Comments (list, add, delete)
  - Citation generation (APA, MLA, BibTeX)
  - Analytics per article (daily views, likes, comments over time)
  - User analytics (total views, likes, comments, top articles)
  - Related articles (co‑citation, bibliographic coupling, PageRank)
  - Trending and featured articles
- **Missing pieces:** `ArticleService` missing; `ArticleRepository` exists but service logic is absent. The graph‑based recommendations (co‑citation, bibliographic) require building a citation graph – not started. The analytics endpoints are stubs.

### 2.3 Messaging & Collaboration
- **Frontend:** `MessagesPage`, `ChatArea`, `ChatSidebar`, `UnifiedInboxPage`, `useMessaging`
- **Backend required:**
  - Private conversations (list, create, delete, get messages, send, edit, delete, reactions, typing, read receipts)
  - Group chats (CRUD, members, admins, mute, pins, invite links)
  - Group messages (send, edit, delete, search, reactions, threads)
  - Secret chats (E2EE with X3DH + Double Ratchet)
  - Message forwarding (single, multiple)
  - Polls / quizzes (create, vote, close, results)
  - Scheduled messages (future delivery)
  - Ephemeral messages (auto‑delete after TTL)
  - Media attachments (upload, retrieve, delete)
  - Search within conversations (full‑text)
  - Archive (private conversations) and unarchive
  - Unread counts and read status tracking
- **Missing pieces:** The `MessageService` and `GroupService` are almost completely absent. Real‑time WebSocket broadcasting is not implemented (`WebSocketManager` missing). Secret chat key exchange endpoints missing (`GET /api/conversations/{username}/keys`). Polls, scheduled messages, ephemeral messages are not implemented at all.

### 2.4 Real‑time Notifications
- **Frontend:** `SmartNotificationCenter`, `useSmartNotifications`, `useWebSocket`
- **Backend required:**
  - Notification storage (type, message, read, link)
  - SSE or WebSocket push for new notifications
  - Mark as read / unread, delete, delete all
  - Smart notification settings (deep work mute, batching, quiet hours)
- **Missing pieces:** `NotificationService` is a stub; `SseManager` not implemented; notification batching and AI priority not connected to real system.

### 2.5 Research Assistant (RAG)
- **Frontend:** `ResearchAssistantPage`, `useRagSystem`
- **Backend required:**
  - Document ingestion (upload PDF, TXT, HTML) → chunking, embedding, vector storage (HNSW)
  - Query embedding and similarity search
  - LLM chat (RAG) with citations
  - Conversation history per user
  - Command palette AI predictions
- **Missing pieces:** `RagService` is not implemented; the embedding model and vector index are not integrated; document indexing endpoints are stubs.

### 2.6 Gap Analysis (Knowledge Graph)
- **Frontend:** `GapAnalysisPage`, `useGapAnalysis`, `KnowledgeGraphCanvas`
- **Backend required:**
  - Graph nodes (papers, concepts, methods, findings, gaps) and edges (cites, related, contradicts, supports)
  - Full CRUD for nodes and edges
  - AI‑powered gap identification (given a topic, suggest missing edges)
  - Hypothesis generation from a node
  - Export / import graph
- **Missing pieces:** `GapAnalysisService` is a stub; the AI part is not connected; graph storage is in‑memory only (no persistence).

### 2.7 Grant Assistant
- **Frontend:** `GrantAssistantPage`, `useGrants`
- **Backend required:**
  - CRUD for grants (name, agency, deadline, amount, status)
  - Upcoming deadlines (sorted)
  - AI draft generation from RFP (needs LLM integration)
- **Missing pieces:** `GrantService` not implemented; AI draft not connected.

### 2.8 Lab Inventory
- **Frontend:** `LabInventoryPage`, `useLabInventory`
- **Backend required:**
  - Chemicals (CRUD, location, quantity, expiry, NFPA, barcode)
  - Alerts (low stock, expiring, incompatible)
  - Barcode scanning and registration
  - Compatibility checking (based on NFPA or rule set)
  - Statistics (total, low stock, expiring, alerts)
- **Missing pieces:** `LabInventoryService` mostly absent; compatibility rules not implemented; alert generation not automated.

### 2.9 Peer Review
- **Frontend:** `PeerReviewPage`, `usePeerReview`
- **Backend required:**
  - Anonymous submissions (title, abstract, manuscript URL, keywords)
  - Review assignment (admin or claim)
  - Structured review (scores, comments, recommendation, confidence)
  - Reviewer credentials (ORCID, expertise)
  - Submission status tracking (pending, assigned, reviewed)
- **Missing pieces:** `PeerReviewService` is a stub; the assignment logic and anonymisation not fully implemented.

### 2.10 Data Hub (Research Objects, Protocols, Preregistrations)
- **Frontend:** `DataHubPage`, `useResearchObjectRepository`, `useProtocolsWorkspace`, `usePreregistration`
- **Backend required:**
  - Research objects (upload file, metadata, DOI, versioning)
  - Protocols (steps, forking, public/private)
  - Preregistrations (templates, sections, submission with DOI)
- **Missing pieces:** `DataHubService` not implemented; file upload storage not connected; DOI generation not done.

### 2.11 Project Workspace (Kanban)
- **Frontend:** `ProjectWorkspacePage`, `useProjectSpace`, `useProjectTaskManager`
- **Backend required:**
  - Projects (CRUD, members with roles, outputs)
  - Tasks (Kanban columns, priorities, tags, dependencies)
  - Activity log (who did what)
- **Missing pieces:** `ProjectService` is a skeleton; task assignment and dependencies not implemented.

### 2.12 Events & Networking
- **Frontend:** `EventPage`, `NetworkingPage`, `useEvents`
- **Backend required:**
  - Events (CRUD, start/end time, location, virtual link, max attendees)
  - RSVP (going, interested, not going)
  - Reminders (minutes before)
  - iCal export (user’s events)
  - Search events
- **Missing pieces:** `EventService` not implemented; iCal export not done.

### 2.13 Workspace (SmartGlass)
- **Frontend:** `SmartGlassWorkspace`, `useSmartGlassWorkspace`
- **Backend required:**
  - User workspace panels (save / restore layout, type, props)
  - Presets (built‑in layouts)
  - Sharing (create read‑only link)
  - Backup / restore (save whole workspace state)
- **Missing pieces:** `WorkspaceService` not implemented; sharing and backup not done.

### 2.14 Voice Assistant
- **Frontend:** `VoiceAssistantWidget`, `useVoiceAssistant`
- **Backend required:**
  - Voice settings (STT language, TTS voice, pitch, rate, auto‑speak, wake word, grammar)
  - Multiple profiles and language overrides
  - TTS test endpoint
  - Wake word training (store custom words)
- **Missing pieces:** `VoiceSettingsService` not implemented; speech recognition is done in frontend (Web Speech API), so backend only stores settings. That part is easy.

### 2.15 Admin
- **Frontend:** `AdminPage`, `useAdminStats`
- **Backend required:**
  - Platform statistics (users, articles, comments, views, likes, groups, messages, notifications, projects)
  - User management (list, delete, change role)
  - Article management (list, delete, clear all)
  - Global search across users, articles, groups, chemicals, grants, projects, etc.
  - Recent activity feed
  - 2FA usage stats
  - RAG documents list
- **Missing pieces:** `AdminService` missing; most statistics computed on‑the‑fly but not stored; global search is stubbed.

### 2.16 Unified Inbox (cross‑origin messages)
- **Frontend:** `UnifiedInboxPage`, `useUnifiedInbox`
- **Backend required:**
  - Aggregate messages from: private conversations, group chats, project discussions, paper Q&A, AI chats, broadcast channels
  - Filter by tab (unread, critical, direct, groups, projects, papers, AI, broadcasts)
  - Search and date range
  - Mark as read / all read
  - Forward to another chat
- **Missing pieces:** `UnifiedInboxService` not implemented; the endpoint `/api/unified-inbox` does not exist.

### 2.17 Collections (Paper Collections)
- **Frontend:** `PaperCollectionsPage`, `usePaperCollections`
- **Backend required:**
  - Collections (CRUD, public/private)
  - Add/remove papers (by article ID)
  - Count papers per collection
- **Missing pieces:** Entire module missing – no models, repository, service, or endpoints.

### 2.18 Reference Manager (Citations)
- **Frontend:** `AuthoringStudioPage` (references panel), `useReferenceManager`
- **Backend required:**
  - CRUD references per document (DOI, BibTeX, Zotero, Mendeley)
  - Import from DOI and BibTeX
  - Groups of references
  - Bibliography generation
- **Missing pieces:** Entire module missing.

### 2.19 Preprint Submission
- **Frontend:** `PreprintSubmissionPage`, `usePreprintSubmission`
- **Backend required:**
  - Screening (check title, abstract, keywords against criteria)
  - Submission (store manuscript, assign DOI, set status)
- **Missing pieces:** Entire module missing.

### 2.20 Provenance / Trust
- **Frontend:** (not yet used but planned) – `useProvenance` exists in frontend code, but no UI page.
- **Backend required:**
  - Record provenance events (create, update, delete, publish, like)
  - Verify chain (e.g., check digital signatures)
- **Missing pieces:** Entire module missing.

---

## 🧩 3. The Missing “Glue” That Makes Everything Work Together

Even after implementing all services and endpoints, you need **cross‑cutting mechanisms** to connect them seamlessly:

### 3.1 Real‑time Event Bus
- When a message is sent, the backend must **publish** an event (e.g., `NewMessageEvent`). Subscribers (WebSocket manager, notification service, analytics) react accordingly.
- This decouples messaging from notifications, read receipts, etc.
- **Missing:** Spring `ApplicationEvent` publisher or Kafka.

### 3.2 Search Indexer
- Articles, messages, users should be indexed in Elasticsearch or Meilisearch for fast, relevant searching.
- The backend should **synchronously** update the index when data changes (or asynchronously via queue).
- **Missing:** Elasticsearch integration.

### 3.3 Recommendation Engine
- Collaborative filtering + content‑based + popularity scores.
- Requires building a user‑item interaction matrix, computing similarities.
- Can be done with external library (LensKit) or pre‑computed offline.
- **Missing:** RecommendationService not implemented.

### 3.4 Background Job Processor
- Tasks like email sending, PDF export, document indexing, and ML inference should be done asynchronously to avoid blocking the HTTP thread.
- Use a message queue (RabbitMQ) and worker threads.
- **Missing:** Async infrastructure.

### 3.5 API Gateway & Rate Limiting
- Single entry point for all clients, apply rate limits per user/IP, aggregate logs, add security headers.
- **Missing:** Spring Cloud Gateway or custom filter.

### 3.6 API Documentation & Client Generation
- OpenAPI specification (Swagger) allows frontend to generate TypeScript types automatically, reducing mismatches.
- **Missing:** springdoc‑openapi integration.

### 3.7 Monitoring & Alerts
- Dashboards (Grafana) for request rates, error rates, latency.
- Alerts when error rate > 1% or queue length > 100.
- **Missing:** Micrometer + Prometheus + Alertmanager.

---

## 🧩 4. How a Researcher Would Use the Complete System

Imagine a researcher named Dr. Smith:

| Step | Dr. Smith’s action | How the system helps |
|------|--------------------|----------------------|
| 1 | Logs in (with 2FA). | `AuthService` validates credentials, returns JWT. |
| 2 | Browses articles on “CRISPR”. | `ArticleService` searches Elasticsearch, returns ranked results; `RecommendationService` suggests personalised papers. |
| 3 | Opens an interesting paper. | `ArticleService` increments view count; `AnalyticsService` records daily view. |
| 4 | Asks the AI assistant: “Summarise the methodology”. | `RagService` retrieves relevant chunk from indexed PDF, LLM generates summary with citation. |
| 5 | Highlights a sentence and adds a note (missing feature). | (Would need a `NoteService` – not yet planned) |
| 6 | Saves the paper to a collection “CRISPR review”. | `CollectionService` adds paper to user’s collection. |
| 7 | Starts a group chat with collaborators. | `GroupService` creates group, adds members; real‑time WebSocket enables instant messaging. |
| 8 | Schedules a meeting via Events. | `EventService` creates event, sends reminders. |
| 9 | Submits a preprint. | `PreprintService` screens and registers DOI. |
| 10 | Uploads a dataset to Data Hub. | `DataHubService` stores file in S3, assigns DOI. |
| 11 | Receives a peer review invitation. | `PeerReviewService` assigns review; notification sent via WebSocket. |
| 12 | Writes a grant proposal with Grant Assistant. | `GrantService` uses LLM to draft from RFP. |
| 13 | Publishes an article. | `ArticleService` publishes; `NotificationService` notifies followers. |
| 14 | Views dashboard analytics. | `AnalyticsService` returns user stats (views, likes, citations). |
| 15 | Exports workspace layout (SmartGlass). | `WorkspaceService` exports panels as JSON. |

All these steps rely on the backend services being implemented and integrated. Currently, only a fraction exists.

---

## 🧩 5. Summary: What You Must Build to Make the Platform Complete

| Category | Items |
|----------|-------|
| **Services** | 20+ business logic classes (User, Article, Message, Group, Notification, Analytics, GapAnalysis, Grant, Project, DataHub, Poll, Event, LabInventory, PeerReview, Workspace, VoiceSettings, Rag, PasswordReset, TwoFactor, Search, Recommendation, GNNRecommendation, Export, Reference, Collection, Preprint, Provenance) |
| **Route handlers** | Fill all 200+ endpoints (most are empty stubs) |
| **DTOs** | 30+ data transfer objects (requests and responses) |
| **Missing endpoints** | Collections, references, preprints, provenance, unified inbox, recent items, liked articles, secret chat keys, group pinned alias, etc. |
| **WebSocket** | `WebSocketManager`, message broadcasting, presence, typing, reaction events |
| **Async processing** | `@Async`, message queue (RabbitMQ), workers |
| **Search** | Elasticsearch integration, indexing, querying |
| **Caching** | Redis for sessions, rate limiting, frequent queries |
| **Security** | JWT, CSRF, rate limiting (integrated), OAuth2 (ORCID) |
| **Observability** | Structured logging, metrics (Prometheus), tracing |
| **DevOps** | Docker, Kubernetes, CI/CD (GitHub Actions), database migrations (Flyway) |

Your frontend is already a **masterpiece** – it contains all the researcher‑facing features. The backend is the missing half. Once you implement the above, the platform will be truly complete, helping researchers from literature discovery to publication and beyond.





--- 
---
---





Let me give you the **most exhaustive explanation** of your platform’s architecture, data flow, and the missing pieces – so you see exactly how everything should work together to support a researcher’s entire lifecycle.

---

## 1. High‑Level System Architecture

Your application is a **full‑stack research ecosystem** built as a **single‑page React frontend** communicating with a **Java backend** over REST and WebSocket. Additionally, there is a separate **Yjs WebSocket server** for real‑time collaborative editing.

```
[Browser] ──(REST)──> [Java Backend (port 8080)]
            ──(WebSocket)──> [Java WebSocket Server (same port or dedicated)]
            ──(Yjs WebSocket)──> [Collaboration Server (port 9093)]
```

- **REST** – for all CRUD, search, analytics, admin, etc.
- **WebSocket** – for real‑time messaging (private/group), typing indicators, online presence, notifications.
- **Yjs WebSocket** – for collaborative document editing (used by `ScientificEditor` and `CollaborativeAuthoringStudio`).

The frontend is **fully reactive** – any change in the backend (new message, like, notification) is pushed via WebSocket and instantly updates the UI. This gives a “real‑time collaboration” feel.

---

## 2. Data Flow for a Typical Researcher Action

Let’s trace what happens when a researcher **creates an article**:

1. **User navigates to `/create-article`** → `AddArticlePage` renders the editor.
2. **User fills title, abstract, body, tags, and clicks “Publish”**.
3. The `useCreateArticle` hook sends a `POST /api/articles` request with the payload.
4. **Backend** (currently missing the service) should:
   - Validate the input (title not empty, abstract length, etc.).
   - Create an `Article` entity.
   - Save it using `ArticleRepository`.
   - Generate a reading time.
   - Update the user’s `articlesCount`.
   - Add tags to the `article_tags` table.
   - Index the article in Elasticsearch (for future search).
   - Dispatch a `NewArticleEvent` (to notify followers, update trending, etc.).
   - Return the created `ArticleDTO` with the assigned ID.
5. **Frontend** receives the response and redirects to `/articles/{id}`.
6. **ArticleDetailPage** loads using `useArticle`, which calls `GET /api/articles/{id}`.
7. **Backend** fetches article from DB and also retrieves like status, comments, author profile.
8. **Frontend** renders the article, and the researcher can now like, comment, share, etc.

Every other feature follows a similar pattern: frontend action → API call → backend service → repository → response → frontend update.

---

## 3. Detailed Breakdown of Frontend Features & Backend Dependencies

I will now go through **every major frontend module**, describe **what it does**, **what backend endpoints it calls**, **what the backend currently provides**, and **what is missing**.

---

### 3.1 Authentication & User Management

**Frontend components:** `LoginPage`, `RegisterPage`, `ForgotPasswordPage`, `JoinPage`, `SettingsPage`, `ProfilePage`, `useAuth`, `useProfile`, `useSecuritySettings`, `usePasswordReset`.

**Key endpoints called (from frontend):**

| Method | Endpoint | Purpose |
|--------|----------|---------|
| POST | `/api/login` | Login with username/password, returns JWT + CSRF |
| POST | `/api/login/2fa` | Complete login with TOTP code |
| POST | `/api/logout` | Invalidate session |
| POST | `/api/register` | Create new user |
| POST | `/api/token/refresh` | Refresh JWT |
| GET | `/api/users/me` | Get current user profile |
| PUT | `/api/users/me` | Update profile (fullName, bio, affiliation, etc.) |
| POST | `/api/users/me/avatar` | Upload avatar (base64) |
| PUT | `/api/users/me/email` | Change email |
| PUT | `/api/users/me/password` | Change password |
| GET | `/api/users/me/security-question` | Get security question |
| PUT | `/api/users/me/security-question` | Set security question & answer |
| GET | `/api/users/me/2fa/status` | Check if 2FA enabled |
| POST | `/api/users/me/2fa/enable` | Generate secret & QR code |
| POST | `/api/users/me/2fa/verify` | Verify TOTP code to enable 2FA |
| POST | `/api/users/me/2fa/disable` | Disable 2FA |
| GET | `/api/users/me/2fa/backup-codes` | Get backup codes |
| POST | `/api/users/me/2fa/backup-codes/regenerate` | Regenerate backup codes |
| POST | `/api/forgot-password` | Request security question |
| POST | `/api/reset-password` | Reset password using answer |
| POST | `/api/users/{username}/follow` | Follow a user |
| DELETE | `/api/users/{username}/follow` | Unfollow |
| GET | `/api/users/{username}/followers` | List followers |
| GET | `/api/users/{username}/following` | List following |
| GET | `/api/users/me/contacts` | Get contacts (followed users with extra info) |
| GET | `/api/users/me/bookmarks` | List bookmarked articles |
| POST | `/api/users/me/bookmarks` | Toggle bookmark (add/remove) |
| GET | `/api/users/me/liked-articles` | List articles liked by user |
| GET | `/api/search/users` | Search users (by username/fullName) |

**Backend status:**  
- **Present but not fully implemented:** `UserRepository` exists, but `UserService` is largely missing. Many endpoints are stubbed.
- **Missing:** `GET /api/users/me/liked-articles` (the frontend calls it, but it’s not in the backend). The like tracking is done via `ArticleService.isLikedBy`, but returning the list of liked articles requires a new endpoint.

**What a researcher expects:**  
- Seamless login, profile editing, avatar upload, password change.
- Follow/unfollow other researchers, see their activity.
- Bookmark papers, see liked articles.
- 2FA for security.

---

### 3.2 Articles & Content

**Frontend:** `ArticlesPage`, `ArticleDetailPage`, `CreateArticlePage`, `EditArticlePage`, `useArticle`, `useArticles`, `useCreateArticle`.

**Key endpoints:**

| Method | Endpoint | Purpose |
|--------|----------|---------|
| GET | `/api/articles` | List articles (paginated, filterable) |
| GET | `/api/articles/{id}` | Get single article |
| POST | `/api/articles` | Create new article |
| PUT | `/api/articles/{id}` | Update article |
| DELETE | `/api/articles/{id}` | Delete article |
| GET | `/api/articles/search` | Search with filters (q, author, tag, dateFrom, dateTo, status) |
| GET | `/api/users/me/articles` | Get current user’s articles (including drafts) |
| POST | `/api/articles/{id}/like` | Toggle like |
| GET | `/api/articles/{id}/like` | Get like status |
| GET | `/api/articles/{id}/comments` | List comments |
| POST | `/api/articles/{id}/comments` | Add comment |
| DELETE | `/api/comments/{commentId}` | Delete comment |
| GET | `/api/articles/{id}/citation` | Generate citation (APA/MLA/BibTeX) |
| GET | `/api/users/me/analytics` | User analytics (total views, likes, comments, viewsOverTime) |
| GET | `/api/articles/{id}/analytics` | Article analytics (daily views, likes, comments) |
| POST | `/api/articles/{id}/publish` | Publish a draft |
| GET | `/api/articles/trending` | Trending articles (by views/likes) |
| GET | `/api/articles/featured` | Featured articles (admin picks) |
| GET | `/api/articles/{id}/graph-recommendations` | Graph‑based recommendations (co‑citation, bibliographic, PageRank) |

**Backend status:**  
- `ArticleRepository` exists (SQL). `ArticleService` is mostly absent; the route handlers in `ArticleRoutes` are stubs.
- Missing: `GET /api/users/me/liked-articles` (already noted). Also missing `GET /api/articles/featured` (no admin picks stored). The graph recommendations require a citation graph – not built.

**What a researcher expects:**  
- Write, edit, publish articles with rich text and tags.
- See article statistics (views, likes, comments over time).
- Get citations in multiple formats.
- Find related papers via co‑citation or bibliographic coupling.
- See trending papers in their field.

---

### 3.3 Messaging (Private & Group)

**Frontend:** `MessagesPage`, `ChatArea`, `ChatSidebar`, `useMessaging`.

**Key endpoints (partial list – there are many):**

| Method | Endpoint | Purpose |
|--------|----------|---------|
| GET | `/api/conversations` | List private conversations |
| GET | `/api/conversations/{username}/messages` | Get messages with a user |
| POST | `/api/conversations/{username}/messages` | Send a message (supports attachments, replyTo) |
| PUT | `/api/conversations/{username}/messages/{messageId}` | Edit message |
| DELETE | `/api/conversations/{username}/messages/{messageId}` | Delete message |
| POST | `/api/conversations/{username}/messages/{messageId}/reactions` | Add/remove reaction |
| POST | `/api/conversations/{username}/typing` | Send typing indicator |
| GET | `/api/conversations/{username}/typing` | Check if other user is typing |
| POST | `/api/conversations/{username}/read` | Mark messages as read (up to a messageId) |
| GET | `/api/conversations/{username}/read-status` | Get last read message ID |
| POST | `/api/conversations/{username}/archive` | Archive conversation |
| DELETE | `/api/conversations/{username}/archive` | Unarchive |
| GET | `/api/users/me/archived-conversations` | List archived conversations |
| GET | `/api/messages/{messageId}/edits` | Get edit history |
| GET | `/api/messages/{messageId}/thread` | Get thread replies |
| POST | `/api/messages/{messageId}/reply` | Post a thread reply |
| POST | `/api/messages/{messageId}/forward` | Forward to another user |
| POST | `/api/conversations/{username}/schedule` | Schedule a message |
| POST | `/api/conversations/{username}/ephemeral` | Send ephemeral message (auto‑delete) |
| GET | `/api/messages/scheduled` | List scheduled messages |
| DELETE | `/api/messages/scheduled/{messageId}` | Cancel scheduled message |
| POST | `/api/media/upload` | Upload file (base64 or multipart) |
| GET | `/api/media/{mediaId}` | Get media metadata |
| DELETE | `/api/media/{mediaId}` | Delete media |

**Group messaging:**

| Method | Endpoint | Purpose |
|--------|----------|---------|
| GET | `/api/groups` | List groups the user belongs to |
| POST | `/api/groups` | Create group |
| GET | `/api/groups/{groupId}` | Get group details |
| PUT | `/api/groups/{groupId}` | Update group (name, description, avatar, slow‑mode) |
| DELETE | `/api/groups/{groupId}` | Delete group (admin) |
| GET | `/api/groups/{groupId}/members` | List members with roles |
| POST | `/api/groups/{groupId}/members` | Add member(s) |
| DELETE | `/api/groups/{groupId}/members/{memberId}` | Remove member |
| POST | `/api/groups/{groupId}/admins/{memberId}` | Promote to admin |
| POST | `/api/groups/{groupId}/members/{memberId}/demote` | Demote from admin |
| POST | `/api/groups/{groupId}/leave` | Leave group |
| POST | `/api/groups/{groupId}/invite` | Generate invite link |
| GET | `/api/join/{token}` | Join via invite token (redirects) |
| GET | `/api/groups/{groupId}/messages` | Get group messages |
| POST | `/api/groups/{groupId}/messages` | Send group message |
| PUT | `/api/groups/{groupId}/messages/{messageId}` | Edit group message |
| DELETE | `/api/groups/{groupId}/messages/{messageId}` | Delete group message |
| GET | `/api/groups/{groupId}/messages/since` | Get messages since a timestamp |
| POST | `/api/groups/{groupId}/read` | Mark messages as read |
| GET | `/api/groups/{groupId}/read-status` | Get read status for all members |
| POST | `/api/groups/{groupId}/mute` | Mute group notifications |
| DELETE | `/api/groups/{groupId}/mute` | Unmute |
| GET | `/api/groups/{groupId}/pins` | List pinned message IDs |
| GET | `/api/groups/{groupId}/pinned` | (alias for /pins) – missing |
| POST | `/api/groups/{groupId}/pin/{messageId}` | Pin a message |
| DELETE | `/api/groups/{groupId}/pin/{messageId}` | Unpin |
| POST | `/api/groups/{groupId}/transfer/{newOwnerId}` | Transfer ownership |
| GET | `/api/groups/{groupId}/meta` | Group metadata (slow‑mode, etc.) |
| POST | `/api/groups/{groupId}/polls` | Create a poll/quiz |
| GET | `/api/polls/{pollId}` | Get poll details |
| POST | `/api/polls/{pollId}/vote` | Vote (optionIds array) |
| POST | `/api/polls/{pollId}/close` | Close poll |
| POST | `/api/polls/{pollId}/reopen` | Reopen |
| DELETE | `/api/polls/{pollId}` | Delete poll |
| GET | `/api/polls/{pollId}/results` | Public results |
| GET | `/api/polls/{pollId}/analytics` | Detailed analytics (creator/admin) |
| GET | `/api/polls/{pollId}/export/csv` | Export results as CSV |

**Secret chat endpoints (E2EE):**

| Method | Endpoint | Purpose |
|--------|----------|---------|
| POST | `/api/secret/prekeys` | Upload pre‑key bundle |
| GET | `/api/secret/prekeys/{username}` | Get pre‑key bundle for a user |
| POST | `/api/conversations/{username}/start-secret` | Initiate secret chat (X3DH) |
| POST | `/api/conversations/{username}/accept-secret` | Accept secret chat request |
| GET | `/api/conversations/{username}/keys` | Get peer’s public keys – **missing** |
| POST | `/api/secret/send` | Send encrypted message (Double Ratchet) |
| GET | `/api/secret/messages/{conversationKey}` | Retrieve queued secret messages |
| POST | `/api/secret/ratchet` | Update ratchet key |

**Backend status:**  
- `MessageRepository` and `GroupRepository` exist (SQL). `MessageService` and `GroupService` are almost completely missing. The route handlers in `MessagingRoutes` are stubs (only logging). WebSocket broadcasting is not implemented.
- Missing: Most of the above endpoints have no business logic. The secret chat endpoints are incomplete (e.g., no key storage or ratchet). The poll endpoints are not implemented.

**What a researcher expects:**  
- Real‑time private and group messaging with typing indicators, read receipts, reactions, and file attachments.
- Ability to create polls in groups.
- Secret chats with end‑to‑end encryption.
- Search messages, edit/delete, forward, reply in threads.
- Scheduled and ephemeral messages.
- Archive conversations, mute groups.

---

### 3.4 Real‑time Notifications

**Frontend:** `SmartNotificationCenter`, `useSmartNotifications`, `useWebSocket`.

**Key endpoints:**

| Method | Endpoint | Purpose |
|--------|----------|---------|
| GET | `/api/notifications` | List user notifications (with pagination, type filtering) |
| GET | `/api/notifications/unread-count` | Get unread count |
| POST | `/api/notifications/{id}/read` | Mark as read |
| POST | `/api/notifications/read-all` | Mark all as read |
| POST | `/api/notifications/read-multiple` | Mark multiple by IDs |
| DELETE | `/api/notifications/{id}` | Delete one |
| DELETE | `/api/notifications` | Delete all for user |
| GET | `/api/events` | SSE stream for real‑time notifications (or WebSocket) |

**Smart notification settings:**

| Method | Endpoint | Purpose |
|--------|----------|---------|
| GET | `/api/users/me/notification-settings` | Get settings (deep work mute, batch interval, quiet hours) |
| POST | `/api/users/me/notification-settings` | Update settings |

**Backend status:**  
- `NotificationRepository` exists (SQL). `NotificationService` is a stub. The SSE/WebSocket push is missing. The smart notification settings are not implemented.

**What a researcher expects:**  
- Receive push notifications for new messages, likes, comments, follows, mentions, etc.
- Mark notifications as read/unread, delete.
- Customise when to be disturbed (deep work mode, quiet hours).
- Batch low‑priority notifications (e.g., 5 likes bundled into one notification).

---

### 3.5 Research Assistant (RAG)

**Frontend:** `ResearchAssistantPage`, `useRagSystem`.

**Key endpoints:**

| Method | Endpoint | Purpose |
|--------|----------|---------|
| POST | `/api/ai/rag-chat` | Ask a question with context from indexed documents |
| POST | `/api/ai/chat` | Simple AI chat (no RAG) |
| POST | `/api/ai/command-palette/predict` | AI predictions for command palette |
| POST | `/api/documents/{docId}/rag-index` | Index a document (multipart) |
| GET | `/api/documents/rag-list` | List indexed documents for user |
| DELETE | `/api/documents/{docId}/rag-delete` | Delete indexed document |
| GET | `/api/ai/conversation` | Get conversation history |
| DELETE | `/api/ai/conversation` | Clear history |
| GET | `/api/ai/models` | List available LLM models |
| GET | `/api/ai/health` | LLM backend health check |

**Backend status:**  
- `RagService` is not implemented; the document indexing, vector storage, and LLM integration are missing. The frontend expects a working RAG system, but none exists.

**What a researcher expects:**  
- Upload PDFs, papers, notes, and ask questions like “What are the main findings of paper X?”.
- Get answers with citations to the exact chunk.
- Have a conversation history, clear it, delete documents.

---

### 3.6 Gap Analysis (Knowledge Graph)

**Frontend:** `GapAnalysisPage`, `KnowledgeGraphCanvas`, `useGapAnalysis`.

**Key endpoints:**

| Method | Endpoint | Purpose |
|--------|----------|---------|
| GET | `/api/gap-analysis/nodes` | List all graph nodes |
| POST | `/api/gap-analysis/nodes` | Create node |
| GET | `/api/gap-analysis/nodes/{id}` | Get node |
| PUT | `/api/gap-analysis/nodes/{id}` | Update node |
| DELETE | `/api/gap-analysis/nodes/{id}` | Delete node |
| GET | `/api/gap-analysis/edges` | List edges |
| POST | `/api/gap-analysis/edges` | Create edge |
| GET | `/api/gap-analysis/edges/{id}` | Get edge |
| PUT | `/api/gap-analysis/edges/{id}` | Update edge |
| DELETE | `/api/gap-analysis/edges/{id}` | Delete edge |
| GET | `/api/gap-analysis/nodes/search` | Search nodes by keyword |
| GET | `/api/gap-analysis/nodes/type/{type}` | Filter by type |
| GET | `/api/gap-analysis/stats` | Graph statistics (node/edge counts, degree distribution) |
| POST | `/api/gap-analysis/analyze` | AI‑powered gap analysis (given a topic, suggest missing edges/hypotheses) |
| POST | `/api/gap-analysis/generate-hypothesis` | Generate hypothesis from a node |
| GET | `/api/gap-analysis/export` | Export full graph as JSON |
| POST | `/api/gap-analysis/import` | Import graph from JSON |

**Backend status:**  
- `GraphRepository` exists (in‑memory). `GapAnalysisService` is a stub. The AI analysis endpoints are not implemented.

**What a researcher expects:**  
- See a visual graph of papers, concepts, methods, gaps.
- Search and highlight nodes, filter by type.
- Run “gap analysis” on a topic – the AI should propose novel research directions.
- Generate hypotheses from existing nodes.
- Export/import the graph for collaboration.

---

### 3.7 Grant Assistant

**Frontend:** `GrantAssistantPage`, `useGrants`.

**Key endpoints:**

| Method | Endpoint | Purpose |
|--------|----------|---------|
| GET | `/api/grants/deadlines` | Upcoming deadlines (sorted) |
| GET | `/api/grants` | User’s grants |
| POST | `/api/grants` | Add a grant |
| PUT | `/api/grants/{id}` | Update grant |
| DELETE | `/api/grants/{id}` | Delete grant |
| POST | `/api/grants/generate` | AI draft generation (given RFP text) |
| POST | `/api/grants/analyze` | Analyze RFP (match score, requirements) |

**Backend status:**  
- `GrantRepository` exists (in‑memory). `GrantService` is missing. AI endpoints are not implemented.

**What a researcher expects:**  
- Keep track of grant deadlines, statuses.
- Upload an RFP (Request for Proposals) and get a draft proposal generated by AI.
- Get a score on how well their research matches the RFP.

---

### 3.8 Lab Inventory

**Frontend:** `LabInventoryPage`, `useLabInventory`.

**Key endpoints (many – I'll summarise):**

- Chemicals CRUD (list, create, update, delete), search, filter by location/type/low stock/expiry.
- Barcode scanning (lookup by barcode, register new barcode).
- Alerts (list, acknowledge, delete).
- Compatibility checking (between two chemicals, based on NFPA or rules).
- Statistics (total, low stock, expiring, alerts).

**Backend status:**  
- `ChemicalRepository` and `AlertRepository` exist (in‑memory). `LabInventoryService` is largely missing. Compatibility rules are not implemented.

**What a researcher expects:**  
- Manage lab chemicals with barcode scanning.
- Get alerts when stock is low or chemicals are expiring.
- Check compatibility before storing chemicals together.
- Export inventory to CSV.

---

### 3.9 Peer Review

**Frontend:** `PeerReviewPage`, `usePeerReview`.

**Key endpoints:**

| Method | Endpoint | Purpose |
|--------|----------|---------|
| GET | `/api/peer-review/submissions` | List open submissions (anonymised) |
| POST | `/api/peer-review/submit` | Submit a paper |
| GET | `/api/peer-review/submissions/{id}` | Get submission details (anonymised) |
| POST | `/api/peer-review/submissions/{id}/claim` | Claim a review |
| GET | `/api/peer-review/my-assigned` | Submissions assigned to me |
| POST | `/api/peer-review/submissions/{id}/review` | Submit review (scores, comments) |
| GET | `/api/peer-review/my-reviews` | Reviews I wrote |
| GET | `/api/peer-review/my-credentials` | Get reviewer credentials (ORCID, expertise) |
| POST | `/api/peer-review/my-credentials` | Save credentials |

**Admin endpoints:**

| Method | Endpoint | Purpose |
|--------|----------|---------|
| GET | `/api/admin/peer-review/submissions` | List all submissions |
| POST | `/api/admin/peer-review/submissions/{id}/assign` | Assign a reviewer |
| DELETE | `/api/admin/peer-review/submissions/{id}` | Delete submission |
| GET | `/api/peer-review/stats` | Statistics (pending, assigned, reviewed) |

**Backend status:**  
- `PeerReviewRepository` exists (in‑memory). `PeerReviewService` is a stub. The anonymisation and assignment logic are missing.

**What a researcher expects:**  
- Submit papers anonymously for peer review.
- Claim reviews, submit structured reviews (scores, comments, recommendation).
- Keep a profile of expertise to get appropriate assignments.

---

### 3.10 Data Hub (Research Objects, Protocols, Preregistrations)

**Frontend:** `DataHubPage`, `useResearchObjectRepository`, `useProtocolsWorkspace`, `usePreregistration`.

**Research objects endpoints:**

| Method | Endpoint | Purpose |
|--------|----------|---------|
| GET | `/api/repository/objects` | User’s research objects |
| GET | `/api/repository/objects/{id}` | Get object |
| POST | `/api/repository/objects` | Create object (with file upload) |
| PUT | `/api/repository/objects/{id}` | Update metadata |
| DELETE | `/api/repository/objects/{id}` | Delete object |
| POST | `/api/repository/objects/{id}/download` | Increment download count |

**Protocols endpoints:**

| Method | Endpoint | Purpose |
|--------|----------|---------|
| GET | `/api/protocols` | User’s protocols |
| GET | `/api/protocols/public` | Public protocols (no auth) |
| GET | `/api/protocols/{id}` | Get protocol |
| POST | `/api/protocols` | Create protocol |
| PUT | `/api/protocols/{id}` | Update |
| DELETE | `/api/protocols/{id}` | Delete |
| POST | `/api/protocols/{id}/fork` | Fork a protocol |
| GET | `/api/protocols/{id}/steps` | Get steps |
| POST | `/api/protocols/{id}/steps` | Add step |
| PUT | `/api/protocols/{id}/steps/{stepId}` | Update step |
| DELETE | `/api/protocols/{id}/steps/{stepId}` | Delete step |

**Preregistrations endpoints:**

| Method | Endpoint | Purpose |
|--------|----------|---------|
| GET | `/api/preregistrations` | User’s preregistrations |
| GET | `/api/preregistrations/{id}` | Get preregistration |
| POST | `/api/preregistrations` | Create draft |
| PUT | `/api/preregistrations/{id}` | Update |
| PUT | `/api/preregistrations/{id}/sections/{sectionId}` | Update section content |
| POST | `/api/preregistrations/{id}/submit` | Submit for DOI (time‑stamped) |
| DELETE | `/api/preregistrations/{id}` | Delete |

**Backend status:**  
- `ResearchObjectRepository`, `ProtocolRepository`, `PreregistrationRepository` exist (in‑memory). `DataHubService` is missing. File upload storage is not implemented. DOI generation is not implemented.

**What a researcher expects:**  
- Share datasets, code, presentations with a DOI (citable).
- Write lab protocols with step‑by‑step checklists, fork other protocols.
- Preregister studies with templates, get a time‑stamped DOI.

---

### 3.11 Project Workspace (Kanban)

**Frontend:** `ProjectWorkspacePage`, `useProjectSpace`, `useProjectTaskManager`.

**Key endpoints:**

| Method | Endpoint | Purpose |
|--------|----------|---------|
| GET | `/api/projects` | User’s projects (owned + member) |
| POST | `/api/projects` | Create project |
| GET | `/api/projects/{id}` | Get project |
| PUT | `/api/projects/{id}` | Update |
| DELETE | `/api/projects/{id}` | Delete |
| GET | `/api/projects/{id}/members` | List members with roles |
| POST | `/api/projects/{id}/members` | Add member |
| PUT | `/api/projects/{id}/members/{userId}` | Update role |
| DELETE | `/api/projects/{id}/members/{userId}` | Remove member |
| GET | `/api/projects/{id}/tasks` | List tasks |
| POST | `/api/projects/{id}/tasks` | Create task |
| GET | `/api/projects/{projectId}/tasks/{taskId}` | Get task |
| PUT | `/api/projects/{projectId}/tasks/{taskId}` | Update task (title, description, priority, tags, dependencies) |
| PATCH | `/api/projects/{projectId}/tasks/{taskId}/move` | Move to another column |
| DELETE | `/api/projects/{projectId}/tasks/{taskId}` | Delete task |
| GET | `/api/projects/{id}/outputs` | List outputs |
| POST | `/api/projects/{id}/outputs` | Add output (link external resource) |
| DELETE | `/api/projects/{id}/outputs/{outputId}` | Delete output |
| GET | `/api/projects/search` | Search projects by name |
| GET | `/api/projects/{id}/activity` | Activity log (stub) |
| POST | `/api/projects/{id}/invite` | Invite user by email |

**Backend status:**  
- `ProjectRepository` exists (in‑memory). `ProjectService` is a stub. Task dependencies and activity log are missing.

**What a researcher expects:**  
- Manage research projects with a Kanban board (backlog, in progress, review, done).
- Assign tasks to members, set priorities, add tags, create dependencies.
- Link outputs (articles, datasets, presentations).
- See project activity log.

---

### 3.12 Events & Networking

**Frontend:** `EventPage`, `NetworkingPage`, `useEvents`.

**Key endpoints:**

| Method | Endpoint | Purpose |
|--------|----------|---------|
| GET | `/api/events` | List events (public, with filters) |
| GET | `/api/events/upcoming` | Upcoming events (now + future) |
| GET | `/api/events/my-events` | Events the user is attending |
| GET | `/api/events/{id}` | Get event details |
| POST | `/api/events` | Create event |
| PUT | `/api/events/{id}` | Update event |
| DELETE | `/api/events/{id}` | Delete event |
| POST | `/api/events/{id}/image` | Upload event image |
| POST | `/api/events/{id}/rsvp` | RSVP (going/interested/not going) |
| GET | `/api/events/{id}/attendees` | List attendees |
| POST | `/api/events/{id}/reminders` | Set reminder |
| GET | `/api/events/{id}/reminders` | Get reminders for user |
| DELETE | `/api/events/reminders/{reminderId}` | Delete reminder |
| POST | `/api/events/recurring` | Create recurring events |
| GET | `/api/events/calendar.ics` | Export user events as iCal |
| POST | `/api/events/{id}/invite` | Invite users by email |
| GET | `/api/events/search` | Search events |

**Backend status:**  
- `EventRepository` exists (in‑memory). `EventService` is missing. The iCal export and reminder email sending are not implemented.

**What a researcher expects:**  
- Create conferences, lab meetings, deadlines.
- RSVP, set reminders, add to calendar (iCal).
- See who is attending.
- Discover events in their field.

---

### 3.13 Workspace (SmartGlass)

**Frontend:** `SmartGlassWorkspace`, `useSmartGlassWorkspace`.

**Key endpoints:**

| Method | Endpoint | Purpose |
|--------|----------|---------|
| GET | `/api/workspace/panels` | Get user’s panels |
| GET | `/api/workspace/panels/{id}` | Get a panel |
| POST | `/api/workspace/panels` | Create panel |
| PUT | `/api/workspace/panels/{id}` | Update panel (title, props, position, size) |
| PATCH | `/api/workspace/panels/{id}` | Partial update (e.g., rename) |
| DELETE | `/api/workspace/panels/{id}` | Delete panel |
| POST | `/api/workspace/panels/{id}/duplicate` | Duplicate panel |
| POST | `/api/workspace/panels/reorder` | Reorder panels |
| GET | `/api/workspace/panels/export` | Export workspace as JSON |
| POST | `/api/workspace/panels/import` | Import workspace from JSON |
| DELETE | `/api/workspace/panels/all` | Clear all panels |
| GET | `/api/workspace/presets` | List built‑in presets |
| POST | `/api/workspace/presets/{presetId}/apply` | Apply preset |
| POST | `/api/workspace/panels/{id}/share` | Create shareable link |
| GET | `/api/workspace/share/{token}` | View shared panel (no auth) |
| GET | `/api/workspace/active` | Get active panel |
| POST | `/api/workspace/active/{id}` | Set active panel |

**Backend status:**  
- `WorkspaceRepository` does not exist (not in provided files). `WorkspaceService` is missing entirely. The route handlers are stubs.

**What a researcher expects:**  
- Customise the workspace layout (AI chat, editor, browser, inventory, etc.).
- Save layouts as presets, apply built‑in presets (research mode, grant writing, literature review).
- Share a read‑only version of their workspace.
- Backup/restore workspace state.

---

### 3.14 Voice Assistant

**Frontend:** `VoiceAssistantWidget`, `VoiceSettingsModal`, `useVoiceAssistant`.

**Key endpoints:**

| Method | Endpoint | Purpose |
|--------|----------|---------|
| GET | `/api/users/me/voice-settings` | Get voice settings |
| PUT | `/api/users/me/voice-settings` | Update settings |
| DELETE | `/api/users/me/voice-settings/reset` | Reset to default |
| GET | `/api/users/me/voice-settings/profiles` | List voice profiles |
| PUT | `/api/users/me/voice-settings/profiles/{profileName}` | Save profile |
| DELETE | `/api/users/me/voice-settings/profiles/{profileName}` | Delete profile |
| POST | `/api/users/me/voice-settings/profiles/{profileName}/activate` | Activate profile |
| GET | `/api/users/me/voice-settings/language/{lang}` | Get language overrides |
| PUT | `/api/users/me/voice-settings/language/{lang}` | Set language overrides |
| GET | `/api/voice/voices` | List system TTS voices |
| POST | `/api/voice/tts/test` | Test TTS (returns audio URL) |
| GET | `/api/users/me/voice-settings/wake-words` | List wake words |
| POST | `/api/users/me/voice-settings/wake-words` | Add wake word |
| DELETE | `/api/users/me/voice-settings/wake-words/{word}` | Remove wake word |
| GET | `/api/users/me/voice-settings/grammar` | Get custom grammar |
| PUT | `/api/users/me/voice-settings/grammar` | Set custom grammar |
| GET | `/api/users/me/voice-settings/export` | Export all voice settings (JSON) |
| POST | `/api/users/me/voice-settings/import` | Import voice settings |

**Backend status:**  
- `VoiceSettingsRepository` exists (in‑memory). `VoiceSettingsService` is missing. The TTS test endpoint would need to generate audio (external service).

**What a researcher expects:**  
- Configure speech recognition language, TTS voice, pitch, speed.
- Set auto‑speak for AI responses.
- Define wake words to activate the assistant hands‑free.
- Manage multiple profiles (e.g., “presentation mode”, “quiet study”).

---

### 3.15 Admin

**Frontend:** `AdminPage`, `useAdminStats`.

**Key endpoints:**

| Method | Endpoint | Purpose |
|--------|----------|---------|
| GET | `/api/admin/stats` | Platform statistics (users, articles, comments, views, likes, messages, groups, notifications, projects) |
| GET | `/api/admin/users` | List all users |
| DELETE | `/api/admin/users/{id}` | Delete user |
| GET | `/api/admin/articles` | List all articles |
| DELETE | `/api/admin/articles/{id}` | Delete article |
| DELETE | `/api/admin/articles` | Clear all articles |
| GET | `/api/admin/activity` | Recent activity feed |
| GET | `/api/admin/search` | Global search across entities (users, articles, groups, chemicals, grants, projects, research objects, polls, events) |
| GET | `/api/admin/2fa/status` | 2FA usage statistics |
| GET | `/api/admin/workspace/panels` | List workspace presets (global) |
| GET | `/api/admin/rag/documents` | List all indexed RAG documents |
| GET | `/api/admin/stats/activity` | Platform activity over time (users, articles, comments, messages) |
| GET | `/api/admin/stats/top-contributors` | Top contributors (by articles, comments, likes) |
| GET | `/api/admin/stats/export/json` | Export full platform stats as JSON |

**Backend status:**  
- Some admin endpoints exist in `AdminController`, but `AdminService` is missing. Global search is stubbed.

**What a researcher (as admin) expects:**  
- View platform health (user growth, content volume, server uptime).
- Manage users and articles (delete spam, promote to admin).
- Search across all entities.
- Get activity feed (recent registrations, publications, groups).

---

### 3.16 Paper Collections

**Frontend:** `PaperCollectionsPage`, `usePaperCollections`.

**Key endpoints (missing entirely):**

| Method | Endpoint | Purpose |
|--------|----------|---------|
| GET | `/api/collections` | List user’s collections |
| POST | `/api/collections` | Create collection |
| DELETE | `/api/collections/{id}` | Delete collection |
| POST | `/api/collections/{id}/papers` | Add a paper (by article ID) |
| DELETE | `/api/collections/{id}/papers/{paperId}` | Remove paper |

**Backend status:**  
- No models, repositories, services, or endpoints.

**What a researcher expects:**  
- Group papers into custom collections (e.g., “Deep learning review”, “Grant proposals”).
- Share collections publicly or keep private.
- Add/remove papers easily.

---

### 3.17 Reference Manager

**Frontend:** `AuthoringStudioPage` (reference panel), `useReferenceManager`.

**Key endpoints (missing entirely):**

| Method | Endpoint | Purpose |
|--------|----------|---------|
| GET | `/api/documents/{docId}/references` | List references for a document |
| POST | `/api/documents/{docId}/references` | Add a reference (DOI, BibTeX, or from external source) |
| PUT | `/api/documents/{docId}/references/{refId}` | Update reference |
| DELETE | `/api/documents/{docId}/references/{refId}` | Delete reference |
| POST | `/api/references/connect-zotero` | Import references from Zotero (API key) |
| POST | `/api/references/connect-mendeley` | Import from Mendeley (access token) |

**Backend status:**  
- No models, repositories, services, or endpoints.

**What a researcher expects:**  
- Import references from DOI, BibTeX, Zotero, Mendeley.
- Organise references into groups.
- Generate a bibliography in APA, MLA, or BibTeX for a document.
- Insert citations into the collaborative editor.

---

### 3.18 Preprint Submission

**Frontend:** `PreprintSubmissionPage`, `usePreprintSubmission`.

**Key endpoints (missing entirely):**

| Method | Endpoint | Purpose |
|--------|----------|---------|
| POST | `/api/preprints/screen` | Screen preprint (check against criteria) |
| POST | `/api/preprints/submit` | Submit preprint, assign DOI, set status |

**Backend status:**  
- No models, repositories, services, or endpoints.

**What a researcher expects:**  
- Upload a manuscript, get a quick screening (format, plagiarism check).
- Receive a DOI immediately upon submission (timestamped).
- Track submission status.

---

### 3.19 Provenance / Trust

**Frontend:** `useProvenance` (hook exists, but no dedicated page yet).

**Key endpoints (missing entirely):**

| Method | Endpoint | Purpose |
|--------|----------|---------|
| GET | `/api/provenance/{entityType}/{entityId}` | Get provenance events for an entity (article, user, chemical, etc.) |
| POST | `/api/provenance/{entityType}/{entityId}/verify` | Verify integrity chain (e.g., check signatures) |

**Backend status:**  
- No models, repositories, services, or endpoints.

**What a researcher expects:**  
- See who created, modified, published an article (audit trail).
- Verify that the content has not been tampered with (e.g., blockchain or digital signatures).

---

### 3.20 Unified Inbox

**Frontend:** `UnifiedInboxPage`, `useUnifiedInbox`.

**Key endpoint (missing):**

| Method | Endpoint | Purpose |
|--------|----------|---------|
| GET | `/api/unified-inbox` | Aggregated messages from all sources (private, groups, projects, paper Q&A, AI chats, broadcasts) |

**Backend status:**  
- No service or endpoint.

**What a researcher expects:**  
- One inbox that shows all conversations (direct messages, group chats, project discussions, paper Q&A, AI assistant chats, broadcast announcements).
- Filter by type, unread, critical, etc.
- Mark as read, forward to another chat.

---

### 3.21 Recent Items (Command Palette)

**Frontend:** `App.tsx` fetches recent papers and contacts for the command palette.

**Key endpoint (missing):**

| Method | Endpoint | Purpose |
|--------|----------|---------|
| GET | `/api/recent-items` | Return list of recently viewed articles and recently contacted users |

**Backend status:**  
- No service or endpoint.

**What a researcher expects:**  
- When pressing `Ctrl+K`, see recently opened articles and recent chat partners to quickly navigate.

---

## 4. Cross‑Cutting Missing Infrastructure

Beyond specific endpoints, the following infrastructure pieces are essential for a production‑grade system:

| Component | Purpose | Current State |
|-----------|---------|----------------|
| **JWT authentication** | Stateless auth, refresh tokens, CSRF protection | Custom session tokens (stub) – missing full JWT implementation |
| **WebSocket clustering** | Broadcast messages to all instances of backend (when multiple servers run) | Not implemented |
| **Async task processing** | Email, PDF generation, model inference, notifications | Not implemented (everything is synchronous) |
| **Message queue (RabbitMQ/Kafka)** | Decouple event producers from consumers (e.g., when an article is published, send emails, update search index, notify followers) | Not implemented |
| **Caching (Redis)** | Cache user profiles, trending articles, recommendations | Not implemented |
| **Full‑text search (Elasticsearch)** | Fast, relevant search across articles, messages, users | Only SQL `LIKE` (slow, no relevance ranking) |
| **Distributed rate limiting** | Prevent abuse across multiple instances | `TokenBucket` exists but not integrated globally |
| **Structured logging & metrics** | Log in JSON, expose Prometheus metrics | No structured logging, no metrics |
| **Health checks** | Liveness/readiness probes for Kubernetes | Only basic `/health` |
| **Database migrations** | Version‑controlled schema changes | No migration tool (Flyway/Liquibase) |
| **API documentation** | OpenAPI/Swagger for client‑side code generation | None |
| **Testing** | Unit, integration, end‑to‑end tests | None |

---

## 5. Summary: What Must Be Implemented

To make your platform truly complete and ready for researchers, you must build:

| Category | Count | Examples |
|----------|-------|----------|
| **Services** | ~25 | `UserService`, `ArticleService`, `MessageService`, `GroupService`, `NotificationService`, `AnalyticsService`, `GapAnalysisService`, `GrantService`, `ProjectService`, `DataHubService`, `PollService`, `EventService`, `LabInventoryService`, `PeerReviewService`, `WorkspaceService`, `VoiceSettingsService`, `RagService`, `PasswordResetService`, `TwoFactorService`, `SearchService`, `MediaService`, `RateLimitService`, `ContentModeration`, `CitationGraphService`, `RecommendationService` |
| **Route handlers** | ~200 | Fill in all missing endpoints (collections, references, preprints, provenance, unified inbox, recent items, etc.) |
| **DTOs** | ~50 | Request/response objects for all endpoints |
| **Models** | ~20 | Already have most, but need `PreKey`, `SignedPreKey`, `Collection`, `Reference`, `Preprint`, `ProvenanceEvent`, `UnifiedMessage`, `RecentItem`, etc. |
| **Utilities** | ~15 | `SessionManager`, `WebSocketManager`, `MailService`, `FileStorageService`, `CitationGenerator`, `ExportConverter`, `HtmlSanitizer`, `JwtUtil`, `TotpUtil`, etc. |
| **Infrastructure** | ~10 | RabbitMQ, Redis, Elasticsearch, Prometheus, Grafana, Flyway, Docker, Kubernetes, GitHub Actions |