# researchhub/researchhub-backend architecture

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

## Overview

1. This is a Django monolith organized into many domain apps under `src/`. The main application bootstrap lives in `researchhub/` (`settings`, `urls`, `wsgi`, `asgi`, `celery`), while each feature area owns its own `models`, `views`, `serializers`, `permissions`, `services`, `signals`, `tasks`, and migrations.

2. The core architectural boundary is the Django API layer. Most request handling flows through app-specific DRF views and viewsets, with serializers shaping payloads and permission classes enforcing access. The repo is not a single-purpose app; it exposes a broad API for content, identity, search, funding, discussion, and AI-assisted workflows.

3. Content is centered around the paper/document stack. `paper/`, `researchhub_document/`, `discussion/`, `review/`, `note/`, `hub/`, `topic/`, `tag/`, and `user/` collectively model scholarly content, authorship, versions, comments, topics, hubs, and moderation state. This content layer feeds most downstream features.

4. Ingestion is a major subsystem. `paper/ingestion/` contains a pipeline, source clients, mappers, and enrichment services for external sources such as OpenAlex and preprint providers. The data flow is: external source APIs/XML feeds → parsers/mappers → paper domain models → enrichment and task execution. There are many management commands for backfills and repair jobs, which indicates the ingestion path is both online and batch-driven.

5. `researchhub_document/` is the unifying abstraction used across the platform. It defines unified document records and document filters, and it connects papers, posts, grants, notes, and other entities into a common indexing/browse model. This layer is the bridge between content creation and the discovery surfaces.

6. Search is a dedicated subsystem backed by OpenSearch. `search/` contains OpenSearch documents, query builders, serializers, view endpoints, and Celery tasks for indexing and cleanup. The search flow is: domain objects change → signals/tasks update OpenSearch documents → search and suggest endpoints query the index. The README confirms OpenSearch is required for browse/search, and there are commands for index rebuild and cleanup.

7. Feed generation is another major read-optimized layer. `feed/` builds several feed variants: activity, funding, grant, journal, moderator, personalized, and ResearchHub feeds. It uses feed entries, hot-score logic, filtering, cache segmentation, and a large set of signals from content and transaction apps to invalidate or recompute feeds. This layer sits between the content/reputation events and the home/feed experiences.

8. User identity, author profiles, and moderation are handled in `user/`, `oauth/`, `orcid/`, `invite/`, `organizations/`, `researchhub_access_group/`, and related models. These apps cover signup/auth, ORCID linking, author claims, organizations, invite flows, permissions, risk scoring, and content moderation. External integrations here include OAuth/social login, ORCID, Persona verification, and organization-specific permissions.

9. Funding, transactions, and reputation form a separate financial subsystem. `purchase/` handles grants, fundraises, balances, payment intents, and payment-provider integrations; `reputation/` handles deposits, withdrawals, bounties, distributions, staking yield, and wallet logic. External payment/ledger integrations include Circle, Coinbase, Stripe, and Endaoment. This subsystem is heavily event-driven and tied to user balances and reward distribution.

10. Social interaction flows are modeled through discussion, comments, reactions, reviews, notes, notifications, and user interactions. `discussion/`, `researchhub_comment/`, `review/`, `note/`, `notification/`, and `analytics/` each own pieces of the interaction graph. Many of these apps emit signals that feed feed updates, notifications, analytics events, and reputation changes.

11. AI-assisted features are isolated into `research_ai/`, `ai_peer_review/`, and some services in `paper/`, `purchase/`, and `search/`. These modules define prompts, LLM service wrappers, email generation, expert finding, proposal review, executive summaries, and RFP-related workflows. The AI boundary is clear: prompt templates and services encapsulate calls to external LLM providers such as Bedrock/OpenAI, then persist or render the generated output back into domain objects and emails.

12. Async and event processing is a cross-cutting backbone. Celery is used throughout for ingestion, indexing, email generation, reputation updates, risk-score backfills, and feed maintenance. Django signals are used heavily to react to model changes and enqueue downstream work. Redis is implied as the task/result/cache substrate from the devcontainer and Celery setup.

13. Analytics and behavioral syncing are handled separately from core product data. `analytics/` ingests Amplitude webhooks and maps events into internal `user_interactions` records; `personalize/` exports and syncs items/interactions to a recommendation backend. This creates a pipeline from user behavior → normalized events → recommendation and reporting services.

14. Infra and developer/runtime tooling matter to the architecture: the project runs on PostgreSQL, Redis, OpenSearch, Django ASGI/WSGI, and Celery workers/beat. There are devcontainer definitions, environment-specific config modules, many management commands for backfills and maintenance, and extensive test coverage per app, which supports a service-oriented monolith rather than a thin CRUD app.

