# researchhub/web architecture

> Architecture diagram of the GitHub repository 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/web
- Repository: https://github.com/researchhub/web

## Overview

1. This is a Next.js App Router web application for ResearchHub. The `app/` tree defines the route structure, while `components/`, `hooks/`, `services/`, `contexts/`, `store/`, and `types/` form the reusable application layer underneath it.

2. The top-level architecture is route-driven. Most user-facing features live under `app/` as page-level entry points, with nested layouts for major areas such as feed, funding, papers, posts, proposals, expert finder, notebook, moderators, journal, profile/settings, and informational pages like about, privacy, and TOS.

3. The app is organized around several large product domains rather than a single generic UI. The biggest clusters are:
   - content discovery and feeds,
   - publishing/reviewing of works,
   - funding/grants/proposals/bounties,
   - author/profile and social features,
   - notebook and editor workflows,
   - expert-finder and outreach workflows,
   - moderation/admin tooling,
   - ResearchCoin / wallet / staking flows.

4. `components/` is the main shared feature layer. It contains domain-specific UI slices such as `Feed`, `Funding`, `Work`, `Comment`, `Notebook`, `ResearchCoin`, `Moderators`, `Referral`, `Journal`, `Leaderboard`, and `Profile`, plus a large reusable `ui/` component library. Most page routes are thin wrappers around these component modules.

5. Data access is centralized in `services/`. These files act as API clients and service façades for backend capabilities such as auth, users, feed, grants, papers, comments, moderation, search, notifications, payments, wallets, referrals, expert finder, and web sockets. This is the main boundary between UI code and server-side/business APIs.

6. There are two distinct backend integration styles:
   - an Apollo/GraphQL path via `lib/apollo-client.ts` and `lib/graphql/*`,
   - service-oriented API calls via `services/*.service.ts` and `services/client.ts`.
   This suggests the frontend consumes both GraphQL and REST-like endpoints depending on the domain.

7. State and session behavior are split across several layers. `contexts/` holds cross-app UI and user state such as auth modal state, navigation, feed tabs, organization selection, notifications, sidebar, sharing, referral, verification, and wallet-related context. `store/` contains a smaller set of persistent client stores such as grant and hub state. Feature hooks in `hooks/` encapsulate fetching, filtering, tracking, and interaction logic.

8. The editor and notebook subsystems are especially self-contained. `components/Editor/` contains a rich block editor with extensions, menus, panels, hooks, and CSS. `app/notebook/` and `components/Notebook/` build on that editor to support note creation, collaboration, conversion, publishing forms, and organization-scoped notebooks. There are dedicated notebook API routes under `app/notebook/api/` for AI, collaboration, and conversion.

9. Content/workflow pages follow a common pattern: a route page loads a feature-specific container, which composes work header, right sidebar, tabs, reviews, bounties, discussion, and version/history sections. This pattern appears across papers, posts, proposals, questions, grants, and fundraise-related pages, showing a shared “work document” model with type-specific presentation.

10. Authentication and user identity are first-class platform concerns. The app uses NextAuth under `app/api/auth/[...nextauth]`, plus dedicated sign-in/error/reset/verify pages. Additional identity integrations exist for ORCID, MFA, and verification flows, and these are surfaced through modal and settings components.

11. Real-time and asynchronous interactions are supported through dedicated infrastructure hooks and services. `services/websocket.service.ts` and `hooks/useWebSocket.ts` indicate socket-based updates, while separate hooks manage feed impressions, comment state, notifications, auto-payments, staking yield, and search progress. This means many UI sections are reactive to server-pushed or polling-based updates.

12. The repo also contains a broad “platform chrome” layer in `app/layouts/` and `components/layouts`-style modules. These handle page shell concerns such as top bar, sidebars, mobile navigation, banners, breadcrumbs, right-side panels, and layout state. This boundary keeps shared navigation and responsive behavior separate from each feature page.

