# vedantgonbare/researchpulse architecture

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

- Interactive diagram: https://gitdiagram.com/vedantgonbare/researchpulse
- Repository: https://github.com/vedantgonbare/researchpulse

## Overview

ResearchPulse is an academic-paper tracking API with a React client in the repository. Its main workflow authenticates a user, searches arXiv or accepts a paper ID, saves papers to PostgreSQL, and supports organization, summaries, and unread-paper digests. Separate branches handle file uploads and request throttling. The map follows the excerpted route calls and the README’s documented capabilities; frontend files and several service implementations are only indexed, so their internal wiring is not inferred.

Main entry points: [`app/api/papers.py`](https://github.com/vedantgonbare/researchpulse/blob/main/app/api/papers.py) (Paper routes), [`app/api/auth.py`](https://github.com/vedantgonbare/researchpulse/blob/main/app/api/auth.py) (Authentication routes), [`app/core/dependencies.py`](https://github.com/vedantgonbare/researchpulse/blob/main/app/core/dependencies.py) (Current-user lookup), [`app/main.py`](https://github.com/vedantgonbare/researchpulse/blob/main/app/main.py) (FastAPI app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API entry"]
  node_app["FastAPI app<br/>[main.py]"]
  node_file_routes["File upload route<br/>[files.py]"]
  node_limiter["Rate limiting<br/>[limiter.py]"]
end

subgraph group_identity["Identity and access"]
  node_auth["Authentication routes<br/>[auth.py]"]
  node_security["JWT and passwords<br/>[security.py]"]
  node_identity_lookup["Current-user lookup<br/>[dependencies.py]"]
  node_user_model["User records<br/>[user.py]"]
end

subgraph group_papers["Paper management"]
  node_paper_routes["Paper routes<br/>[papers.py]"]
  node_paper_model["Paper records<br/>[paper.py]"]
  node_digest["Unread digest<br/>[digest.py]"]
  node_db_session["Database sessions<br/>[session.py]"]
end

subgraph group_integrations["External services"]
  node_arxiv["arXiv search and fetch<br/>[arxiv.py]"]
  node_cache["Query cache<br/>[cache.py]"]
  node_ai["AI summarization<br/>[ai.py]"]
  node_storage["Cloudinary storage<br/>[storage.py]"]
end

node_client(("API client"))
node_postgres[("PostgreSQL")]
node_redis[("Redis")]
node_arxiv_service["arXiv"]
node_gemini["Gemini AI"]
node_cloudinary["Cloudinary"]

node_client -->|"sends requests"| node_app
node_app -->|"registers router"| node_auth
node_app -->|"registers router"| node_paper_routes
node_app -->|"registers router"| node_file_routes
node_auth -->|"hashes and signs"| node_security
node_auth -->|"requires user"| node_identity_lookup
node_identity_lookup -->|"decodes token"| node_security
node_identity_lookup -->|"loads user"| node_user_model
node_auth -->|"creates and queries"| node_user_model
node_auth -->|"uses session"| node_db_session
node_paper_routes -->|"requires user"| node_identity_lookup
node_paper_routes -->|"uses session"| node_db_session
node_paper_routes -->|"queries and saves"| node_paper_model
node_paper_routes -->|"searches and fetches"| node_arxiv
node_paper_routes -->|"checks and updates"| node_cache
node_paper_routes -->|"requests digest"| node_digest
node_paper_routes -->|"requests summary"| node_ai
node_file_routes -->|"requires user"| node_identity_lookup
node_file_routes -->|"uploads file"| node_storage
node_paper_routes -->|"applies limits"| node_limiter
node_file_routes -->|"applies limits"| node_limiter
node_db_session -->|"connects"| node_postgres
node_paper_model -->|"stores paper data"| node_postgres
node_user_model -->|"stores user data"| node_postgres
node_cache -->|"caches queries"| node_redis
node_limiter -->|"tracks request counts"| node_redis
node_arxiv -->|"searches and fetches"| node_arxiv_service
node_ai -->|"summarizes abstracts"| node_gemini
node_storage -->|"uploads files"| node_cloudinary

click node_app "https://github.com/vedantgonbare/researchpulse/blob/main/app/main.py"
click node_auth "https://github.com/vedantgonbare/researchpulse/blob/main/app/api/auth.py"
click node_security "https://github.com/vedantgonbare/researchpulse/blob/main/app/core/security.py"
click node_identity_lookup "https://github.com/vedantgonbare/researchpulse/blob/main/app/core/dependencies.py"
click node_user_model "https://github.com/vedantgonbare/researchpulse/blob/main/app/models/user.py"
click node_paper_routes "https://github.com/vedantgonbare/researchpulse/blob/main/app/api/papers.py"
click node_paper_model "https://github.com/vedantgonbare/researchpulse/blob/main/app/models/paper.py"
click node_arxiv "https://github.com/vedantgonbare/researchpulse/blob/main/app/services/arxiv.py"
click node_cache "https://github.com/vedantgonbare/researchpulse/blob/main/app/services/cache.py"
click node_digest "https://github.com/vedantgonbare/researchpulse/blob/main/app/services/digest.py"
click node_ai "https://github.com/vedantgonbare/researchpulse/blob/main/app/services/ai.py"
click node_file_routes "https://github.com/vedantgonbare/researchpulse/blob/main/app/api/files.py"
click node_storage "https://github.com/vedantgonbare/researchpulse/blob/main/app/services/storage.py"
click node_limiter "https://github.com/vedantgonbare/researchpulse/blob/main/app/core/limiter.py"
click node_db_session "https://github.com/vedantgonbare/researchpulse/blob/main/app/db/session.py"

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,node_file_routes,node_limiter,node_client toneBlue
class node_auth,node_security,node_identity_lookup,node_user_model,node_postgres,node_redis toneAmber
class node_paper_routes,node_paper_model,node_digest,node_db_session toneMint
class node_arxiv,node_cache,node_ai,node_storage toneRose
class node_arxiv_service,node_gemini,node_cloudinary toneIndigo
```

## Components

### API entry

- [FastAPI app](https://github.com/vedantgonbare/researchpulse/blob/main/app/main.py): `app/main.py`
- [File upload route](https://github.com/vedantgonbare/researchpulse/blob/main/app/api/files.py): `app/api/files.py`
- [Rate limiting](https://github.com/vedantgonbare/researchpulse/blob/main/app/core/limiter.py): `app/core/limiter.py`

### Identity and access

- [Authentication routes](https://github.com/vedantgonbare/researchpulse/blob/main/app/api/auth.py): `app/api/auth.py`
- [JWT and passwords](https://github.com/vedantgonbare/researchpulse/blob/main/app/core/security.py): `app/core/security.py`
- [Current-user lookup](https://github.com/vedantgonbare/researchpulse/blob/main/app/core/dependencies.py): `app/core/dependencies.py`
- [User records](https://github.com/vedantgonbare/researchpulse/blob/main/app/models/user.py): `app/models/user.py`

### Paper management

- [Paper routes](https://github.com/vedantgonbare/researchpulse/blob/main/app/api/papers.py): `app/api/papers.py`
- [Paper records](https://github.com/vedantgonbare/researchpulse/blob/main/app/models/paper.py): `app/models/paper.py`
- [Unread digest](https://github.com/vedantgonbare/researchpulse/blob/main/app/services/digest.py): `app/services/digest.py`
- [Database sessions](https://github.com/vedantgonbare/researchpulse/blob/main/app/db/session.py): `app/db/session.py`

### External services

- [arXiv search and fetch](https://github.com/vedantgonbare/researchpulse/blob/main/app/services/arxiv.py): `app/services/arxiv.py`
- [Query cache](https://github.com/vedantgonbare/researchpulse/blob/main/app/services/cache.py): `app/services/cache.py`
- [AI summarization](https://github.com/vedantgonbare/researchpulse/blob/main/app/services/ai.py): `app/services/ai.py`
- [Cloudinary storage](https://github.com/vedantgonbare/researchpulse/blob/main/app/services/storage.py): `app/services/storage.py`

### Other components

- **API client**
- **PostgreSQL**
- **Redis**
- **arXiv**
- **Gemini AI**
- **Cloudinary**

## Connections

- API client → FastAPI app: sends requests (evidence: `README.md`)
- FastAPI app → Authentication routes: registers router (evidence: `app/main.py`)
- FastAPI app → Paper routes: registers router (evidence: `app/main.py`)
- FastAPI app → File upload route: registers router (evidence: `app/main.py`)
- Authentication routes → JWT and passwords: hashes and signs (evidence: `app/api/auth.py`)
- Authentication routes → Current-user lookup: requires user (evidence: `app/api/auth.py`)
- Current-user lookup → JWT and passwords: decodes token (evidence: `app/core/dependencies.py`)
- Current-user lookup → User records: loads user (evidence: `app/core/dependencies.py`)
- Authentication routes → User records: creates and queries (evidence: `app/api/auth.py`)
- Authentication routes → Database sessions: uses session (evidence: `app/api/auth.py`)
- Paper routes → Current-user lookup: requires user (evidence: `app/api/papers.py`)
- Paper routes → Database sessions: uses session (evidence: `app/api/papers.py`)
- Paper routes → Paper records: queries and saves (evidence: `app/api/papers.py`)
- Paper routes → arXiv search and fetch: searches and fetches (evidence: `app/api/papers.py`)
- Paper routes → Query cache: checks and updates (evidence: `app/api/papers.py`)
- Paper routes → Unread digest: requests digest (evidence: `app/api/papers.py`)
- Paper routes → AI summarization: requests summary (evidence: `app/api/papers.py`)
- File upload route → Current-user lookup: requires user (evidence: `app/api/files.py`)
- File upload route → Cloudinary storage: uploads file (evidence: `app/api/files.py`)
- Paper routes → Rate limiting: applies limits (evidence: `app/api/papers.py`)
- File upload route → Rate limiting: applies limits (evidence: `app/api/files.py`)
- Database sessions → PostgreSQL: connects (evidence: `app/db/session.py`)
- Paper records → PostgreSQL: stores paper data (evidence: `README.md`)
- User records → PostgreSQL: stores user data (evidence: `README.md`)
- Query cache → Redis: caches queries (evidence: `README.md`)
- Rate limiting → Redis: tracks request counts (evidence: `README.md`)
- arXiv search and fetch → arXiv: searches and fetches (evidence: `README.md`)
- AI summarization → Gemini AI: summarizes abstracts (evidence: `README.md`)
- Cloudinary storage → Cloudinary: uploads files (evidence: `app/services/storage.py`)
