Projects/docs/API_DOCS.md

# **Backend API Reference – IE Research Platform (from Java code)**

> **Base URL:** `/api` (unless otherwise noted)  
> **Authentication:** JWT token via `Authorization: Bearer <token>` header or `auth_token` cookie.  
> **WebSocket:** Main WebSocket at `ws://localhost:8080/ws` (handled by `WebSocketManager`), collaboration WebSocket at `ws://localhost:9093` (Yjs).  
> **Static files:** Served from `/src/main/resources/Templates/` with compression, range requests, and SPA fallback.

---

## 1. Authentication & User Management

| Method | Endpoint | Description | Java Class / Method |
|--------|----------|-------------|----------------------|
| POST | `/api/login` | Login (returns JWT token + CSRF token) | `AuthRoutes` → `registerLogin()` |
| POST | `/api/login/2fa` | Complete login with TOTP code | `AuthRoutes` → `/login/2fa` |
| POST | `/api/logout` | Logout, invalidate token | `AuthRoutes` → `/logout` |
| POST | `/api/register` | Register new user | `AuthRoutes` → `/register` |
| POST | `/api/token/refresh` | Refresh JWT token | `AuthRoutes` → `/token/refresh` |
| GET | `/api/users/me` | Get current user profile | `UserRoutes` → `/users/me` |
| PUT | `/api/users/me` | Update profile | `UserRoutes` → `/users/me` |
| PUT | `/api/users/me/email` | Change email | `UserRoutes` → `/users/me/email` |
| PUT | `/api/users/me/password` | Change password | `UserRoutes` → `/users/me/password` |
| DELETE | `/api/users/me` | Deactivate account | `UserRoutes` → `/users/me` |
| POST | `/api/users/me/avatar` | Upload avatar (base64) | `UserRoutes` → `/users/me/avatar` |
| GET | `/api/users/{username}` | Get public profile (respects privacy) | `UserRoutes` → `/users/{username}` |
| GET | `/api/search/users` | Search users (paginated) | `UserRoutes` → `/search/users` |
| GET | `/api/users/me/security-question` | Get security question | `UserRoutes` → `/users/me/security-question` |
| PUT | `/api/users/me/security-question` | Set security question & answer | `UserRoutes` → `/users/me/security-question` |
| GET | `/api/users/me/2fa/status` | Check if 2FA is enabled | `UserRoutes` → `/users/me/2fa/status` |
| POST | `/api/users/me/2fa/enable` | Enable 2FA (generates secret & QR) | `AuthRoutes` → `/users/me/2fa/enable` |
| POST | `/api/users/me/2fa/verify` | Verify TOTP code to enable 2FA | `AuthRoutes` → `/users/me/2fa/verify` |
| POST | `/api/users/me/2fa/disable` | Disable 2FA | `AuthRoutes` → `/users/me/2fa/disable` |
| GET | `/api/users/me/2fa/backup-codes` | Retrieve backup codes | `AuthRoutes` → `/users/me/2fa/backup-codes` |
| POST | `/api/users/me/2fa/backup-codes/regenerate` | Regenerate backup codes | `AuthRoutes` → `/users/me/2fa/backup-codes/regenerate` |
| POST | `/api/forgot-password` | Request security question for password reset | `AuthRoutes` (and `PasswordResetRoutes`) |
| POST | `/api/reset-password` | Reset password using security answer | `AuthRoutes` (and `PasswordResetRoutes`) |

---

## 2. Follow System

| Method | Endpoint | Description | Java Class / Method |
|--------|----------|-------------|----------------------|
| POST | `/api/users/{username}/follow` | Follow a user | `UserRoutes` → `/users/{username}/follow` |
| DELETE | `/api/users/{username}/follow` | Unfollow a user | `UserRoutes` → `/users/{username}/follow` |
| GET | `/api/users/{username}/followers` | List followers (paginated) | `UserRoutes` → `/users/{username}/followers` |
| GET | `/api/users/{username}/following` | List following (paginated) | `UserRoutes` → `/users/{username}/following` |
| GET | `/api/users/me/contacts` | Get followed users with extra fields (online, mutual followers) | `UserRoutes` → `/users/me/contacts` |

---

## 3. Articles

