How researchhub/web works
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 Services · app Routes · hooks Hooks · ui Shared UI Kit
Components 20
App Router
Route-driven Next.js entry points and special route handlers.
- Routes · Top-level app routes, layouts, and API handlers.
app - Feed · Following, for-you, latest, and popular feed surfaces.
app/(feed) - Works · Paper, post, proposal, question, grant, and related document flows.
app/paper - Funding · Funding marketplace, grants, fundraise, earn, and give experiences.
app/fund - Expert Finder · Search, outreach, templates, and library workflows for expert sourcing.
app/expert-finder - Notebook · Organization notebooks, editor-backed notes, and notebook APIs.
app/notebook - Moderation · Admin and review tooling for pending works, editors, referrals, and audits.
app/moderators - Identity · Sign-in, reset, verify, settings, author pages, and referral/join flows.
app/auth
Shared UI
Feature modules, reusable widgets, and chrome components.
- Work UI · Shared work-document shells, tabs, headers, history, and sidebars.
components/work - Feed UI · Feed cards, tabs, filters, and item renderers.
components/Feed - Funding UI · Grant, proposal, payment, dashboard, and marketplace presentation.
components/Funding - Editor & Notebook · Block editor, notebook shell, publishing form, and note layout.
components/Editor - Shared UI Kit · Reusable primitives, modals, banners, tooltips, charts, and chrome.
components/ui
Data Layer
API clients, GraphQL, and backend service façades.
Client State
Contexts, hooks, and client stores that coordinate UI behavior.
Platform
Providers, library helpers, and cross-cutting utilities.
- Providers · Analytics, Apollo, NextAuth, APM, and toaster wiring.
components/providers - Lib & Utils · Formatting, metadata, content conversion, and structured-data helpers.
lib
Connections 23
- 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.