# hitagiiii/thesis-recommendation-system architecture

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

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

## Overview

This is a locally deployed academic-paper repository and recommendation system. Users browse or import papers, extract and validate metadata, store PDFs and records, then search the repository or request ranked recommendations from a query or seed paper. The backend is FastAPI/SQLAlchemy over SQLite; the React frontend exposes repository, library, upload, recommendation, and evaluation workflows. Recommendation search combines configured TF-IDF, S-BERT, and metadata scores. Several frontend and backend subsystems are represented from README capabilities and the file tree; their internal wiring is not asserted where source excerpts do not show it.

Main entry points: [`app/api.py`](https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/api.py) (Paper API), [`app/models/models.py`](https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/models/models.py) (Paper records), [`app/services/recommendation/search_service.py`](https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/services/recommendation/search_service.py) (Recommendation search), [`frontend/src/App.tsx`](https://github.com/hitagiiii/thesis-recommendation-system/blob/main/frontend/src/App.tsx) (Web interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_web_ui["Web interface<br/>[App.tsx]"]
  node_repo_pages["Repository workflows"]
  node_recommend_pages["Recommendation pages"]
  node_lab_page["Pipeline lab<br/>[Lab.tsx]"]
  node_frontend_api["HTTP client<br/>[api.ts]"]
end

subgraph group_repository["Paper repository"]
  node_paper_api["Paper API<br/>[api.py]"]
  node_bib_import["BibTeX extraction<br/>[bib_extraction.py]"]
  node_paper_extraction["PDF extraction<br/>[extraction.py]"]
  node_validation["Recommendation validation<br/>[validation.py]"]
  node_classification["Subject classification<br/>[classification.py]"]
  node_pdf_finder["Open-access PDF finder<br/>[pdf_finder.py]"]
  node_search["Repository search<br/>[fts_search.py]"]
  node_queries["Repository queries<br/>[queries.py]"]
end

subgraph group_recommend["Recommendation engine"]
  node_text_prep["Text preparation"]
  node_rec_search["Recommendation search<br/>[search_service.py]"]
  node_tfidf["TF-IDF pipeline<br/>[tfidf_pipeline.py]"]
  node_sbert["S-BERT pipeline<br/>[sbert_pipeline.py]"]
  node_metadata_score["Metadata scoring"]
  node_pipeline_config["Pipeline weights<br/>[pipeline_config.py]"]
  node_vector_index[("Vector index<br/>[vector_index.py]")]
end

subgraph group_persistence["Data and storage"]
  node_paper_store[("Paper records<br/>[models.py]")]
  node_database[("SQLite database<br/>[database.py]")]
  node_file_storage[("Uploaded files<br/>[storage.py]")]
end

subgraph group_research["Research features"]
  node_evaluation["Evaluation runner<br/>[runner.py]"]
  node_research_chat["Research help chat<br/>[research_chat.py]"]
  node_pixel_pet["Pixel pet and hunt<br/>[PixelPet.tsx]"]
end

node_researcher(("Researcher"))
node_external_sources{{"Online paper sources"}}

node_researcher -->|"uses"| node_web_ui
node_web_ui -->|"routes to"| node_repo_pages
node_web_ui -->|"routes to"| node_recommend_pages
node_web_ui -->|"routes to"| node_lab_page
node_repo_pages -->|"requests data"| node_frontend_api
node_recommend_pages -.->|"requests data"| node_frontend_api
node_frontend_api -.->|"HTTP requests"| node_paper_api
node_paper_api -->|"uses sessions"| node_database
node_database -->|"maps records"| node_paper_store
node_paper_api -->|"queries papers"| node_queries
node_paper_api -->|"imports citations"| node_bib_import
node_paper_api -->|"extracts metadata"| node_paper_extraction
node_paper_api -->|"validates records"| node_validation
node_paper_api -->|"classifies papers"| node_classification
node_paper_api -.->|"finds PDFs"| node_pdf_finder
node_paper_api -->|"searches records"| node_search
node_paper_api -.->|"stores uploads"| node_file_storage
node_paper_extraction -->|"populates metadata"| node_paper_store
node_bib_import -->|"imports metadata"| node_paper_store
node_pdf_finder -.->|"searches online"| node_external_sources
node_queries -->|"reads records"| node_paper_store
node_search -.->|"searches records"| node_paper_store
node_paper_api -.->|"requests recommendations"| node_rec_search
node_rec_search -->|"prepares query text"| node_text_prep
node_rec_search -->|"scores lexical"| node_tfidf
node_rec_search -->|"scores semantic"| node_sbert
node_rec_search -->|"scores metadata"| node_metadata_score
node_rec_search -->|"loads weights"| node_pipeline_config
node_rec_search -->|"selects candidates"| node_paper_store
node_tfidf -->|"uses vectors"| node_vector_index
node_sbert -->|"uses embeddings"| node_vector_index
node_tfidf -->|"reads corpus"| node_paper_store
node_sbert -->|"reads corpus"| node_paper_store
node_metadata_score -->|"scores fields"| node_paper_store
node_lab_page -.->|"sends recipe"| node_frontend_api
node_researcher -->|"interacts"| node_pixel_pet
node_recommend_pages -.->|"evaluates results"| node_evaluation
node_paper_api -.->|"answers help queries"| node_research_chat

click node_web_ui "https://github.com/hitagiiii/thesis-recommendation-system/blob/main/frontend/src/App.tsx"
click node_repo_pages "https://github.com/hitagiiii/thesis-recommendation-system/tree/main/frontend/src/pages/repository"
click node_recommend_pages "https://github.com/hitagiiii/thesis-recommendation-system/tree/main/frontend/src/pages/evaluation"
click node_lab_page "https://github.com/hitagiiii/thesis-recommendation-system/blob/main/frontend/src/pages/lab/Lab.tsx"
click node_frontend_api "https://github.com/hitagiiii/thesis-recommendation-system/blob/main/frontend/src/api.ts"
click node_paper_api "https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/api.py"
click node_bib_import "https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/services/bib_extraction.py"
click node_paper_extraction "https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/services/extraction.py"
click node_validation "https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/services/validation.py"
click node_classification "https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/services/classification.py"
click node_pdf_finder "https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/services/pdf_finder.py"
click node_search "https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/services/fts_search.py"
click node_queries "https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/repositories/queries.py"
click node_paper_store "https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/models/models.py"
click node_database "https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/database.py"
click node_file_storage "https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/services/storage.py"
click node_text_prep "https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/services/text_preparation.py"
click node_rec_search "https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/services/recommendation/search_service.py"
click node_tfidf "https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/services/recommendation/tfidf_pipeline.py"
click node_sbert "https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/services/recommendation/sbert_pipeline.py"
click node_metadata_score "https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/services/recommendation/metadata_pipeline.py"
click node_pipeline_config "https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/services/recommendation/pipeline_config.py"
click node_vector_index "https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/services/recommendation/vector_index.py"
click node_evaluation "https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/services/evaluation/runner.py"
click node_research_chat "https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/services/research_chat.py"
click node_pixel_pet "https://github.com/hitagiiii/thesis-recommendation-system/blob/main/frontend/src/components/retro/PixelPet.tsx"

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_web_ui,node_repo_pages,node_recommend_pages,node_lab_page,node_frontend_api toneBlue
class node_paper_api,node_bib_import,node_paper_extraction,node_validation,node_classification,node_pdf_finder,node_search,node_queries toneAmber
class node_text_prep,node_rec_search,node_tfidf,node_sbert,node_metadata_score,node_pipeline_config,node_vector_index toneMint
class node_paper_store,node_database,node_file_storage toneRose
class node_evaluation,node_research_chat,node_pixel_pet,node_researcher,node_external_sources toneIndigo
```

## Components

### Web application

- [Web interface](https://github.com/hitagiiii/thesis-recommendation-system/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Repository workflows](https://github.com/hitagiiii/thesis-recommendation-system/tree/main/frontend/src/pages/repository): `frontend/src/pages/repository`
- [Recommendation pages](https://github.com/hitagiiii/thesis-recommendation-system/tree/main/frontend/src/pages/evaluation): `frontend/src/pages/evaluation`
- [Pipeline lab](https://github.com/hitagiiii/thesis-recommendation-system/blob/main/frontend/src/pages/lab/Lab.tsx): `frontend/src/pages/lab/Lab.tsx`
- [HTTP client](https://github.com/hitagiiii/thesis-recommendation-system/blob/main/frontend/src/api.ts): `frontend/src/api.ts`

### Paper repository

- [Paper API](https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/api.py): `app/api.py`
- [BibTeX extraction](https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/services/bib_extraction.py): `app/services/bib_extraction.py`
- [PDF extraction](https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/services/extraction.py): `app/services/extraction.py`
- [Recommendation validation](https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/services/validation.py): `app/services/validation.py`
- [Subject classification](https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/services/classification.py): `app/services/classification.py`
- [Open-access PDF finder](https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/services/pdf_finder.py): `app/services/pdf_finder.py`
- [Repository search](https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/services/fts_search.py): `app/services/fts_search.py`
- [Repository queries](https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/repositories/queries.py): `app/repositories/queries.py`

### Recommendation engine

- [Text preparation](https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/services/text_preparation.py): `app/services/text_preparation.py`
- [Recommendation search](https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/services/recommendation/search_service.py): `app/services/recommendation/search_service.py`
- [TF-IDF pipeline](https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/services/recommendation/tfidf_pipeline.py): `app/services/recommendation/tfidf_pipeline.py`
- [S-BERT pipeline](https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/services/recommendation/sbert_pipeline.py): `app/services/recommendation/sbert_pipeline.py`
- [Metadata scoring](https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/services/recommendation/metadata_pipeline.py): `app/services/recommendation/metadata_pipeline.py`
- [Pipeline weights](https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/services/recommendation/pipeline_config.py): `app/services/recommendation/pipeline_config.py`
- [Vector index](https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/services/recommendation/vector_index.py): `app/services/recommendation/vector_index.py`

### Data and storage

- [Paper records](https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/models/models.py): `app/models/models.py`
- [SQLite database](https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/database.py): `app/database.py`
- [Uploaded files](https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/services/storage.py): `app/services/storage.py`

### Research features

- [Evaluation runner](https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/services/evaluation/runner.py): `app/services/evaluation/runner.py`
- [Research help chat](https://github.com/hitagiiii/thesis-recommendation-system/blob/main/app/services/research_chat.py): `app/services/research_chat.py`
- [Pixel pet and hunt](https://github.com/hitagiiii/thesis-recommendation-system/blob/main/frontend/src/components/retro/PixelPet.tsx): `frontend/src/components/retro/PixelPet.tsx`

### Other components

- **Researcher**
- **Online paper sources**

## Connections

- Researcher → Web interface: uses
- Web interface → Repository workflows: routes to (evidence: `frontend/src/App.tsx`)
- Web interface → Recommendation pages: routes to (evidence: `frontend/src/App.tsx`)
- Web interface → Pipeline lab: routes to (evidence: `frontend/src/App.tsx`)
- Repository workflows → HTTP client: requests data (evidence: `frontend/src/pages/repository/Repository.tsx`)
- Recommendation pages → HTTP client: requests data
- HTTP client → Paper API: HTTP requests
- Paper API → SQLite database: uses sessions (evidence: `app/api.py`)
- SQLite database → Paper records: maps records (evidence: `app/database.py`)
- Paper API → Repository queries: queries papers (evidence: `app/api.py`)
- Paper API → BibTeX extraction: imports citations (evidence: `app/api.py`)
- Paper API → PDF extraction: extracts metadata (evidence: `app/api.py`)
- Paper API → Recommendation validation: validates records (evidence: `app/api.py`)
- Paper API → Subject classification: classifies papers (evidence: `app/api.py`)
- Paper API → Open-access PDF finder: finds PDFs (evidence: `app/api.py`)
- Paper API → Repository search: searches records (evidence: `app/api.py`)
- Paper API → Uploaded files: stores uploads (evidence: `app/api.py`)
- PDF extraction → Paper records: populates metadata
- BibTeX extraction → Paper records: imports metadata
- Open-access PDF finder → Online paper sources: searches online
- Repository queries → Paper records: reads records (evidence: `app/repositories/queries.py`)
- Repository search → Paper records: searches records
- Paper API → Recommendation search: requests recommendations (evidence: `app/api.py`)
- Recommendation search → Text preparation: prepares query text (evidence: `app/services/recommendation/search_service.py`)
- Recommendation search → TF-IDF pipeline: scores lexical (evidence: `app/services/recommendation/search_service.py`)
- Recommendation search → S-BERT pipeline: scores semantic (evidence: `app/services/recommendation/search_service.py`)
- Recommendation search → Metadata scoring: scores metadata (evidence: `app/services/recommendation/search_service.py`)
- Recommendation search → Pipeline weights: loads weights (evidence: `app/services/recommendation/search_service.py`)
- Recommendation search → Paper records: selects candidates (evidence: `app/services/recommendation/search_service.py`)
- TF-IDF pipeline → Vector index: uses vectors (evidence: `app/services/recommendation/tfidf_pipeline.py`)
- S-BERT pipeline → Vector index: uses embeddings (evidence: `app/services/recommendation/sbert_pipeline.py`)
- TF-IDF pipeline → Paper records: reads corpus (evidence: `app/services/recommendation/tfidf_pipeline.py`)
- S-BERT pipeline → Paper records: reads corpus (evidence: `app/services/recommendation/sbert_pipeline.py`)
- Metadata scoring → Paper records: scores fields (evidence: `app/services/recommendation/metadata_pipeline.py`)
- Pipeline lab → HTTP client: sends recipe
- Researcher → Pixel pet and hunt: interacts
- Recommendation pages → Evaluation runner: evaluates results
- Paper API → Research help chat: answers help queries (evidence: `app/api.py`)