| Method | Endpoint | Description | Java Class / Method |
|--------|----------|-------------|----------------------|
| GET | `/api/articles` | List articles (paginated, filterable) | `ArticleRoutes` (or `ArticleApiController`) |
| GET | `/api/articles/{id}` | Get single article | `ArticleApiController` |
| POST | `/api/articles` | Create article (authenticated) | `ArticleApiController` |
| PUT | `/api/articles/{id}` | Update article (author or admin) | `ArticleApiController` |
| DELETE | `/api/articles/{id}` | Delete article (author or admin) | `ArticleApiController` |
| GET | `/api/articles/search` | Search articles (with pagination & sorting) | `ArticleRoutes` → `/articles/search` |
| GET | `/api/users/me/articles` | Get current user's articles (including drafts) | `ArticleRoutes` → `/users/me/articles` |
| POST | `/api/articles/{id}/like` | Toggle like | `ArticleApiController` |
| GET | `/api/articles/{id}/like` | Get like status | `ArticleApiController` |
| GET | `/api/articles/{id}/comments` | Get comments for article | `ArticleApiController` |
| POST | `/api/articles/{id}/comments` | Add comment | `ArticleApiController` |
| DELETE | `/api/comments/{commentId}` | Delete comment | `ArticleApiController` |
| GET | `/api/articles/{id}/citation` | Generate citation (APA, MLA, etc.) | `ArticleApiController` |
| GET | `/api/users/me/analytics` | User analytics (views, likes, comments, etc.) | `ArticleApiController` / `AnalyticsRoutes` |
| POST | `/api/articles/{id}/publish` | Publish a draft | `ArticleApiController` |
| GET | `/api/articles/trending` | Trending articles (by views/likes) | `ArticleRoutes` → `/articles/trending` |
| GET | `/api/articles/featured` | Featured articles (admin picks) | `ArticleRoutes` → `/articles/featured` |
| GET | `/api/articles/{id}/graph-recommendations` | Graph‑based recommendations (co‑citation, bibliographic, PageRank) | `ArticleRoutes` → `/articles/{id}/graph-recommendations` |
| POST | `/api/articles/{id}/view` | Increment view count | `ArticleRoutes` → `/articles/{id}/view` |

---

## 4. Messaging (Private & Group)

### Private Conversations

| Method | Endpoint | Description | Java Class / Method |
|--------|----------|-------------|----------------------|
| GET | `/api/conversations` | List private conversations | `MessagingRoutes` |
| DELETE | `/api/conversations/{username}` | Delete conversation | `MessagingRoutes` |
| GET | `/api/conversations/{username}/messages` | Get messages with a user (paginated) | `MessagingRoutes` |
| POST | `/api/conversations/{username}/messages` | Send a message | `MessagingRoutes` |
| PUT | `/api/conversations/{username}/messages/{messageId}` | Edit message | `MessagingRoutes` |
| DELETE | `/api/conversations/{username}/messages/{messageId}` | Delete message | `MessagingRoutes` |
| POST | `/api/conversations/{username}/messages/{messageId}/reactions` | Add/remove reaction | `MessagingRoutes` |
| POST | `/api/conversations/{username}/typing` | Send typing indicator | `MessagingRoutes` |
| GET | `/api/conversations/{username}/typing` | Check if other user is typing | `MessagingRoutes` |
| POST | `/api/conversations/{username}/read` | Mark messages as read (up to a messageId) | `MessagingRoutes` |
| GET | `/api/conversations/{username}/read-status` | Get last read message ID | `MessagingRoutes` |
| POST | `/api/conversations/{username}/archive` | Archive conversation | `MessagingRoutes` |
| DELETE | `/api/conversations/{username}/archive` | Unarchive conversation | `MessagingRoutes` |
| GET | `/api/users/me/archived-conversations` | List archived conversations | `MessagingRoutes` |

### Groups

