# aisocietyiitj/papertrail architecture

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

- Interactive diagram: https://gitdiagram.com/aisocietyiitj/papertrail
- Repository: https://github.com/aisocietyiitj/papertrail

## Overview

PaperTrail exposes three research workflows: building foundational reading paths, matching researchers to academic profiles using a query and optional resume, and recommending papers. The sampled code supports the API-to-backend calls and the reading-path query’s Pinecone/Neo4j interactions; the README is empty, and several frontend routes and backend helpers were not sampled, so their internal wiring is left out.

Main entry points: [`main.py`](https://github.com/aisocietyiitj/papertrail/blob/main/main.py) (Use-case orchestration), [`frontend/papertraiFrontend/src/App.jsx`](https://github.com/aisocietyiitj/papertrail/blob/main/frontend/papertraiFrontend/src/App.jsx) (Application routes), [`src/usecase_1/query.py`](https://github.com/aisocietyiitj/papertrail/blob/main/src/usecase_1/query.py) (Path query), [`src/usecase_2/utils/vec_query_search.py`](https://github.com/aisocietyiitj/papertrail/blob/main/src/usecase_2/utils/vec_query_search.py) (Interest vector search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_app["Application routes<br/>[App.jsx]"]
  node_path_ui["Reading path view<br/>[ResearchPath.jsx]"]
  node_match_ui["Researcher match"]
  node_discovery_ui["Problem discovery"]
end

subgraph group_api["API and orchestration"]
  node_api["FastAPI endpoints<br/>[app.py]"]
  node_backend["Use-case orchestration<br/>[main.py]"]
  node_paper_rec["Paper recommendations<br/>[main.py]"]
  node_paper_clean["Recommendation preparation<br/>[Cleaning.py]"]
end

subgraph group_reading["Reading paths"]
  node_path_pipeline["Graph build pipeline<br/>[main.py]"]
  node_path_query["Path query<br/>[query.py]"]
  node_graph_ingest["Graph ingestion<br/>[ingest_neo4j.py]"]
  node_neo4j[("Research graph")]
  node_vector_search["Paper vector search<br/>[query.py]"]
  node_pinecone_papers[("Paper vectors")]
end

subgraph group_profiles["Academic profiles"]
  node_profile_setup["Profile setup<br/>[main.py]"]
  node_interest_extract["Interest extraction<br/>[extractor.py]"]
  node_profile_search["Interest vector search"]
  node_profile_lookup["Professor lookup<br/>[get_prof_info.py]"]
  node_profile_vectors[("Profile vectors")]
  node_profiles_graph[("Academic graph")]
  node_local_llm["Local language model"]
end

node_researcher(("Researcher"))

node_researcher -->|"uses"| node_app
node_app -->|"routes to"| node_path_ui
node_app -->|"routes to"| node_match_ui
node_app -->|"routes to"| node_discovery_ui
node_api -->|"calls"| node_backend
node_backend -->|"queries"| node_path_query
node_backend -->|"recommends"| node_paper_rec
node_backend -->|"extracts interests"| node_interest_extract
node_backend -->|"searches interests"| node_profile_search
node_backend -->|"looks up professors"| node_profile_lookup
node_backend -->|"runs setup"| node_profile_setup
node_path_pipeline -->|"ingests graph"| node_graph_ingest
node_graph_ingest -->|"writes nodes and edges"| node_neo4j
node_path_query -->|"embeds query"| node_vector_search
node_vector_search -->|"searches vectors"| node_pinecone_papers
node_path_query -->|"traverses prerequisites"| node_neo4j
node_profile_search -->|"searches vectors"| node_profile_vectors
node_profile_search -->|"embeds query"| node_local_llm
node_profile_lookup -->|"queries profiles"| node_profiles_graph
node_paper_rec -->|"uses"| node_paper_clean

click node_app "https://github.com/aisocietyiitj/papertrail/blob/main/frontend/papertraiFrontend/src/App.jsx"
click node_path_ui "https://github.com/aisocietyiitj/papertrail/blob/main/frontend/papertraiFrontend/src/routes/ResearchPath.jsx"
click node_match_ui "https://github.com/aisocietyiitj/papertrail/blob/main/frontend/papertraiFrontend/src/routes/ResearcherMatch.jsx"
click node_discovery_ui "https://github.com/aisocietyiitj/papertrail/blob/main/frontend/papertraiFrontend/src/routes/ProblemDiscovery.jsx"
click node_api "https://github.com/aisocietyiitj/papertrail/blob/main/app.py"
click node_backend "https://github.com/aisocietyiitj/papertrail/blob/main/main.py"
click node_paper_rec "https://github.com/aisocietyiitj/papertrail/blob/main/main.py"
click node_paper_clean "https://github.com/aisocietyiitj/papertrail/blob/main/src/usecase_3/Cleaning.py"
click node_path_pipeline "https://github.com/aisocietyiitj/papertrail/blob/main/src/usecase_1/main.py"
click node_path_query "https://github.com/aisocietyiitj/papertrail/blob/main/src/usecase_1/query.py"
click node_graph_ingest "https://github.com/aisocietyiitj/papertrail/blob/main/src/usecase_1/ingest_neo4j.py"
click node_vector_search "https://github.com/aisocietyiitj/papertrail/blob/main/src/usecase_1/query.py"
click node_profile_setup "https://github.com/aisocietyiitj/papertrail/blob/main/main.py"
click node_interest_extract "https://github.com/aisocietyiitj/papertrail/blob/main/src/usecase_2/local_llm/extractor.py"
click node_profile_search "https://github.com/aisocietyiitj/papertrail/blob/main/src/usecase_2/utils/vec_query_search.py"
click node_profile_lookup "https://github.com/aisocietyiitj/papertrail/blob/main/src/usecase_2/utils/get_prof_info.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_path_ui,node_match_ui,node_discovery_ui toneBlue
class node_api,node_backend,node_paper_rec,node_paper_clean toneAmber
class node_path_pipeline,node_path_query,node_graph_ingest,node_neo4j,node_vector_search,node_pinecone_papers toneMint
class node_profile_setup,node_interest_extract,node_profile_search,node_profile_lookup,node_profile_vectors,node_profiles_graph,node_local_llm toneRose
class node_researcher toneIndigo
```

## Components

### Web application

- [Application routes](https://github.com/aisocietyiitj/papertrail/blob/main/frontend/papertraiFrontend/src/App.jsx): `frontend/papertraiFrontend/src/App.jsx`
- [Reading path view](https://github.com/aisocietyiitj/papertrail/blob/main/frontend/papertraiFrontend/src/routes/ResearchPath.jsx): `frontend/papertraiFrontend/src/routes/ResearchPath.jsx`
- [Researcher match](https://github.com/aisocietyiitj/papertrail/blob/main/frontend/papertraiFrontend/src/routes/ResearcherMatch.jsx): `frontend/papertraiFrontend/src/routes/ResearcherMatch.jsx`
- [Problem discovery](https://github.com/aisocietyiitj/papertrail/blob/main/frontend/papertraiFrontend/src/routes/ProblemDiscovery.jsx): `frontend/papertraiFrontend/src/routes/ProblemDiscovery.jsx`

### API and orchestration

- [FastAPI endpoints](https://github.com/aisocietyiitj/papertrail/blob/main/app.py): `app.py`
- [Use-case orchestration](https://github.com/aisocietyiitj/papertrail/blob/main/main.py): `main.py`
- [Paper recommendations](https://github.com/aisocietyiitj/papertrail/blob/main/main.py): `main.py`
- [Recommendation preparation](https://github.com/aisocietyiitj/papertrail/blob/main/src/usecase_3/Cleaning.py): `src/usecase_3/Cleaning.py`

### Reading paths

- [Graph build pipeline](https://github.com/aisocietyiitj/papertrail/blob/main/src/usecase_1/main.py): `src/usecase_1/main.py`
- [Path query](https://github.com/aisocietyiitj/papertrail/blob/main/src/usecase_1/query.py): `src/usecase_1/query.py`
- [Graph ingestion](https://github.com/aisocietyiitj/papertrail/blob/main/src/usecase_1/ingest_neo4j.py): `src/usecase_1/ingest_neo4j.py`
- **Research graph**
- [Paper vector search](https://github.com/aisocietyiitj/papertrail/blob/main/src/usecase_1/query.py): `src/usecase_1/query.py`
- **Paper vectors**

### Academic profiles

- [Profile setup](https://github.com/aisocietyiitj/papertrail/blob/main/main.py): `main.py`
- [Interest extraction](https://github.com/aisocietyiitj/papertrail/blob/main/src/usecase_2/local_llm/extractor.py): `src/usecase_2/local_llm/extractor.py`
- [Interest vector search](https://github.com/aisocietyiitj/papertrail/blob/main/src/usecase_2/utils/vec_query_search.py): `src/usecase_2/utils/vec_query_search.py`
- [Professor lookup](https://github.com/aisocietyiitj/papertrail/blob/main/src/usecase_2/utils/get_prof_info.py): `src/usecase_2/utils/get_prof_info.py`
- **Profile vectors**
- **Academic graph**
- **Local language model**

### Other components

- **Researcher**

## Connections

- Researcher → Application routes: uses
- Application routes → Reading path view: routes to
- Application routes → Researcher match: routes to
- Application routes → Problem discovery: routes to
- FastAPI endpoints → Use-case orchestration: calls
- Use-case orchestration → Path query: queries
- Use-case orchestration → Paper recommendations: recommends
- Use-case orchestration → Interest extraction: extracts interests
- Use-case orchestration → Interest vector search: searches interests
- Use-case orchestration → Professor lookup: looks up professors
- Use-case orchestration → Profile setup: runs setup
- Graph build pipeline → Graph ingestion: ingests graph
- Graph ingestion → Research graph: writes nodes and edges
- Path query → Paper vector search: embeds query
- Paper vector search → Paper vectors: searches vectors
- Path query → Research graph: traverses prerequisites
- Interest vector search → Profile vectors: searches vectors
- Interest vector search → Local language model: embeds query
- Professor lookup → Academic graph: queries profiles
- Paper recommendations → Recommendation preparation: uses