# researchhub/researchhub-web architecture

> Architecture diagram of the GitHub repository researchhub/researchhub-web, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/researchhub/researchhub-web
- Repository: https://github.com/researchhub/researchhub-web

## Overview

1. **Overall shape**
   - This is a **Next.js frontend application** for ResearchHub, not just a site of pages. The repo is organized around **route-level pages**, **domain-specific component subsystems**, and a shared **client-side state/config layer**.
   - The README confirms it depends on the separate **researchhub-backend** app to run, so most business data comes from backend APIs rather than local persistence.

2. **Routing and app shell**
   - `pages/` defines the top-level application routes: home, paper/post/question detail pages, author profiles, hubs, search, leaderboards, moderation dashboards, onboarding, checkout, login, and product areas like reference manager.
   - `_app.js`, `_document.js`, `_error.js`, and `pages/Base.js` provide the global shell, shared layout, error handling, and app-wide providers.

3. **Domain-oriented component architecture**
   - `components/` is split into large feature domains such as **Paper**, **Comment**, **Document**, **Author**, **Hubs**, **ReferenceManager**, **Bounty**, **LiveFeed**, **Moderator**, **Notebook**, and **UnifiedDocFeed**.
   - Each domain usually contains its own UI widgets, utility code, local API helpers, and sometimes local types/constants. This suggests a **vertical-slice architecture** where each feature owns its UI and interaction logic.

4. **Core content model: documents and publications**
   - The most central subsystem is the **document/publication workflow**: `components/Document`, `components/Paper`, `components/DocumentViewer`, and related `pages/paper/[documentId]` and `pages/post/[documentId]`.
   - These modules cover fetching paper/post metadata, rendering the document viewer, voting, editing metadata, upload flows, PDF viewing, open graph data, and paper version creation/publishing. This is the main content lifecycle for the app.

5. **Discussion and annotation layer**
   - `components/Comment`, `components/InlineCommentDisplay`, `components/PaperDraftInlineComment`, and `components/Comment/modules/annotation` form the discussion subsystem.
   - It supports threaded comments, inline annotations, selection-based commenting, review categories, privacy controls, Quill/Tiptap rendering, and sharable links to comment positions. This is a distinct layer that overlays discussion on top of documents and drafts.

6. **Identity, authors, and reputation**
   - `components/Author`, `components/Verification`, `components/AuthorClaimModal`, `components/AuthorClaimCaseDashboard`, `components/Publication`, and `components/ResearchCoin` handle identity and author-related workflows.
   - These modules cover profile pages, publication claims, identity verification, reputation displays, author expertise/institutions, reward claiming, and author claim moderation. They are tightly coupled to user-generated scholarly identity rather than generic user profiles.

7. **Community discovery and feed surfaces**
   - `components/Home`, `components/Feed`, `components/UnifiedDocFeed`, `components/ForYouFeed`, `components/LiveFeed`, `components/Search`, `components/SearchV2`, and `components/Leaderboard` represent discovery and engagement surfaces.
   - These features aggregate content from multiple document types and user actions into feeds, search results, live updates, and ranked views. The unified feed layer is especially important because it normalizes different content types into one browsing model.

8. **Hubs, organizations, and topical governance**
   - `components/Hubs`, `components/HubLeaderDashboard`, `components/PermissionsDashboard`, `components/Org`, and `components/Onboard` support topical communities and organization-level access.
   - Hubs appear to be the main taxonomy for scientific topics and moderation scope. Permissions and hub editor management imply a multi-role governance model, with dashboards for leaders, editors, and administrators.

9. **Reference Manager as a product boundary**
   - `components/ReferenceManager` and `pages/reference-manager` form a substantial product area inside the app.
   - It includes reference ingestion, DOI/URL lookup, project organization, collaborator management, bibliography export, onboarding, and manual upload drawers. Architecturally, this is a semi-isolated workspace with its own sub-routes, local contexts, and API layer.

10. **Client state and shared infrastructure**
   - Global state is split between **Redux** (`redux/`) and **React context/hooks** (`components/contexts`, `config/hooks`).
   - Redux slices cover areas like auth, paper, discussion, vote, permission, banners, notifications, flags, and transactions. Contexts handle cross-cutting concerns such as navigation, organization, exchange rates, saved citations, and reference manager settings. This indicates a mixed state model: persistent app state in Redux, localized feature state in context/hooks.