| Method | Endpoint | Description | Java Class / Method |
|--------|----------|-------------|----------------------|
| GET | `/api/groups` | List groups user belongs to | `MessagingRoutes` |
| POST | `/api/groups` | Create group | `MessagingRoutes` |
| GET | `/api/groups/{groupId}` | Get group details | `MessagingRoutes` |
| PUT | `/api/groups/{groupId}` | Update group (name, description, avatar, slow‑mode) | `MessagingRoutes` |
| DELETE | `/api/groups/{groupId}` | Delete group (admin only) | `MessagingRoutes` |
| GET | `/api/groups/{groupId}/members` | List group members | `MessagingRoutes` |
| POST | `/api/groups/{groupId}/members` | Add member(s) | `MessagingRoutes` |
| DELETE | `/api/groups/{groupId}/members/{memberId}` | Remove member | `MessagingRoutes` |
| POST | `/api/groups/{groupId}/admins/{memberId}` | Promote to admin | `MessagingRoutes` |
| POST | `/api/groups/{groupId}/members/{memberId}/demote` | Demote from admin | `MessagingRoutes` |
| POST | `/api/groups/{groupId}/leave` | Leave group | `MessagingRoutes` |
| POST | `/api/groups/{groupId}/invite` | Generate invite link | `MessagingRoutes` |
| GET | `/api/join/{token}` | Join group via invite token (redirects) | `MessagingRoutes` |
| GET | `/api/groups/{groupId}/messages` | Get group messages (paginated) | `MessagingRoutes` |
| POST | `/api/groups/{groupId}/messages` | Send group message | `MessagingRoutes` |
| PUT | `/api/groups/{groupId}/messages/{messageId}` | Edit group message | `MessagingRoutes` |
| DELETE | `/api/groups/{groupId}/messages/{messageId}` | Delete group message | `MessagingRoutes` |
| GET | `/api/groups/{groupId}/messages/since` | Get messages since a timestamp | `MessagingRoutes` |
| POST | `/api/groups/{groupId}/read` | Mark messages as read (read receipt) | `MessagingRoutes` |
| GET | `/api/groups/{groupId}/read-status` | Get read status for all members | `MessagingRoutes` |
| POST | `/api/groups/{groupId}/mute` | Mute group | `MessagingRoutes` |
| DELETE | `/api/groups/{groupId}/mute` | Unmute group | `MessagingRoutes` |
| GET | `/api/groups/{groupId}/pins` | List pinned messages | `MessagingRoutes` |
| POST | `/api/groups/{groupId}/pin/{messageId}` | Pin message | `MessagingRoutes` |
| DELETE | `/api/groups/{groupId}/pin/{messageId}` | Unpin message | `MessagingRoutes` |
| POST | `/api/groups/{groupId}/transfer/{newOwnerId}` | Transfer group ownership | `MessagingRoutes` |
| GET | `/api/groups/{groupId}/meta` | Group metadata (slow‑mode, etc.) | `MessagingRoutes` |

### Secret Chats (E2EE)

| Method | Endpoint | Description | Java Class / Method |
|--------|----------|-------------|----------------------|
| POST | `/api/secret/prekeys` | Upload pre‑key bundle | `SecretConversationRoutes` |
| GET | `/api/secret/prekeys/{username}` | Get pre‑key bundle for a user | `SecretConversationRoutes` |
| POST | `/api/secret/prekeys/refresh` | Refresh one‑time pre‑keys | `SecretConversationRoutes` |
| POST | `/api/conversations/{username}/start-secret` | Initiate secret chat (X3DH) | `MessagingRoutes` (and `SecretConversationRoutes`) |
| POST | `/api/conversations/{username}/accept-secret` | Accept secret chat request | `SecretConversationRoutes` |
| GET | `/api/secret/sessions` | List secret chat sessions | `SecretConversationRoutes` |
| POST | `/api/secret/send` | Send encrypted message (Double Ratchet) | `SecretConversationRoutes` |
| GET | `/api/secret/messages/{conversationKey}` | Retrieve queued secret messages | `SecretConversationRoutes` |
| POST | `/api/secret/ratchet` | Update ratchet key | `SecretConversationRoutes` |

### Polls & Quizzes (in groups)

| Method | Endpoint | Description | Java Class / Method |
|--------|----------|-------------|----------------------|
| POST | `/api/groups/{groupId}/polls` | Create a poll/quiz | `MessagingRoutes` |
| GET | `/api/polls/{pollId}` | Get poll details | `MessagingRoutes` |
| POST | `/api/polls/{pollId}/vote` | Vote (optionIds array) | `MessagingRoutes` |
| POST | `/api/polls/{pollId}/close` | Close poll | `MessagingRoutes` |
| POST | `/api/polls/{pollId}/reopen` | Reopen closed poll | `MessagingRoutes` |
| DELETE | `/api/polls/{pollId}` | Delete poll | `MessagingRoutes` |
| GET | `/api/polls/{pollId}/results` | Public results (no auth) | `PollRoutes` |
| GET | `/api/polls/{pollId}/analytics` | Detailed analytics (creator/admin) | `PollRoutes` |
| GET | `/api/polls/{pollId}/export/csv` | Export results as CSV | `PollRoutes` |
| GET | `/api/polls` | List polls (filtered, paginated) | `PollRoutes` |
| POST | `/api/polls` | Create poll (standalone) | `PollRoutes` |
| PUT | `/api/polls/{id}` | Update poll (question, options, expiry) | `PollRoutes` |
| GET | `/api/polls/{id}/my-vote` | Get user's vote | `PollRoutes` |
| GET | `/api/polls/templates` | List poll templates | `PollRoutes` |
| POST | `/api/polls/{id}/schedule` | Schedule activation | `PollRoutes` |
| PUT | `/api/polls/{id}/privacy` | Set privacy (public/group/project) | `PollRoutes` |

### Forward & Threads

