# ashure333/thesis-recommendation-system architecture

> Architecture diagram of the GitHub repository ashure333/thesis-recommendation-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ashure333/thesis-recommendation-system
- Repository: https://github.com/ashure333/thesis-recommendation-system

## Overview

PaperRec is a locally deployed academic-paper repository and recommendation system. Users import PDFs or BibTeX through the React interface; the API processes paper metadata, stores records and files, and exposes repository and personal-library operations. For recommendation searches, the API delegates to a search service that selects TF-IDF, S-BERT, and/or metadata scoring, then returns ranked results. The README documents additional capabilities including classification, validation, PDF discovery, evaluation, and index rebuilding. Some subsystem connections are based on README documentation because their source was not excerpted.

Main entry points: [`app/services/upload_paper.py`](https://github.com/ashure333/thesis-recommendation-system/blob/main/app/services/upload_paper.py) (Upload orchestration), [`app/api.py`](https://github.com/ashure333/thesis-recommendation-system/blob/main/app/api.py) (FastAPI routes), [`app/services/recommendation/search_service.py`](https://github.com/ashure333/thesis-recommendation-system/blob/main/app/services/recommendation/search_service.py) (Search orchestration), [`frontend/src/App.tsx`](https://github.com/ashure333/thesis-recommendation-system/blob/main/frontend/src/App.tsx) (React app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web interface"]
  node_webapp["React app<br/>[App.tsx]"]
  node_repo_ui["Repository UI<br/>[Repository.tsx]"]
  node_upload_ui["Upload UI<br/>[Upload.tsx]"]
  node_search_ui["Search UI<br/>[Search.tsx]"]
  node_recommend_ui["Recommendations UI"]
  node_client_api["HTTP client<br/>[api.ts]"]
end

subgraph group_ingest["Paper ingestion"]
  node_upload_service["Upload orchestration<br/>[upload_paper.py]"]
  node_bib_extract["BibTeX extraction<br/>[bib_extraction.py]"]
  node_pdf_extract["PDF extraction<br/>[extraction.py]"]
  node_classification["Classification<br/>[classification.py]"]
  node_validation["Recommendation validation<br/>[validation.py]"]
  node_text_prep["Prepared text"]
  node_pdf_finder["PDF discovery<br/>[pdf_finder.py]"]
end

subgraph group_repository["Repository state"]
  node_api["FastAPI routes<br/>[api.py]"]
  node_file_storage[("Paper files<br/>[storage.py]")]
  node_queries["Repository queries<br/>[queries.py]"]
  node_database[("SQLite records<br/>[database.py]")]
  node_models["Paper and user models<br/>[models.py]"]
end

subgraph group_recommendation["Recommendation"]
  node_search_service["Search orchestration<br/>[search_service.py]"]
  node_pipeline_config["Pipeline weights<br/>[pipeline_config.py]"]
  node_tfidf["TF-IDF scoring<br/>[tfidf_pipeline.py]"]
  node_sbert["S-BERT scoring<br/>[sbert_pipeline.py]"]
  node_metadata["Metadata scoring"]
  node_similarity["Similarity utilities<br/>[similarity.py]"]
end

node_researcher(("Researcher"))
node_pdf_sources["Open-access sources"]

node_researcher -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_repo_ui
node_webapp -->|"routes to"| node_upload_ui
node_webapp -->|"routes to"| node_search_ui
node_webapp -->|"routes to"| node_recommend_ui
node_repo_ui -->|"requests"| node_client_api
node_upload_ui -->|"uploads"| node_client_api
node_search_ui -->|"requests"| node_client_api
node_recommend_ui -->|"requests"| node_client_api
node_client_api -->|"HTTP calls"| node_api
node_api -->|"delegates"| node_upload_service
node_upload_service -->|"extracts BibTeX"| node_bib_extract
node_upload_service -->|"extracts PDF"| node_pdf_extract
node_upload_service -->|"classifies"| node_classification
node_upload_service -->|"validates"| node_validation
node_upload_service -->|"prepares text"| node_text_prep
node_upload_service -->|"stores files"| node_file_storage
node_api -->|"finds PDFs"| node_pdf_finder
node_pdf_finder -->|"searches sources"| node_pdf_sources
node_api -->|"queries records"| node_queries
node_queries -->|"uses models"| node_models
node_api -->|"uses session"| node_database
node_database -->|"maps tables"| node_models
node_api -->|"dispatches search"| node_search_service
node_search_service -->|"gets weights"| node_pipeline_config
node_search_service -->|"scores candidates"| node_tfidf
node_search_service -->|"scores candidates"| node_sbert
node_search_service -->|"scores candidates"| node_metadata
node_search_service -->|"loads candidates"| node_models
node_tfidf -->|"uses cosine"| node_similarity
node_sbert -->|"uses cosine"| node_similarity
node_metadata -->|"uses cosine"| node_similarity

click node_webapp "https://github.com/ashure333/thesis-recommendation-system/blob/main/frontend/src/App.tsx"
click node_repo_ui "https://github.com/ashure333/thesis-recommendation-system/blob/main/frontend/src/pages/repository/Repository.tsx"
click node_upload_ui "https://github.com/ashure333/thesis-recommendation-system/blob/main/frontend/src/pages/repository/Upload.tsx"
click node_search_ui "https://github.com/ashure333/thesis-recommendation-system/blob/main/frontend/src/pages/main/Search.tsx"
click node_recommend_ui "https://github.com/ashure333/thesis-recommendation-system/blob/main/frontend/src/pages/evaluation/Recommendations.tsx"
click node_client_api "https://github.com/ashure333/thesis-recommendation-system/blob/main/frontend/src/api.ts"
click node_api "https://github.com/ashure333/thesis-recommendation-system/blob/main/app/api.py"
click node_upload_service "https://github.com/ashure333/thesis-recommendation-system/blob/main/app/services/upload_paper.py"
click node_bib_extract "https://github.com/ashure333/thesis-recommendation-system/blob/main/app/services/bib_extraction.py"
click node_pdf_extract "https://github.com/ashure333/thesis-recommendation-system/blob/main/app/services/extraction.py"
click node_classification "https://github.com/ashure333/thesis-recommendation-system/blob/main/app/services/classification.py"
click node_validation "https://github.com/ashure333/thesis-recommendation-system/blob/main/app/services/validation.py"
click node_text_prep "https://github.com/ashure333/thesis-recommendation-system/blob/main/app/services/text_preparation.py"
click node_pdf_finder "https://github.com/ashure333/thesis-recommendation-system/blob/main/app/services/pdf_finder.py"
click node_file_storage "https://github.com/ashure333/thesis-recommendation-system/blob/main/app/services/storage.py"
click node_queries "https://github.com/ashure333/thesis-recommendation-system/blob/main/app/repositories/queries.py"
click node_database "https://github.com/ashure333/thesis-recommendation-system/blob/main/app/database.py"
click node_models "https://github.com/ashure333/thesis-recommendation-system/blob/main/app/models/models.py"
click node_search_service "https://github.com/ashure333/thesis-recommendation-system/blob/main/app/services/recommendation/search_service.py"
click node_pipeline_config "https://github.com/ashure333/thesis-recommendation-system/blob/main/app/services/recommendation/pipeline_config.py"
click node_tfidf "https://github.com/ashure333/thesis-recommendation-system/blob/main/app/services/recommendation/tfidf_pipeline.py"
click node_sbert "https://github.com/ashure333/thesis-recommendation-system/blob/main/app/services/recommendation/sbert_pipeline.py"
click node_metadata "https://github.com/ashure333/thesis-recommendation-system/blob/main/app/services/recommendation/metadata_pipeline.py"
click node_similarity "https://github.com/ashure333/thesis-recommendation-system/blob/main/app/services/recommendation/similarity.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_webapp,node_repo_ui,node_upload_ui,node_search_ui,node_recommend_ui,node_client_api toneBlue
class node_upload_service,node_bib_extract,node_pdf_extract,node_classification,node_validation,node_text_prep,node_pdf_finder toneAmber
class node_api,node_file_storage,node_queries,node_database,node_models toneMint
class node_search_service,node_pipeline_config,node_tfidf,node_sbert,node_metadata,node_similarity toneRose
class node_researcher,node_pdf_sources toneIndigo
```

## Components

### Web interface

- [React app](https://github.com/ashure333/thesis-recommendation-system/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Repository UI](https://github.com/ashure333/thesis-recommendation-system/blob/main/frontend/src/pages/repository/Repository.tsx): `frontend/src/pages/repository/Repository.tsx`
- [Upload UI](https://github.com/ashure333/thesis-recommendation-system/blob/main/frontend/src/pages/repository/Upload.tsx): `frontend/src/pages/repository/Upload.tsx`
- [Search UI](https://github.com/ashure333/thesis-recommendation-system/blob/main/frontend/src/pages/main/Search.tsx): `frontend/src/pages/main/Search.tsx`
- [Recommendations UI](https://github.com/ashure333/thesis-recommendation-system/blob/main/frontend/src/pages/evaluation/Recommendations.tsx): `frontend/src/pages/evaluation/Recommendations.tsx`
- [HTTP client](https://github.com/ashure333/thesis-recommendation-system/blob/main/frontend/src/api.ts): `frontend/src/api.ts`

### Paper ingestion

- [Upload orchestration](https://github.com/ashure333/thesis-recommendation-system/blob/main/app/services/upload_paper.py): `app/services/upload_paper.py`
- [BibTeX extraction](https://github.com/ashure333/thesis-recommendation-system/blob/main/app/services/bib_extraction.py): `app/services/bib_extraction.py`
- [PDF extraction](https://github.com/ashure333/thesis-recommendation-system/blob/main/app/services/extraction.py): `app/services/extraction.py`
- [Classification](https://github.com/ashure333/thesis-recommendation-system/blob/main/app/services/classification.py): `app/services/classification.py`
- [Recommendation validation](https://github.com/ashure333/thesis-recommendation-system/blob/main/app/services/validation.py): `app/services/validation.py`
- [Prepared text](https://github.com/ashure333/thesis-recommendation-system/blob/main/app/services/text_preparation.py): `app/services/text_preparation.py`
- [PDF discovery](https://github.com/ashure333/thesis-recommendation-system/blob/main/app/services/pdf_finder.py): `app/services/pdf_finder.py`

### Repository state

- [FastAPI routes](https://github.com/ashure333/thesis-recommendation-system/blob/main/app/api.py): `app/api.py`
- [Paper files](https://github.com/ashure333/thesis-recommendation-system/blob/main/app/services/storage.py): `app/services/storage.py`
- [Repository queries](https://github.com/ashure333/thesis-recommendation-system/blob/main/app/repositories/queries.py): `app/repositories/queries.py`
- [SQLite records](https://github.com/ashure333/thesis-recommendation-system/blob/main/app/database.py): `app/database.py`
- [Paper and user models](https://github.com/ashure333/thesis-recommendation-system/blob/main/app/models/models.py): `app/models/models.py`

### Recommendation

- [Search orchestration](https://github.com/ashure333/thesis-recommendation-system/blob/main/app/services/recommendation/search_service.py): `app/services/recommendation/search_service.py`
- [Pipeline weights](https://github.com/ashure333/thesis-recommendation-system/blob/main/app/services/recommendation/pipeline_config.py): `app/services/recommendation/pipeline_config.py`
- [TF-IDF scoring](https://github.com/ashure333/thesis-recommendation-system/blob/main/app/services/recommendation/tfidf_pipeline.py): `app/services/recommendation/tfidf_pipeline.py`
- [S-BERT scoring](https://github.com/ashure333/thesis-recommendation-system/blob/main/app/services/recommendation/sbert_pipeline.py): `app/services/recommendation/sbert_pipeline.py`
- [Metadata scoring](https://github.com/ashure333/thesis-recommendation-system/blob/main/app/services/recommendation/metadata_pipeline.py): `app/services/recommendation/metadata_pipeline.py`
- [Similarity utilities](https://github.com/ashure333/thesis-recommendation-system/blob/main/app/services/recommendation/similarity.py): `app/services/recommendation/similarity.py`

### Other components

- **Researcher**
- **Open-access sources**

## Connections

- Researcher → React app: uses (evidence: `README.md`)
- React app → Repository UI: routes to (evidence: `frontend/src/App.tsx`)
- React app → Upload UI: routes to (evidence: `frontend/src/App.tsx`)
- React app → Search UI: routes to (evidence: `frontend/src/App.tsx`)
- React app → Recommendations UI: routes to (evidence: `frontend/src/App.tsx`)
- Repository UI → HTTP client: requests (evidence: `frontend/src/pages/repository/Repository.tsx`)
- Upload UI → HTTP client: uploads (evidence: `README.md`)
- Search UI → HTTP client: requests (evidence: `frontend/src/pages/main/Search.tsx`)
- Recommendations UI → HTTP client: requests (evidence: `frontend/src/pages/evaluation/Recommendations.tsx`)
- HTTP client → FastAPI routes: HTTP calls (evidence: `README.md`)
- FastAPI routes → Upload orchestration: delegates (evidence: `app/api.py`)
- Upload orchestration → BibTeX extraction: extracts BibTeX (evidence: `app/services/upload_paper.py`)
- Upload orchestration → PDF extraction: extracts PDF (evidence: `app/services/upload_paper.py`)
- Upload orchestration → Classification: classifies (evidence: `app/services/upload_paper.py`)
- Upload orchestration → Recommendation validation: validates (evidence: `app/services/upload_paper.py`)
- Upload orchestration → Prepared text: prepares text (evidence: `app/services/upload_paper.py`)
- Upload orchestration → Paper files: stores files (evidence: `app/services/upload_paper.py`)
- FastAPI routes → PDF discovery: finds PDFs (evidence: `app/api.py`)
- PDF discovery → Open-access sources: searches sources (evidence: `app/services/pdf_finder.py`)
- FastAPI routes → Repository queries: queries records (evidence: `app/api.py`)
- Repository queries → Paper and user models: uses models (evidence: `app/repositories/queries.py`)
- FastAPI routes → SQLite records: uses session (evidence: `app/api.py`)
- SQLite records → Paper and user models: maps tables (evidence: `app/database.py`)
- FastAPI routes → Search orchestration: dispatches search (evidence: `app/api.py`)
- Search orchestration → Pipeline weights: gets weights (evidence: `app/services/recommendation/search_service.py`)
- Search orchestration → TF-IDF scoring: scores candidates (evidence: `app/services/recommendation/search_service.py`)
- Search orchestration → S-BERT scoring: scores candidates (evidence: `app/services/recommendation/search_service.py`)
- Search orchestration → Metadata scoring: scores candidates (evidence: `app/services/recommendation/search_service.py`)
- Search orchestration → Paper and user models: loads candidates (evidence: `app/services/recommendation/search_service.py`)
- TF-IDF scoring → Similarity utilities: uses cosine (evidence: `app/services/recommendation/tfidf_pipeline.py`)
- S-BERT scoring → Similarity utilities: uses cosine (evidence: `app/services/recommendation/sbert_pipeline.py`)
- Metadata scoring → Similarity utilities: uses cosine (evidence: `app/services/recommendation/metadata_pipeline.py`)