11. **API and integration boundaries**
   - Many feature folders include local `api/` modules, and `config/api`, `config/fetch`, and `config/utils/buildApiUri.ts` centralize request construction.
   - The repo integrates with several external services or backend capabilities where they materially affect architecture: **authentication** (`config/auth`, Google login, Orcid login/connect), **Stripe** checkout, **Ethereum/ResearchCoin** wallet-related flows, **Sentry** monitoring, and likely **S3-backed document/post fetches** from document APIs.
   - There is also a `pages/api/` area for small Next.js server routes like revalidation and robots.

12. **Shared UI and utility layer**
   - `components/shared`, `components/Form`, `components/Modals`, `components/Tooltips`, `components/Icons`, `components/Placeholders`, `static/`, and `public/` provide reusable UI primitives, modal infrastructure, placeholder skeletons, and assets.
   - `config/themes`, `config/constants`, `config/types`, and `config/utils` provide the common design system, domain types, URL parsing, formatting, validation, and environment helpers used across features.

13. **Operational and delivery concerns**
   - The repo includes build-time and workflow tooling: `next.config.js`, ESLint/Prettier, Husky hooks, sitemap generation scripts, and GitHub Actions.
   - `tests/cypress` provides end-to-end coverage for auth, home, hub, paper, search, and routing, which suggests the app’s primary architectural contracts are at the page and user-flow level rather than isolated library APIs.