| Method | Endpoint | Description | Java Class / Method |
|--------|----------|-------------|----------------------|
| POST | `/api/messages/{messageId}/forward` | Forward a private message | `MessagingRoutes` |
| POST | `/api/groups/messages/{messageId}/forward-to-group` | Forward group message | `MessagingRoutes` |
| GET | `/api/messages/{messageId}/thread` | Get thread replies | `MessagingRoutes` |
| POST | `/api/messages/{messageId}/reply` | Post a thread reply | `MessagingRoutes` |

### Media Attachments

| Method | Endpoint | Description | Java Class / Method |
|--------|----------|-------------|----------------------|
| POST | `/api/media/upload` | Upload file (base64) | `MessagingRoutes` |
| GET | `/api/media/{mediaId}` | Get media metadata | `MessagingRoutes` |
| DELETE | `/api/media/{mediaId}` | Delete media (owner only) | `MessagingRoutes` |
| GET | `/api/messages/{messageId}/media` | List media for a message | `MessagingRoutes` |

### Search in Messages

| Method | Endpoint | Description | Java Class / Method |
|--------|----------|-------------|----------------------|
| GET | `/api/conversations/search` | Basic private message search | `MessagingRoutes` |
| GET | `/api/conversations/search/advanced` | Advanced search (with filters) | `MessagingRoutes` |
| GET | `/api/groups/{groupId}/search` | Search group messages | `MessagingRoutes` |
| GET | `/api/groups/{groupId}/search/advanced` | Advanced group search | `MessagingRoutes` |

### Scheduled & Ephemeral Messages

| Method | Endpoint | Description | Java Class / Method |
|--------|----------|-------------|----------------------|
| POST | `/api/conversations/{username}/schedule` | Schedule a message | `MessagingRoutes` |
| POST | `/api/conversations/{username}/ephemeral` | Send ephemeral message | `MessagingRoutes` |
| GET | `/api/messages/scheduled` | List scheduled messages | `MessagingRoutes` |
| DELETE | `/api/messages/scheduled/{messageId}` | Cancel scheduled message | `MessagingRoutes` |

---

## 5. Notifications

| Method | Endpoint | Description | Java Class / Method |
|--------|----------|-------------|----------------------|
| GET | `/api/notifications` | List user notifications (paginated, filterable) | `NotificationRoutes` (and `NotificationController`) |
| GET | `/api/notifications/unread-count` | Get unread count | `NotificationRoutes` |
| POST | `/api/notifications/{id}/read` | Mark notification as read | `NotificationRoutes` |
| POST | `/api/notifications/read-all` | Mark all as read | `NotificationRoutes` |
| POST | `/api/notifications/read-multiple` | Mark multiple as read | `NotificationRoutes` |
| DELETE | `/api/notifications/{id}` | Delete notification | `NotificationRoutes` |
| DELETE | `/api/notifications` | Delete all notifications for user | `NotificationRoutes` |
| GET | `/api/admin/notifications` | Admin – list all notifications | `NotificationRoutes` |
| GET | `/api/admin/notifications/stats` | Admin – notification stats | `NotificationRoutes` |

---

## 6. Notifications (SSE / real‑time)

| Method | Endpoint | Description | Java Class / Method |
|--------|----------|-------------|----------------------|
| GET | `/api/events` | Server‑Sent Events stream for real‑time notifications | `SseRoutes` |

---

## 7. Recommendations & Discovery

| Method | Endpoint | Description | Java Class / Method |
|--------|----------|-------------|----------------------|
| GET | `/api/recommendations/feed` | Personalized feed (GNN + hybrid) | `GNNRecommendationRoutes` / `RecommendationRoutes` |
| GET | `/api/recommendations/trending` | Global trending articles | `RecommendationRoutes` |
| GET | `/api/recommendations/trending/category/{category}` | Trending by category | `RecommendationRoutes` |
| GET | `/api/recommendations/similar/{articleId}` | Similar articles (content‑based) | `RecommendationRoutes` |
| GET | `/api/recommendations/users` | Suggested users to follow | `RecommendationRoutes` |
| GET | `/api/recommendations/users/interest/{topic}` | Suggested users by interest | `RecommendationRoutes` |
| GET | `/api/recommendations/hybrid/feed` | Hybrid feed (content + collaborative + popularity) | `RecommendationRoutes` |
| POST | `/api/recommendations/feedback` | Record user feedback (like, click, share, rating) | `RecommendationRoutes` |
| POST | `/api/recommendations/admin/refresh` | Admin – refresh model | `RecommendationRoutes` |
| POST | `/api/recommendations/admin/retrain` | Admin – full retrain | `RecommendationRoutes` |
| GET | `/api/recommendations/admin/stats` | Admin – model stats | `RecommendationRoutes` |

---

## 8. RAG Assistant (Research Assistant)

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

