How researchhub/researchhub-web works
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 Route pages · Document Documents · Author Authors · config API config
Components 21
Routes
Next.js pages and top-level route entrypoints
- App shell · Global app wrapper, document, error handling, and base providers.
pages/_app.js - Route pages · Primary route tree for papers, posts, questions, authors, hubs, search, moderation, onboarding, checkout, and account flows.
pages - API routes · Small server-side routes such as revalidation and robots.
pages/api
Content
Document, paper, post, and discussion workflows
- Documents · Core paper/post/question document lifecycle, viewer, metadata, voting, upload, and version publishing.
components/Document - Paper UI · Paper-specific presentation, side columns, tabs, summaries, uploads, and abstract editing.
components/Paper - Comments · Threaded comments, inline annotation overlays, review categories, and rich-text composition.
components/Comment - Inline comments · Selection-based comment threads and annotation positioning on top of content.
components/InlineCommentDisplay - Draft annotations · Draft-time inline annotation tools for paper editing and manuscript review.
components/PaperDraftInlineComment
Discovery
Feeds, search, rankings, and home surfaces
- Feeds · Home feed, author feed, live feed, and unified document feed surfaces.
components/UnifiedDocFeed - Search · Search across documents, people, and hubs with filters and autosuggest.
components/Search - Leaderboards · Leaderboard and top-rated discovery pages.
components/Leaderboard
Identity
Authors, verification, reputation, and claims
- Authors · Author profiles, publications, expertise, reputation, and claim flows.
components/Author - Claiming · Author claim modal, validation, and claim case moderation dashboard.
components/AuthorClaimCaseDashboard - Verification · Identity and publication verification flows, badges, and connect steps.
components/Verification
Governance
Hubs, permissions, moderation, and org controls
- Hubs · Topic hubs, hub pages, selectors, and hub discovery cards.
components/Hubs - Governance · Leader, editor, permission, moderator, and org management dashboards.
components/PermissionsDashboard - Live moderation · Live feed review and content removal workflows for flagged content.
components/LiveFeed
Reference Manager
Standalone reference management workspace
- Reference manager · 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 · App-wide Redux slices and React contexts for auth, papers, discussion, permissions, notifications, navigation, and settings.
redux - API config · Shared fetch helpers, auth, URI builders, gatekeepers, Stripe, and integration wiring.
config - Shared UI · Reusable form controls, modals, banners, tooltips, icons, placeholders, and shared components.
components/shared
Connections 23
- 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.