Main entry points: [`src`](https://github.com/researchhub/researchhub-backend/tree/main/src) (API apps), [`src/paper`](https://github.com/researchhub/researchhub-backend/tree/main/src/paper) (Paper domain), [`src/purchase`](https://github.com/researchhub/researchhub-backend/tree/main/src/purchase) (Funding), [`src/feed`](https://github.com/researchhub/researchhub-backend/tree/main/src/feed) (Feeds)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core platform"]
  node_researchhub_bootstrap["researchhub<br/>Django bootstrap"]
  node_api_surface["API apps<br/>DRF endpoints"]
end

subgraph group_content["Content domain"]
  node_paper_ingestion["Paper ingestion<br/>Import pipeline"]
  node_paper_domain["Paper domain<br/>Paper models"]
  node_researchhub_document["Unified documents<br/>Document index model"]
  node_discussion_comments["Discussion layer<br/>Conversation models"]
  node_review_system["Review system<br/>Review workflow"]
end

subgraph group_discovery["Discovery layers"]
  node_search_system["Search"]
  node_feed_system["Feeds<br/>Read models"]
  node_personalize_system["Personalize<br/>Recommendation sync"]
end

subgraph group_identity["Identity and access"]
  node_user_identity["Users<br/>Identity/profile"]
  node_auth_integrations["Auth integrations<br/>Signup/linking"]
  node_orcid_integration["ORCID<br/>External identity"]
  node_orgs_access["Organizations<br/>Org access"]
end

subgraph group_finance["Funding and reputation"]
  node_funding_purchase["Funding<br/>Payments/grants"]
  node_reputation_system["Reputation<br/>Rewards/ledger"]
end

subgraph group_ai["AI workflows"]
  node_ai_workflows["AI workflows<br/>LLM services"]
  node_ai_peer_review["AI peer review<br/>Automated review"]
end

subgraph group_ops["Async and integrations"]
  node_analytics_pipeline["Analytics<br/>Behavior ingest"]
  node_external_services[("External services<br/>Integrations")]
end

node_researchhub_bootstrap -->|"configures"| node_api_surface
node_api_surface -->|"serves"| node_paper_domain
node_api_surface -->|"serves"| node_discussion_comments
node_api_surface -->|"serves"| node_review_system
node_api_surface -->|"serves"| node_funding_purchase
node_api_surface -->|"serves"| node_reputation_system
node_api_surface -->|"serves"| node_search_system
node_api_surface -->|"serves"| node_feed_system
node_paper_ingestion -->|"writes"| node_paper_domain
node_paper_ingestion -->|"enriches"| node_researchhub_document
node_paper_domain -->|"publishes"| node_researchhub_document
node_discussion_comments -->|"publishes"| node_researchhub_document
node_review_system -->|"extends"| node_discussion_comments
node_researchhub_document -->|"indexes"| node_search_system
node_paper_domain -.->|"signals"| node_search_system
node_discussion_comments -.->|"signals"| node_feed_system
node_paper_domain -.->|"signals"| node_feed_system
node_funding_purchase -.->|"signals"| node_feed_system
node_reputation_system -.->|"signals"| node_feed_system
node_analytics_pipeline -->|"syncs"| node_personalize_system
node_user_identity -->|"uses"| node_auth_integrations
node_auth_integrations -->|"delegates"| node_orcid_integration
node_user_identity -->|"governs"| node_orgs_access
node_user_identity -->|"owns"| node_funding_purchase
node_user_identity -->|"owns"| node_reputation_system
node_funding_purchase -->|"feeds"| node_reputation_system
node_ai_workflows -->|"reviews"| node_funding_purchase
node_ai_workflows -->|"analyzes"| node_paper_domain
node_ai_peer_review -->|"uses"| node_ai_workflows
node_search_system -.->|"depends on"| node_external_services
node_feed_system -.->|"depends on"| node_external_services
node_funding_purchase -.->|"integrates"| node_external_services
node_reputation_system -.->|"integrates"| node_external_services
node_ai_workflows -.->|"calls"| node_external_services

click node_researchhub_bootstrap "https://github.com/researchhub/researchhub-backend/tree/main/src/researchhub"
click node_api_surface "https://github.com/researchhub/researchhub-backend/tree/main/src"
click node_paper_ingestion "https://github.com/researchhub/researchhub-backend/tree/main/src/paper/ingestion"
click node_paper_domain "https://github.com/researchhub/researchhub-backend/tree/main/src/paper"
click node_researchhub_document "https://github.com/researchhub/researchhub-backend/tree/main/src/researchhub_document"
click node_discussion_comments "https://github.com/researchhub/researchhub-backend/tree/main/src/discussion"
click node_review_system "https://github.com/researchhub/researchhub-backend/tree/main/src/review"
click node_search_system "https://github.com/researchhub/researchhub-backend/tree/main/src/search"
click node_feed_system "https://github.com/researchhub/researchhub-backend/tree/main/src/feed"
click node_personalize_system "https://github.com/researchhub/researchhub-backend/tree/main/src/personalize"
click node_user_identity "https://github.com/researchhub/researchhub-backend/tree/main/src/user"
click node_auth_integrations "https://github.com/researchhub/researchhub-backend/tree/main/src/oauth"
click node_orcid_integration "https://github.com/researchhub/researchhub-backend/tree/main/src/orcid"
click node_orgs_access "https://github.com/researchhub/researchhub-backend/tree/main/src/organizations"
click node_funding_purchase "https://github.com/researchhub/researchhub-backend/tree/main/src/purchase"
click node_reputation_system "https://github.com/researchhub/researchhub-backend/tree/main/src/reputation"
click node_ai_workflows "https://github.com/researchhub/researchhub-backend/tree/main/src/research_ai"
click node_ai_peer_review "https://github.com/researchhub/researchhub-backend/tree/main/src/ai_peer_review"
click node_analytics_pipeline "https://github.com/researchhub/researchhub-backend/tree/main/src/analytics"

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_researchhub_bootstrap,node_api_surface,node_analytics_pipeline,node_external_services toneBlue
class node_paper_ingestion,node_paper_domain,node_researchhub_document,node_discussion_comments,node_review_system toneAmber
class node_search_system,node_feed_system,node_personalize_system toneMint
class node_user_identity,node_auth_integrations,node_orcid_integration,node_orgs_access toneRose
class node_funding_purchase,node_reputation_system toneIndigo
class node_ai_workflows,node_ai_peer_review toneTeal
```

## Components

### Core platform

Bootstrap, API surface, and shared runtime wiring.

- [researchhub](https://github.com/researchhub/researchhub-backend/tree/main/src/researchhub): Django bootstrap · Project settings, URL routing, ASGI/WSGI, Celery wiring, and shared API runtime. · `src/researchhub`
- [API apps](https://github.com/researchhub/researchhub-backend/tree/main/src): DRF endpoints · App-specific views, serializers, permissions, and services that implement the public API. · `src`

### Content domain

Scholarly content, unified documents, and interaction models.

- [Paper ingestion](https://github.com/researchhub/researchhub-backend/tree/main/src/paper/ingestion): Import pipeline · External source clients, parsers, mappers, and enrichment services for paper intake. · `src/paper/ingestion`
- [Paper domain](https://github.com/researchhub/researchhub-backend/tree/main/src/paper): Paper models · Paper, authorship, versions, citations, uploads, and paper-centric services. · `src/paper`
- [Unified documents](https://github.com/researchhub/researchhub-backend/tree/main/src/researchhub_document): Document index model · Cross-domain document abstraction for browse, filters, and shared discovery views. · `src/researchhub_document`
- [Discussion layer](https://github.com/researchhub/researchhub-backend/tree/main/src/discussion): Conversation models · Threads, comments, reactions, reviews, and note/discussion interactions. · `src/discussion`
- [Review system](https://github.com/researchhub/researchhub-backend/tree/main/src/review): Review workflow · Peer review objects, availability, permissions, services, and review signals. · `src/review`

### Discovery layers

Search, feeds, and recommendation-oriented read models.

- [Search](https://github.com/researchhub/researchhub-backend/tree/main/src/search): OpenSearch subsystem · Index documents, query builders, suggest endpoints, indexing tasks, and cleanup commands. · `src/search`
- [Feeds](https://github.com/researchhub/researchhub-backend/tree/main/src/feed): Read models · Activity, funding, grant, journal, moderator, and personalized feed generation. · `src/feed`
- [Personalize](https://github.com/researchhub/researchhub-backend/tree/main/src/personalize): Recommendation sync · Exports items and interactions to an external recommendation backend. · `src/personalize`

### Identity and access

Signup, profiles, orgs, invites, and moderation boundaries.

- [Users](https://github.com/researchhub/researchhub-backend/tree/main/src/user): Identity/profile · Users, authors, moderation, verification, risk scoring, follows, and engagement state. · `src/user`
- [Auth integrations](https://github.com/researchhub/researchhub-backend/tree/main/src/oauth): Signup/linking · OAuth signup, ORCID linking, invitation flows, and access group permissions. · `src/oauth`
- [ORCID](https://github.com/researchhub/researchhub-backend/tree/main/src/orcid): External identity · ORCID connect/callback/fetch services and related tasks. · `src/orcid`
- [Organizations](https://github.com/researchhub/researchhub-backend/tree/main/src/organizations): Org access · Organizations, access groups, and organization-scoped permissions. · `src/organizations`

### Funding and reputation

Wallets, payments, grants, bounties, and reputation flows.

- [Funding](https://github.com/researchhub/researchhub-backend/tree/main/src/purchase): Payments/grants · Balances, purchases, fundraises, grants, payment intents, and provider integrations. · `src/purchase`
- [Reputation](https://github.com/researchhub/researchhub-backend/tree/main/src/reputation): Rewards/ledger · Deposits, withdrawals, bounties, staking yield, distributions, and wallet logic. · `src/reputation`

### AI workflows

LLM-assisted review, search, and outreach workflows.

- [AI workflows](https://github.com/researchhub/researchhub-backend/tree/main/src/research_ai): LLM services · Proposal review, executive summaries, expert finding, and outreach/email generation. · `src/research_ai`
- [AI peer review](https://github.com/researchhub/researchhub-backend/tree/main/src/ai_peer_review): Automated review · Proposal review generation, scoring, comment upserts, and editorial feedback workflows. · `src/ai_peer_review`

### Async and integrations

Background jobs, webhooks, analytics, and external services.

- [Analytics](https://github.com/researchhub/researchhub-backend/tree/main/src/analytics): Behavior ingest · Amplitude webhook ingestion and normalization into internal interaction records. · `src/analytics`
- **External services**: Integrations · PostgreSQL, Redis, OpenSearch, payment providers, and LLM backends used across the monolith.

## Connections

- researchhub → API apps: configures · Bootstraps routing, settings, auth, and task execution for all apps.
- API apps → Paper domain: serves · Paper endpoints expose paper CRUD, upload, versions, and related actions.
- API apps → Discussion layer: serves · Discussion and comment endpoints handle threads, reactions, and moderation.
- API apps → Review system: serves · Review endpoints expose review availability and review operations.
- API apps → Funding: serves · Funding APIs expose grants, fundraises, balances, and payment flows.
- API apps → Reputation: serves · Reputation APIs expose deposits, withdrawals, bounties, and staking.
- API apps → Search: serves · Search endpoints query and suggest across indexed documents.
- API apps → Feeds: serves · Feed endpoints render activity, funding, journal, and personalized feeds.
- Paper ingestion → Paper domain: writes · Imported works are normalized into paper records and related models.
- Paper ingestion → Unified documents: enriches · Imported papers are also reflected into unified browse/document records.
- Paper domain → Unified documents: publishes · Paper changes feed the unified document abstraction for discovery surfaces.
- Discussion layer → Unified documents: publishes · Posts, comments, and related entities contribute to unified documents.
- Review system → Discussion layer: extends · Review content is threaded through discussion/comment structures.
- Unified documents → Search: indexes · Unified documents are projected into OpenSearch documents.
- Paper domain → Search: signals · Paper updates trigger indexing and cleanup of search documents.
- Discussion layer → Feeds: signals · Comment and discussion activity invalidates or updates feeds.
- Paper domain → Feeds: signals · Paper changes create feed entries and hot-score updates.
- Funding → Feeds: signals · Funding events contribute to funding, grant, and activity feeds.
- Reputation → Feeds: signals · Reputation events drive bounty, moderation, and activity feed updates.
- Analytics → Personalize: syncs · Normalized interactions are exported for recommendation and sync services.
- Users → Auth integrations: uses · Identity and profile flows rely on signup, OAuth, and ORCID linking.
- Auth integrations → ORCID: delegates · ORCID connect, callback, and fetch logic is handled by the ORCID app.
- Users → Organizations: governs · User and author permissions are constrained by organization access models.
- Users → Funding: owns · Wallets, balances, and support status are attached to users and authors.
- Users → Reputation: owns · Reputation accounts, rewards, and payouts are user-centered.
- Funding → Reputation: feeds · Purchases and grants drive reward, payout, and wallet-related reputation flows.
- AI workflows → Funding: reviews · Proposal and grant workflows generate summaries and assessment outputs.
- AI workflows → Paper domain: analyzes · Paper-related AI services generate summaries, context, and expert discovery artifacts.
- AI peer review → AI workflows: uses · Automated proposal review builds on shared LLM and prompt services.
- Search → External services: depends on · OpenSearch is required for browse/search functionality.
- Feeds → External services: depends on · Feeds rely on cache, async jobs, and external persistence backends.
- Funding → External services: integrates · Payment and transfer providers are used for checkout and grants.
- Reputation → External services: integrates · Ledger, wallet, and staking flows depend on external services and storage.
- AI workflows → External services: calls · LLM and context-generation services call external model providers.