---

## 9. Lab Inventory

| Method | Endpoint | Description | Java Class / Method |
|--------|----------|-------------|----------------------|
| GET | `/api/inventory/chemicals` | List chemicals (filtering, sorting, pagination) | `LabInventoryRoutes` |
| GET | `/api/inventory/chemicals/{id}` | Get single chemical | `LabInventoryRoutes` |
| POST | `/api/inventory/chemicals` | Create chemical | `LabInventoryRoutes` |
| PUT | `/api/inventory/chemicals/{id}` | Full update | `LabInventoryRoutes` |
| PATCH | `/api/inventory/chemicals/{id}` | Partial update | `LabInventoryRoutes` |
| DELETE | `/api/inventory/chemicals/{id}` | Delete chemical | `LabInventoryRoutes` |
| POST | `/api/inventory/chemicals/batch` | Bulk create/update | `LabInventoryRoutes` |
| DELETE | `/api/inventory/chemicals/batch` | Bulk delete | `LabInventoryRoutes` |
| GET | `/api/inventory/locations` | List all unique locations | `LabInventoryRoutes` |
| POST | `/api/inventory/locations` | Add a location | `LabInventoryRoutes` |
| DELETE | `/api/inventory/locations/{name}` | Remove location from all chemicals | `LabInventoryRoutes` |
| GET | `/api/inventory/alerts` | List alerts (with filters) | `LabInventoryRoutes` |
| POST | `/api/inventory/alerts/{id}/acknowledge` | Acknowledge alert | `LabInventoryRoutes` |
| DELETE | `/api/inventory/alerts/{id}` | Delete alert | `LabInventoryRoutes` |
| POST | `/api/inventory/scan` | Scan barcode | `LabInventoryRoutes` |
| GET | `/api/inventory/chemicals/{id}/incompatibilities` | Get incompatible chemicals | `LabInventoryRoutes` |
| POST | `/api/inventory/chemicals/{id}/check-compatibility` | Check compatibility with another chemical | `LabInventoryRoutes` |
| GET | `/api/inventory/stats` | Statistics (total, low stock, expiring, etc.) | `LabInventoryRoutes` |
| GET | `/api/inventory/export/csv` | Export inventory to CSV | `LabInventoryRoutes` |

---

## 10. Peer Review

| Method | Endpoint | Description | Java Class / Method |
|--------|----------|-------------|----------------------|
| GET | `/api/peer-review/submissions` | List open submissions (anonymised) | `PeerReviewRoutes` |
| POST | `/api/peer-review/submit` | Submit a paper (anonymous) | `PeerReviewRoutes` |
| GET | `/api/peer-review/submissions/{id}` | Get submission details | `PeerReviewRoutes` |
| POST | `/api/peer-review/submissions/{id}/claim` | Claim a review | `PeerReviewRoutes` |
| GET | `/api/peer-review/my-assigned` | Submissions assigned to me | `PeerReviewRoutes` |
| POST | `/api/peer-review/submissions/{id}/review` | Submit review (scores, comments) | `PeerReviewRoutes` |
| GET | `/api/peer-review/my-reviews` | Get reviews written by me | `PeerReviewRoutes` |
| GET | `/api/peer-review/my-credentials` | Get reviewer credentials | `PeerReviewRoutes` |
| POST | `/api/peer-review/my-credentials` | Save reviewer credentials | `PeerReviewRoutes` |
| GET | `/api/admin/peer-review/submissions` | Admin – list all submissions | `PeerReviewRoutes` |
| POST | `/api/admin/peer-review/submissions/{id}/assign` | Admin – assign reviewer | `PeerReviewRoutes` |
| DELETE | `/api/admin/peer-review/submissions/{id}` | Admin – delete submission | `PeerReviewRoutes` |
| GET | `/api/peer-review/stats` | Admin – statistics | `PeerReviewRoutes` |

---

## 11. Gap Analysis & Knowledge Graph