Main entry points: [`pages`](https://github.com/researchhub/researchhub-web/tree/master/pages) (Route pages), [`components/Document`](https://github.com/researchhub/researchhub-web/tree/master/components/Document) (Documents), [`components/Author`](https://github.com/researchhub/researchhub-web/tree/master/components/Author) (Authors), [`config`](https://github.com/researchhub/researchhub-web/tree/master/config) (API config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_routes["Routes"]
  node_pages_app_shell["App shell<br/>Next.js shell<br/>[_app.js]"]
  node_pages_route_map["Route pages<br/>Next.js routes"]
  node_pages_api["API routes<br/>Next.js API"]
end

subgraph group_content["Content"]
  node_document_system["Documents<br/>content workflow"]
  node_paper_system["Paper UI<br/>paper surface"]
  node_comment_system["Comments<br/>discussion layer"]
  node_inline_comment["Inline comments<br/>annotation overlay"]
  node_draft_comment["Draft annotations<br/>draft overlay"]
end

subgraph group_discovery["Discovery"]
  node_feed_surface["Feeds<br/>discovery surface"]
  node_search_surface["Search"]
  node_ranking_surface["Leaderboards<br/>ranked views"]
end

subgraph group_identity["Identity"]
  node_author_system["Authors<br/>identity layer"]
  node_claim_workflow["Claiming<br/>identity workflow"]
  node_verification_system["Verification"]
end

subgraph group_governance["Governance"]
  node_hub_system["Hubs<br/>topic communities"]
  node_governance_dashboards["Governance<br/>moderation/admin"]
  node_live_moderation["Live moderation<br/>flag review"]
end

subgraph group_refmgr["Reference Manager"]
  node_reference_manager["Reference manager<br/>workspace"]
end

subgraph group_shared["Shared Infra"]
  node_global_state["State layer<br/>redux+context"]
  node_api_config["API config<br/>request boundary"]
  node_shared_ui["Shared UI<br/>design system"]
end

node_pages_app_shell -->|"providers"| node_global_state
node_pages_route_map -->|"renders"| node_document_system
node_pages_route_map -->|"renders"| node_feed_surface
node_pages_route_map -->|"renders"| node_search_surface
node_pages_route_map -->|"renders"| node_author_system
node_pages_route_map -->|"renders"| node_hub_system
node_pages_route_map -->|"renders"| node_reference_manager
node_pages_api -->|"serves"| node_api_config
node_document_system -->|"hosts"| node_comment_system
node_document_system -->|"specializes"| node_paper_system
node_comment_system -->|"overlays"| node_inline_comment
node_comment_system -->|"extends"| node_draft_comment
node_feed_surface -->|"aggregates"| node_document_system
node_search_surface -->|"searches"| node_hub_system
node_search_surface -->|"searches"| node_author_system
node_author_system -->|"includes"| node_claim_workflow
node_author_system -->|"depends on"| node_verification_system
node_hub_system -->|"governed by"| node_governance_dashboards
node_governance_dashboards -->|"feeds"| node_live_moderation
node_reference_manager -->|"integrates"| node_api_config
node_reference_manager -->|"builds on"| node_shared_ui
node_global_state -->|"orchestrates"| node_api_config
node_shared_ui -->|"uses"| node_api_config

click node_pages_app_shell "https://github.com/researchhub/researchhub-web/blob/master/pages/_app.js"
click node_pages_route_map "https://github.com/researchhub/researchhub-web/tree/master/pages"
click node_pages_api "https://github.com/researchhub/researchhub-web/tree/master/pages/api"
click node_document_system "https://github.com/researchhub/researchhub-web/tree/master/components/Document"
click node_paper_system "https://github.com/researchhub/researchhub-web/tree/master/components/Paper"
click node_comment_system "https://github.com/researchhub/researchhub-web/tree/master/components/Comment"
click node_inline_comment "https://github.com/researchhub/researchhub-web/tree/master/components/InlineCommentDisplay"
click node_draft_comment "https://github.com/researchhub/researchhub-web/tree/master/components/PaperDraftInlineComment"
click node_feed_surface "https://github.com/researchhub/researchhub-web/tree/master/components/UnifiedDocFeed"
click node_search_surface "https://github.com/researchhub/researchhub-web/tree/master/components/Search"
click node_ranking_surface "https://github.com/researchhub/researchhub-web/tree/master/components/Leaderboard"
click node_author_system "https://github.com/researchhub/researchhub-web/tree/master/components/Author"
click node_claim_workflow "https://github.com/researchhub/researchhub-web/tree/master/components/AuthorClaimCaseDashboard"
click node_verification_system "https://github.com/researchhub/researchhub-web/tree/master/components/Verification"
click node_hub_system "https://github.com/researchhub/researchhub-web/tree/master/components/Hubs"
click node_governance_dashboards "https://github.com/researchhub/researchhub-web/tree/master/components/PermissionsDashboard"
click node_live_moderation "https://github.com/researchhub/researchhub-web/tree/master/components/LiveFeed"
click node_reference_manager "https://github.com/researchhub/researchhub-web/tree/master/components/ReferenceManager"
click node_global_state "https://github.com/researchhub/researchhub-web/tree/master/redux"
click node_api_config "https://github.com/researchhub/researchhub-web/tree/master/config"
click node_shared_ui "https://github.com/researchhub/researchhub-web/tree/master/components/shared"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_pages_app_shell,node_pages_route_map,node_pages_api,node_global_state,node_api_config,node_shared_ui toneBlue
class node_document_system,node_paper_system,node_comment_system,node_inline_comment,node_draft_comment toneAmber
class node_feed_surface,node_search_surface,node_ranking_surface toneMint
class node_author_system,node_claim_workflow,node_verification_system toneRose
class node_hub_system,node_governance_dashboards,node_live_moderation toneIndigo
class node_reference_manager toneTeal
```

## Components

### Routes

Next.js pages and top-level route entrypoints

- [App shell](https://github.com/researchhub/researchhub-web/blob/master/pages/_app.js): Next.js shell · Global app wrapper, document, error handling, and base providers. · `pages/_app.js`
- [Route pages](https://github.com/researchhub/researchhub-web/tree/master/pages): Next.js routes · Primary route tree for papers, posts, questions, authors, hubs, search, moderation, onboarding, checkout, and account flows. · `pages`
- [API routes](https://github.com/researchhub/researchhub-web/tree/master/pages/api): Next.js API · Small server-side routes such as revalidation and robots. · `pages/api`

### Content

Document, paper, post, and discussion workflows

- [Documents](https://github.com/researchhub/researchhub-web/tree/master/components/Document): content workflow · Core paper/post/question document lifecycle, viewer, metadata, voting, upload, and version publishing. · `components/Document`
- [Paper UI](https://github.com/researchhub/researchhub-web/tree/master/components/Paper): paper surface · Paper-specific presentation, side columns, tabs, summaries, uploads, and abstract editing. · `components/Paper`
- [Comments](https://github.com/researchhub/researchhub-web/tree/master/components/Comment): discussion layer · Threaded comments, inline annotation overlays, review categories, and rich-text composition. · `components/Comment`
- [Inline comments](https://github.com/researchhub/researchhub-web/tree/master/components/InlineCommentDisplay): annotation overlay · Selection-based comment threads and annotation positioning on top of content. · `components/InlineCommentDisplay`
- [Draft annotations](https://github.com/researchhub/researchhub-web/tree/master/components/PaperDraftInlineComment): draft overlay · Draft-time inline annotation tools for paper editing and manuscript review. · `components/PaperDraftInlineComment`

### Discovery

Feeds, search, rankings, and home surfaces

- [Feeds](https://github.com/researchhub/researchhub-web/tree/master/components/UnifiedDocFeed): discovery surface · Home feed, author feed, live feed, and unified document feed surfaces. · `components/UnifiedDocFeed`
- [Search](https://github.com/researchhub/researchhub-web/tree/master/components/Search): search UI · Search across documents, people, and hubs with filters and autosuggest. · `components/Search`
- [Leaderboards](https://github.com/researchhub/researchhub-web/tree/master/components/Leaderboard): ranked views · Leaderboard and top-rated discovery pages. · `components/Leaderboard`

### Identity

Authors, verification, reputation, and claims

- [Authors](https://github.com/researchhub/researchhub-web/tree/master/components/Author): identity layer · Author profiles, publications, expertise, reputation, and claim flows. · `components/Author`
- [Claiming](https://github.com/researchhub/researchhub-web/tree/master/components/AuthorClaimCaseDashboard): identity workflow · Author claim modal, validation, and claim case moderation dashboard. · `components/AuthorClaimCaseDashboard`
- [Verification](https://github.com/researchhub/researchhub-web/tree/master/components/Verification): identity verification · Identity and publication verification flows, badges, and connect steps. · `components/Verification`

### Governance

Hubs, permissions, moderation, and org controls

- [Hubs](https://github.com/researchhub/researchhub-web/tree/master/components/Hubs): topic communities · Topic hubs, hub pages, selectors, and hub discovery cards. · `components/Hubs`
- [Governance](https://github.com/researchhub/researchhub-web/tree/master/components/PermissionsDashboard): moderation/admin · Leader, editor, permission, moderator, and org management dashboards. · `components/PermissionsDashboard`
- [Live moderation](https://github.com/researchhub/researchhub-web/tree/master/components/LiveFeed): flag review · Live feed review and content removal workflows for flagged content. · `components/LiveFeed`

### Reference Manager

Standalone reference management workspace

- [Reference manager](https://github.com/researchhub/researchhub-web/tree/master/components/ReferenceManager): workspace · Standalone reference management product area with projects, onboarding, citation tables, imports, and uploads. · `components/ReferenceManager`

### Shared Infra

App shell, state, APIs, config, and reusable UI

- [State layer](https://github.com/researchhub/researchhub-web/tree/master/redux): redux+context · App-wide Redux slices and React contexts for auth, papers, discussion, permissions, notifications, navigation, and settings. · `redux`
- [API config](https://github.com/researchhub/researchhub-web/tree/master/config): request boundary · Shared fetch helpers, auth, URI builders, gatekeepers, Stripe, and integration wiring. · `config`
- [Shared UI](https://github.com/researchhub/researchhub-web/tree/master/components/shared): design system · Reusable form controls, modals, banners, tooltips, icons, placeholders, and shared components. · `components/shared`

## Connections

- App shell → State layer: providers · App shell installs shared app state and cross-cutting providers.
- Route pages → Documents: renders · Routes delegate to document and paper workflows for main scholarly content.
- Route pages → Feeds: renders · Home and feed routes surface aggregated content streams.
- Route pages → Search: renders · Search routes use the search subsystem.
- Route pages → Authors: renders · Author route pages are backed by the author identity subsystem.
- Route pages → Hubs: renders · Hub routes map to topical community views.
- Route pages → Reference manager: renders · Reference manager routes expose the workspace product boundary.
- API routes → API config: serves · Server-side routes reuse shared API and request helpers.
- Documents → Comments: hosts · Documents provide the primary surface for threaded discussion.
- Documents → Paper UI: specializes · Paper UI extends the document workflow for publication-specific views and actions.
- Comments → Inline comments: overlays · Inline comments are layered on top of documents and drafts.
- Comments → Draft annotations: extends · Draft annotations reuse the discussion model during editing.
- Feeds → Documents: aggregates · Feeds normalize papers, posts, and contributions into browsable cards.
- Search → Hubs: searches · Search can target topical hubs as a first-class result type.
- Search → Authors: searches · Search can surface people and author profiles.
- Authors → Claiming: includes · Author identity includes claim and moderation workflows.
- Authors → Verification: depends on · Profiles and claims depend on identity verification flows.
- Hubs → Governance: governed by · Hub membership, editors, and permissions are managed through dashboards.
- Governance → Live moderation: feeds · Admin and moderation dashboards consume live flag/review streams.
- Reference manager → API config: integrates · Reference manager depends on shared API construction and auth boundaries.
- Reference manager → Shared UI: builds on · The workspace is assembled from shared UI primitives and layout components.
- State layer → API config: orchestrates · State actions and hooks are driven by shared request and auth utilities.
- Shared UI → API config: uses · Reusable UI components rely on common request, formatting, and environment helpers.