13. Cross-cutting concerns are implemented as providers and utilities. `components/providers/` wraps analytics, APM, NextAuth, Apollo, and toasts; `utils/` and `lib/` provide formatting, dates, URLs, search history, validation, structured data, metadata, and content conversions. These modules support the app without owning business workflows.

14. The repository includes route-level and feature-level API endpoints under `app/api/`, plus a few specialized routes elsewhere, such as referral application and moderation routes. These endpoints support browser-side flows like auth callbacks, link previews, OG image generation, notebook collaboration, and referral handling.

15. Operationally, this is a modern TypeScript frontend with Next.js, ESLint, Prettier, Tailwind, and Husky pre-commit hooks. The architecture is designed for a large product surface area where page routes stay thin, feature components own presentation, hooks own client behavior, and `services/` own backend communication.

Main entry points: [`services`](https://github.com/researchhub/web/tree/main/services) (Services), [`app`](https://github.com/researchhub/web/tree/main/app) (Routes), [`hooks`](https://github.com/researchhub/web/tree/main/hooks) (Hooks), [`components/ui`](https://github.com/researchhub/web/tree/main/components/ui) (Shared UI Kit)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App Router"]
  node_app_root["Routes<br/>nextjs app router"]
  node_app_feed["Feed<br/>route cluster"]
  node_app_work["Works<br/>route cluster"]
  node_app_funding["Funding<br/>route cluster"]
  node_app_expert["Expert Finder<br/>route cluster"]
  node_app_notebook["Notebook<br/>route cluster"]
  node_app_moderation["Moderation<br/>route cluster"]
  node_app_identity["Identity<br/>auth & profile routes"]
end

subgraph group_components["Shared UI"]
  node_components_work["Work UI<br/>document views"]
  node_components_feed["Feed UI<br/>feed components"]
  node_components_funding["Funding UI<br/>funding components"]
  node_components_editor_notebook["Editor & Notebook<br/>editor stack"]
  node_components_shared["Shared UI Kit<br/>design system"]
end

subgraph group_data["Data Layer"]
  node_services_api["Services<br/>api façades"]
  node_services_graphql["GraphQL<br/>apollo path<br/>[apollo-client.ts]"]
end

subgraph group_state["Client State"]
  node_state_hooks["Hooks"]
  node_state_contexts["Contexts<br/>app state"]
  node_state_store["Stores"]
end

subgraph group_platform["Platform"]
  node_platform_providers["Providers"]
  node_platform_lib["Lib & Utils<br/>shared helpers"]
end

node_app_root -->|"renders"| node_components_shared
node_app_root -->|"calls"| node_services_api
node_app_root -->|"uses"| node_state_hooks
node_app_root -->|"reads"| node_state_contexts
node_app_feed -->|"builds with"| node_components_feed
node_app_work -->|"builds with"| node_components_work
node_app_funding -->|"builds with"| node_components_funding
node_app_expert -->|"composes"| node_components_shared
node_app_notebook -->|"builds with"| node_components_editor_notebook
node_app_moderation -->|"composes"| node_components_shared
node_app_identity -->|"uses"| node_components_shared
node_components_work -->|"loads"| node_services_api
node_components_feed -->|"loads"| node_services_api
node_components_funding -->|"loads"| node_services_api
node_components_editor_notebook -->|"syncs"| node_services_api
node_services_api -->|"uses"| node_services_graphql
node_services_api -->|"depends on"| node_platform_lib
node_state_hooks -->|"wraps"| node_services_api
node_state_hooks -->|"coordinates"| node_state_contexts
node_state_store -->|"consumed by"| node_state_hooks
node_platform_providers -->|"provides"| node_services_graphql
node_platform_providers -->|"wraps"| node_state_contexts
node_app_root -->|"wraps"| node_platform_providers

click node_app_root "https://github.com/researchhub/web/tree/main/app"
click node_app_feed "https://github.com/researchhub/web/tree/main/app/(feed)"
click node_app_work "https://github.com/researchhub/web/tree/main/app/paper"
click node_app_funding "https://github.com/researchhub/web/tree/main/app/fund"
click node_app_expert "https://github.com/researchhub/web/tree/main/app/expert-finder"
click node_app_notebook "https://github.com/researchhub/web/tree/main/app/notebook"
click node_app_moderation "https://github.com/researchhub/web/tree/main/app/moderators"
click node_app_identity "https://github.com/researchhub/web/tree/main/app/auth"
click node_components_work "https://github.com/researchhub/web/tree/main/components/work"
click node_components_feed "https://github.com/researchhub/web/tree/main/components/Feed"
click node_components_funding "https://github.com/researchhub/web/tree/main/components/Funding"
click node_components_editor_notebook "https://github.com/researchhub/web/tree/main/components/Editor"
click node_components_shared "https://github.com/researchhub/web/tree/main/components/ui"
click node_services_api "https://github.com/researchhub/web/tree/main/services"
click node_services_graphql "https://github.com/researchhub/web/blob/main/lib/apollo-client.ts"
click node_state_hooks "https://github.com/researchhub/web/tree/main/hooks"
click node_state_contexts "https://github.com/researchhub/web/tree/main/contexts"
click node_state_store "https://github.com/researchhub/web/tree/main/store"
click node_platform_providers "https://github.com/researchhub/web/tree/main/components/providers"
click node_platform_lib "https://github.com/researchhub/web/tree/main/lib"

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_app_root,node_app_feed,node_app_work,node_app_funding,node_app_expert,node_app_notebook,node_app_moderation,node_app_identity toneBlue
class node_components_work,node_components_feed,node_components_funding,node_components_editor_notebook,node_components_shared toneAmber
class node_services_api,node_services_graphql toneMint
class node_state_hooks,node_state_contexts,node_state_store toneRose
class node_platform_providers,node_platform_lib toneIndigo
```

## Components

### App Router

Route-driven Next.js entry points and special route handlers.

- [Routes](https://github.com/researchhub/web/tree/main/app): nextjs app router · Top-level app routes, layouts, and API handlers. · `app`
- [Feed](https://github.com/researchhub/web/tree/main/app/(feed)): route cluster · Following, for-you, latest, and popular feed surfaces. · `app/(feed)`
- [Works](https://github.com/researchhub/web/tree/main/app/paper): route cluster · Paper, post, proposal, question, grant, and related document flows. · `app/paper`
- [Funding](https://github.com/researchhub/web/tree/main/app/fund): route cluster · Funding marketplace, grants, fundraise, earn, and give experiences. · `app/fund`
- [Expert Finder](https://github.com/researchhub/web/tree/main/app/expert-finder): route cluster · Search, outreach, templates, and library workflows for expert sourcing. · `app/expert-finder`
- [Notebook](https://github.com/researchhub/web/tree/main/app/notebook): route cluster · Organization notebooks, editor-backed notes, and notebook APIs. · `app/notebook`
- [Moderation](https://github.com/researchhub/web/tree/main/app/moderators): route cluster · Admin and review tooling for pending works, editors, referrals, and audits. · `app/moderators`
- [Identity](https://github.com/researchhub/web/tree/main/app/auth): auth & profile routes · Sign-in, reset, verify, settings, author pages, and referral/join flows. · `app/auth`

### Shared UI

Feature modules, reusable widgets, and chrome components.

- [Work UI](https://github.com/researchhub/web/tree/main/components/work): document views · Shared work-document shells, tabs, headers, history, and sidebars. · `components/work`
- [Feed UI](https://github.com/researchhub/web/tree/main/components/Feed): feed components · Feed cards, tabs, filters, and item renderers. · `components/Feed`
- [Funding UI](https://github.com/researchhub/web/tree/main/components/Funding): funding components · Grant, proposal, payment, dashboard, and marketplace presentation. · `components/Funding`
- [Editor & Notebook](https://github.com/researchhub/web/tree/main/components/Editor): editor stack · Block editor, notebook shell, publishing form, and note layout. · `components/Editor`
- [Shared UI Kit](https://github.com/researchhub/web/tree/main/components/ui): design system · Reusable primitives, modals, banners, tooltips, charts, and chrome. · `components/ui`

### Data Layer

API clients, GraphQL, and backend service façades.

- [Services](https://github.com/researchhub/web/tree/main/services): api façades · Domain service clients for auth, feed, grants, papers, moderation, wallet, and search. · `services`
- [GraphQL](https://github.com/researchhub/web/blob/main/lib/apollo-client.ts): apollo path · Apollo client and GraphQL query/mapping layer. · `lib/apollo-client.ts`

### Client State

Contexts, hooks, and client stores that coordinate UI behavior.

- [Hooks](https://github.com/researchhub/web/tree/main/hooks): behavior hooks · Feature hooks for fetching, tracking, filtering, and interaction logic. · `hooks`
- [Contexts](https://github.com/researchhub/web/tree/main/contexts): app state · Cross-app UI, auth, navigation, referral, notification, and wallet state. · `contexts`
- [Stores](https://github.com/researchhub/web/tree/main/store): client stores · Persistent local state for grants and hubs. · `store`

### Platform

Providers, library helpers, and cross-cutting utilities.

- [Providers](https://github.com/researchhub/web/tree/main/components/providers): app providers · Analytics, Apollo, NextAuth, APM, and toaster wiring. · `components/providers`
- [Lib & Utils](https://github.com/researchhub/web/tree/main/lib): shared helpers · Formatting, metadata, content conversion, and structured-data helpers. · `lib`

## Connections

- Routes → Shared UI Kit: renders · Routes compose shared layout primitives and reusable UI.
- Routes → Services: calls · Route handlers and pages fetch domain data through service clients.
- Routes → Hooks: uses · Pages rely on hooks for client behavior and data orchestration.
- Routes → Contexts: reads · Route shells consume cross-app state providers.
- Feed → Feed UI: builds with · Feed routes are thin wrappers around feed presentation modules.
- Works → Work UI: builds with · Paper, post, proposal, question, and grant pages share the work-document model.
- Funding → Funding UI: builds with · Funding routes compose grants, proposals, dashboards, and payment views.
- Expert Finder → Shared UI Kit: composes · Expert finder uses common modals, tables, and form components.
- Notebook → Editor & Notebook: builds with · Notebook routes layer on the editor and note-management UI.
- Moderation → Shared UI Kit: composes · Moderation pages use shared chrome and table-like presentation.
- Identity → Shared UI Kit: uses · Identity and profile flows use common forms, modals, and banners.
- Work UI → Services: loads · Work views pull documents, reviews, comments, and related metadata.
- Feed UI → Services: loads · Feed modules fetch feed sources, filters, and item actions.
- Funding UI → Services: loads · Funding UI connects to grants, payments, wallets, and fundraisers.
- Editor & Notebook → Services: syncs · Editor and notebook workflows persist documents and collaborative state.
- Services → GraphQL: uses · Some domain clients route through Apollo and GraphQL queries.
- Services → Lib & Utils: depends on · Service clients share request, conversion, and formatting helpers.
- Hooks → Services: wraps · Hooks encapsulate service calls and client-side interaction logic.
- Hooks → Contexts: coordinates · Hooks bridge shared state and feature-specific behavior.
- Stores → Hooks: consumed by · Feature hooks read and update persistent client stores.
- Providers → GraphQL: provides · Apollo provider wires the GraphQL client into the app shell.
- Providers → Contexts: wraps · Providers initialize cross-cutting client state and telemetry.
- Routes → Providers: wraps · The root layout installs app-wide providers.