| Method | Endpoint | Description | Java Class / Method |
|--------|----------|-------------|----------------------|
| GET | `/api/gap-analysis/nodes` | List all graph nodes | `GapAnalysisRoutes` |
| POST | `/api/gap-analysis/nodes` | Create node | `GapAnalysisRoutes` |
| GET | `/api/gap-analysis/nodes/{id}` | Get node | `GapAnalysisRoutes` |
| PUT | `/api/gap-analysis/nodes/{id}` | Update node | `GapAnalysisRoutes` |
| DELETE | `/api/gap-analysis/nodes/{id}` | Delete node | `GapAnalysisRoutes` |
| GET | `/api/gap-analysis/edges` | List all edges | `GapAnalysisRoutes` |
| POST | `/api/gap-analysis/edges` | Create edge | `GapAnalysisRoutes` |
| GET | `/api/gap-analysis/edges/{id}` | Get edge | `GapAnalysisRoutes` |
| PUT | `/api/gap-analysis/edges/{id}` | Update edge | `GapAnalysisRoutes` |
| DELETE | `/api/gap-analysis/edges/{id}` | Delete edge | `GapAnalysisRoutes` |
| GET | `/api/gap-analysis/nodes/search` | Search nodes by keyword | `GapAnalysisRoutes` |
| GET | `/api/gap-analysis/nodes/type/{type}` | Filter nodes by type | `GapAnalysisRoutes` |
| GET | `/api/gap-analysis/stats` | Graph statistics | `GapAnalysisRoutes` |
| POST | `/api/gap-analysis/analyze` | AI‑powered gap analysis (topic) | `GapAnalysisRoutes` |
| POST | `/api/gap-analysis/generate-hypothesis` | Generate hypothesis for a node | `GapAnalysisRoutes` |
| POST | `/api/gap-analysis/import` | Bulk import (JSON) | `GapAnalysisRoutes` |
| GET | `/api/gap-analysis/export` | Export full graph as JSON | `GapAnalysisRoutes` |

---

## 12. Grant Assistant

| Method | Endpoint | Description | Java Class / Method |
|--------|----------|-------------|----------------------|
| GET | `/api/grants/deadlines` | Upcoming grant deadlines | `GrantRoutes` |
| GET | `/api/grants` | User's grants | `GrantRoutes` |
| POST | `/api/grants` | Add a grant | `GrantRoutes` |
| PUT | `/api/grants/{id}` | Update grant | `GrantRoutes` |
| DELETE | `/api/grants/{id}` | Delete grant | `GrantRoutes` |
| POST | `/api/grants/generate` | Generate draft proposal (AI) | `GrantRoutes` |
| POST | `/api/grants/analyze` | Analyze RFP (AI) | `GrantRoutes` |

---

## 13. Data Hub (Research Objects, Protocols, Preregistrations)

### Research Objects

| Method | Endpoint | Description | Java Class / Method |
|--------|----------|-------------|----------------------|
| GET | `/api/repository/objects` | User's research objects | `DataHubRoutes` |
| GET | `/api/repository/objects/all` | Admin – all objects | `DataHubRoutes` |
| GET | `/api/repository/objects/{id}` | Get object | `DataHubRoutes` |
| POST | `/api/repository/objects` | Create object (multipart) | `DataHubRoutes` |
| PUT | `/api/repository/objects/{id}` | Update object | `DataHubRoutes` |
| DELETE | `/api/repository/objects/{id}` | Delete object | `DataHubRoutes` |
| POST | `/api/repository/objects/{id}/download` | Increment download count | `DataHubRoutes` |

### Protocols

| Method | Endpoint | Description | Java Class / Method |
|--------|----------|-------------|----------------------|
| GET | `/api/protocols` | User's protocols | `DataHubRoutes` |
| GET | `/api/protocols/public` | Public protocols | `DataHubRoutes` |
| GET | `/api/protocols/{id}` | Get protocol | `DataHubRoutes` |
| POST | `/api/protocols` | Create protocol | `DataHubRoutes` |
| PUT | `/api/protocols/{id}` | Update protocol | `DataHubRoutes` |
| DELETE | `/api/protocols/{id}` | Delete protocol | `DataHubRoutes` |
| POST | `/api/protocols/{id}/fork` | Fork protocol | `DataHubRoutes` |
| GET | `/api/protocols/{id}/steps` | List steps | `DataHubRoutes` |
| POST | `/api/protocols/{id}/steps` | Add step | `DataHubRoutes` |
| PUT | `/api/protocols/{id}/steps/{stepId}` | Update step | `DataHubRoutes` |
| DELETE | `/api/protocols/{id}/steps/{stepId}` | Delete step | `DataHubRoutes` |

### Preregistrations

| Method | Endpoint | Description | Java Class / Method |
|--------|----------|-------------|----------------------|
| GET | `/api/preregistrations` | User's preregistrations | `DataHubRoutes` |
| GET | `/api/preregistrations/{id}` | Get preregistration | `DataHubRoutes` |
| POST | `/api/preregistrations` | Create draft | `DataHubRoutes` |
| PUT | `/api/preregistrations/{id}` | Update | `DataHubRoutes` |
| PUT | `/api/preregistrations/{id}/sections/{sectionId}` | Update section content | `DataHubRoutes` |
| POST | `/api/preregistrations/{id}/submit` | Submit for timestamping (DOI) | `DataHubRoutes` |
| DELETE | `/api/preregistrations/{id}` | Delete | `DataHubRoutes` |

---

## 14. Projects (Kanban, Members, Outputs)

| Method | Endpoint | Description | Java Class / Method |
|--------|----------|-------------|----------------------|
| GET | `/api/projects` | User's projects (owned + member) | `ProjectRoutes` |
| POST | `/api/projects` | Create project | `ProjectRoutes` |
| GET | `/api/projects/{id}` | Get project | `ProjectRoutes` |
| PUT | `/api/projects/{id}` | Update project | `ProjectRoutes` |
| DELETE | `/api/projects/{id}` | Delete project | `ProjectRoutes` |
| GET | `/api/projects/{id}/members` | List members with roles | `ProjectRoutes` |
| POST | `/api/projects/{id}/members` | Add member | `ProjectRoutes` |
| PUT | `/api/projects/{id}/members/{userId}` | Update member role | `ProjectRoutes` |
| DELETE | `/api/projects/{id}/members/{userId}` | Remove member | `ProjectRoutes` |
| GET | `/api/projects/{id}/tasks` | List tasks (kanban) | `ProjectRoutes` |
| POST | `/api/projects/{id}/tasks` | Create task | `ProjectRoutes` |
| GET | `/api/projects/{projectId}/tasks/{taskId}` | Get task | `ProjectRoutes` |
| PUT | `/api/projects/{projectId}/tasks/{taskId}` | Update task | `ProjectRoutes` |
| PATCH | `/api/projects/{projectId}/tasks/{taskId}/move` | Move task to another column | `ProjectRoutes` |
| DELETE | `/api/projects/{projectId}/tasks/{taskId}` | Delete task | `ProjectRoutes` |
| GET | `/api/projects/{id}/outputs` | List outputs | `ProjectRoutes` |
| POST | `/api/projects/{id}/outputs` | Add output | `ProjectRoutes` |
| DELETE | `/api/projects/{id}/outputs/{outputId}` | Delete output | `ProjectRoutes` |
| GET | `/api/projects/search` | Search projects | `ProjectRoutes` |
| GET | `/api/projects/{id}/activity` | Activity log (stub) | `ProjectRoutes` |
| POST | `/api/projects/{id}/invite` | Invite user by email | `ProjectRoutes` |

---

## 15. Events

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

---

## 16. Voice Assistant Settings

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

---

## 17. Workspace (SmartGlass)

| Method | Endpoint | Description | Java Class / Method |
|--------|----------|-------------|----------------------|
| GET | `/api/workspace/panels` | Get user's panels | `WorkspaceRoutes` |
| GET | `/api/workspace/panels/{id}` | Get panel | `WorkspaceRoutes` |
| POST | `/api/workspace/panels` | Create panel | `WorkspaceRoutes` |
| PUT | `/api/workspace/panels/{id}` | Update panel | `WorkspaceRoutes` |
| PATCH | `/api/workspace/panels/{id}` | Partial update (name only) | `WorkspaceRoutes` |
| DELETE | `/api/workspace/panels/{id}` | Delete panel | `WorkspaceRoutes` |
| POST | `/api/workspace/panels/{id}/duplicate` | Duplicate panel | `WorkspaceRoutes` |
| POST | `/api/workspace/panels/reorder` | Reorder panels | `WorkspaceRoutes` |
| GET | `/api/workspace/panels/export` | Export workspace as JSON | `WorkspaceRoutes` |
| POST | `/api/workspace/panels/import` | Import workspace from JSON | `WorkspaceRoutes` |
| DELETE | `/api/workspace/panels/all` | Clear all panels | `WorkspaceRoutes` |
| GET | `/api/workspace/presets` | List built‑in presets | `WorkspaceRoutes` |
| POST | `/api/workspace/presets/{presetId}/apply` | Apply preset | `WorkspaceRoutes` |
| POST | `/api/workspace/panels/{id}/share` | Create shareable link | `WorkspaceRoutes` |
| GET | `/api/workspace/share/{token}` | View shared panel (no auth) | `WorkspaceRoutes` |
| GET | `/api/workspace/active` | Get active panel | `WorkspaceRoutes` |
| POST | `/api/workspace/active/{id}` | Set active panel | `WorkspaceRoutes` |

---

## 18. Admin (system management)

| Method | Endpoint | Description | Java Class / Method |
|--------|----------|-------------|----------------------|
| GET | `/api/admin/stats` | Platform statistics | `AdminController` / `AdminRoutes` |
| GET | `/api/admin/users` | List all users | `AdminController` / `AdminRoutes` |
| DELETE | `/api/admin/users/{id}` | Delete user | `AdminController` |
| GET | `/api/admin/articles` | List all articles | `AdminController` |
| DELETE | `/api/admin/articles/{id}` | Delete article (admin) | `AdminController` |
| DELETE | `/api/admin/articles` | Clear all articles | `AdminController` |
| GET | `/api/admin/activity` | Recent activity feed | `AdminRoutes` |
| GET | `/api/admin/search` | Global search across entities | `AdminRoutes` |
| POST | `/api/admin/2fa/status` | 2FA usage statistics | `AdminRoutes` |
| GET | `/api/admin/workspace/panels` | List workspace presets | `AdminRoutes` |
| GET | `/api/admin/rag/documents` | List all indexed RAG documents | `AdminRoutes` |

---

## 19. Analytics (global & per user)

| Method | Endpoint | Description | Java Class / Method |
|--------|----------|-------------|----------------------|
| GET | `/api/users/me/analytics/views` | User's views over time | `AnalyticsRoutes` |
| GET | `/api/users/me/analytics/top-articles` | User's top performing articles | `AnalyticsRoutes` |
| GET | `/api/users/me/analytics/export/csv` | Export user analytics as CSV | `AnalyticsRoutes` |
| GET | `/api/admin/stats/activity` | Platform activity over time | `AnalyticsRoutes` |
| GET | `/api/admin/stats/top-contributors` | Top contributors | `AnalyticsRoutes` |
| GET | `/api/articles/{id}/analytics/views-daily` | Daily views for an article | `AnalyticsRoutes` |
| GET | `/api/articles/{id}/analytics/referrers` | Referral sources for article | `AnalyticsRoutes` |
| GET | `/api/articles/{id}/analytics/demographics` | Reader demographics | `AnalyticsRoutes` |
| GET | `/api/articles/{id}/analytics/citations` | Citation metrics | `AnalyticsRoutes` |
| GET | `/api/articles/{id}/analytics/export/csv` | Export article analytics as CSV | `AnalyticsRoutes` |
| POST | `/api/articles/{id}/analytics/alert` | Set view threshold alert | `AnalyticsRoutes` |
| GET | `/api/users/me/analytics/alerts` | Get active alerts | `AnalyticsRoutes` |
| DELETE | `/api/users/me/analytics/alerts/{id}` | Delete alert | `AnalyticsRoutes` |
| GET | `/api/trending` | Global trending articles | `AnalyticsRoutes` |
| GET | `/api/popular-tags` | Popular tags (with counts) | `AnalyticsRoutes` |

---

## 20. Tags

| Method | Endpoint | Description | Java Class / Method |
|--------|----------|-------------|----------------------|
| GET | `/api/tags` | List all tags | `TagController` |

---

## 21. GenUI (Generative UI)

| Method | Endpoint | Description | Java Class / Method |
|--------|----------|-------------|----------------------|
| ... | (The frontend uses `genui-registry.ts` to lazy‑load components, no dedicated backend endpoints) | | |

---

## 22. Utilities & Health

| Method | Endpoint | Description | Java Class / Method |
|--------|----------|-------------|----------------------|
| GET | `/api/health` | Health check (returns status & uptime) | `AdminRoutes` (and `AuthRoutes`) |
| GET | `/api/me` | Current user username | `AuthRoutes` |

---

## WebSocket Endpoints

| Path | Purpose | Java Component |
|------|---------|----------------|
| `ws://localhost:8080/ws` | Main WebSocket for messaging, typing, presence, notifications | `WebSocketManager` |
| `ws://localhost:9093` | Collaboration (Yjs) WebSocket for real‑time document editing | (Separate server) |

---

## Static File Serving

- **Base directory:** `/src/main/resources/Templates/`
- **SPA fallback:** Serves `index.html` for non‑API routes.
- **Compression:** Brotli / Gzip (pre‑compressed files or on‑the‑fly)
- **Caching:** Strong ETags, cache headers for assets, range requests supported.

---

# **How to Run the Full Stack**

1. **Backend** (Java Spring Boot / custom router)
   - Ensure all services (UserService, ArticleService, MessageService, etc.) are implemented.
   - Start the main server (e.g., `Main` class) – it will listen on port `8080` (or configured).
   - Start the Yjs WebSocket server (separate process) on port `9093` for collaboration.

2. **Frontend** (React + Vite)
   - Set environment variables in `.env`:
     ```
     VITE_API_BASE_URL=http://localhost:8080/api
     VITE_WS_URL=ws://localhost:8080/ws
     VITE_COLLAB_WS_URL=ws://localhost:9093
     ```
   - Run `pnpm dev` (or `npm run dev`)

3. **Database**
   - The backend uses in‑memory storage (see `UserRepository`, `ArticleRepository`, etc.) – you should replace with a real database (MySQL, PostgreSQL) for production.