# sha5hank007/citation-atlas_project architecture

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

- Interactive diagram: https://gitdiagram.com/sha5hank007/citation-atlas_project
- Repository: https://github.com/sha5hank007/citation-atlas_project

## Overview

#### Purpose and Entry Points
Citation Atlas is a local interactive research-exploration system: it discovers papers for a topic, constructs a citation graph, indexes paper text for retrieval, and answers questions constrained to retrieved content. The FastAPI application is launched through `backend/server.py`; backend orchestration likely begins in `backend/main.py`. The browser client is a static HTML/D3 interface rooted at `frontend/index.html`.

#### API and Application Boundary
`backend/server.py` exposes the HTTP boundary between the UI and Python services. `frontend/index.html` provides the research/QA interface, while `frontend/graph.js` renders and interacts with graph data. Backend responses must provide graph-compatible paper/node/edge data and support question requests scoped to selected papers.

#### Discovery and Query Expansion
Topic input is expanded before retrieval in `backend/query/expander.py`. Seed-paper discovery is handled by the ArXiv adapter at `backend/harvester/arxiv.py`; citation/reference metadata comes from `backend/harvester/semantic_scholar.py`. These are external-service boundaries: ArXiv is preferred for accessible source PDFs, while Semantic Scholar supplies relationships needed to grow the graph.

#### Paper Acquisition and Content Preparation
`backend/papers/download.py` is the document-acquisition boundary, obtaining PDFs with the ArXiv-first strategy and fallback behavior. Downloaded documents feed the RAG pipeline in `backend/rag/pipeline.py`, which is responsible for PDF text extraction, chunking, embedding, and indexing. This stage depends materially on PyMuPDF, SentenceTransformers MiniLM embeddings, and ChromaDB persistence/query capabilities.

#### Citation Graph Construction
`backend/graph/builder.py` creates the in-memory citation graph, expected to model papers as nodes and citations as directed relationships. `backend/graph/roles.py` assigns graph-derived roles or importance classifications, and `backend/graph/exporter.py` serializes the graph into frontend-consumable data. NetworkX is the core graph runtime; graph construction is separated from visualization so the browser does not need direct access to harvesting or document processing.

#### Retrieval-Augmented Question Answering
`backend/rag/query.py` performs retrieval against the indexed paper chunks, including paper-level filtering for questions asked against user-selected graph nodes. `backend/rag/pipeline.py` owns index preparation, while retrieval results are passed to an LLM client rather than allowing an LLM to answer from ungrounded knowledge. This creates the main quality boundary: source chunks retrieved from local vector storage are the context for generated answers.

#### LLM Provider Abstraction and Runtime Configuration
`backend/llm/client.py` provides a provider-neutral LLM boundary, delegating to `backend/llm/groq_client.py`, `backend/llm/gemini_client.py`, or `backend/llm/openrouter_client.py`. `backend/config.py` selects the configured provider and reads required API credentials. The application therefore combines local Python/FastAPI, NetworkX, ChromaDB, and embedding execution with remote ArXiv, Semantic Scholar, and configurable LLM APIs.

Main entry points: [`backend/llm/client.py`](https://github.com/sha5hank007/citation-atlas_project/blob/main/backend/llm/client.py) (LLM abstraction), [`backend/main.py`](https://github.com/sha5hank007/citation-atlas_project/blob/main/backend/main.py) (Application orchestrator), [`backend/server.py`](https://github.com/sha5hank007/citation-atlas_project/blob/main/backend/server.py) (HTTP server), [`backend/harvester/arxiv.py`](https://github.com/sha5hank007/citation-atlas_project/blob/main/backend/harvester/arxiv.py) (ArXiv discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Browser UI"]
  node_frontend["Research interface<br/>static HTML/D3<br/>[index.html]"]
  node_graph_ui["Graph interaction<br/>D3 client<br/>[graph.js]"]
end

subgraph group_api["Application API"]
  node_server{{"HTTP server<br/>FastAPI<br/>[server.py]"}}
  node_main["Application orchestrator<br/>Python service<br/>[main.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
end

subgraph group_discovery["Discovery &amp; Graph"]
  node_query_expander["Topic expansion<br/>query service<br/>[expander.py]"]
  node_arxiv["ArXiv discovery<br/>harvester adapter<br/>[arxiv.py]"]
  node_semantic_scholar["Citation metadata<br/>harvester adapter"]
  node_graph_builder["Citation graph builder<br/>NetworkX graph<br/>[builder.py]"]
  node_graph_roles["Graph roles<br/>graph analysis<br/>[roles.py]"]
  node_graph_exporter["Graph exporter<br/>serialization<br/>[exporter.py]"]
end

subgraph group_rag["Local RAG"]
  node_downloader["PDF acquisition<br/>document downloader<br/>[download.py]"]
  node_rag_pipeline["Index preparation<br/>RAG pipeline<br/>[pipeline.py]"]
  node_vector_store[("Paper chunk index<br/>ChromaDB")]
  node_rag_query["Scoped retrieval<br/>RAG query<br/>[query.py]"]
end

subgraph group_llm["LLM Providers"]
  node_llm_client["LLM abstraction<br/>provider-neutral client<br/>[client.py]"]
  node_groq["Groq provider<br/>LLM adapter<br/>[groq_client.py]"]
  node_gemini["Gemini provider<br/>LLM adapter<br/>[gemini_client.py]"]
  node_openrouter["OpenRouter provider<br/>LLM adapter"]
end

node_frontend -->|"loads"| node_graph_ui
node_graph_ui -->|"graph and question requests"| node_server
node_server -->|"delegates"| node_main
node_main -->|"expands topic"| node_query_expander
node_query_expander -->|"search query"| node_arxiv
node_main -->|"citation lookup"| node_semantic_scholar
node_arxiv -->|"seed papers"| node_graph_builder
node_semantic_scholar -->|"citation metadata"| node_graph_builder
node_graph_builder -->|"graph metrics"| node_graph_roles
node_graph_roles -->|"annotated graph"| node_graph_exporter
node_graph_exporter -->|"node/edge payload"| node_server
node_arxiv -->|"paper sources"| node_downloader
node_downloader -->|"PDFs"| node_rag_pipeline
node_rag_pipeline -->|"embeddings and chunks"| node_vector_store
node_main -->|"question and selected papers"| node_rag_query
node_rag_query -->|"filtered similarity search"| node_vector_store
node_rag_query -->|"retrieved source context"| node_llm_client
node_llm_client -.->|"configured provider"| node_groq
node_llm_client -.->|"configured provider"| node_gemini
node_llm_client -.->|"configured provider"| node_openrouter
node_config -->|"provider and credentials"| node_llm_client
node_llm_client -->|"grounded answer"| node_server

click node_frontend "https://github.com/sha5hank007/citation-atlas_project/blob/main/frontend/index.html"
click node_graph_ui "https://github.com/sha5hank007/citation-atlas_project/blob/main/frontend/graph.js"
click node_server "https://github.com/sha5hank007/citation-atlas_project/blob/main/backend/server.py"
click node_main "https://github.com/sha5hank007/citation-atlas_project/blob/main/backend/main.py"
click node_query_expander "https://github.com/sha5hank007/citation-atlas_project/blob/main/backend/query/expander.py"
click node_arxiv "https://github.com/sha5hank007/citation-atlas_project/blob/main/backend/harvester/arxiv.py"
click node_semantic_scholar "https://github.com/sha5hank007/citation-atlas_project/blob/main/backend/harvester/semantic_scholar.py"
click node_graph_builder "https://github.com/sha5hank007/citation-atlas_project/blob/main/backend/graph/builder.py"
click node_graph_roles "https://github.com/sha5hank007/citation-atlas_project/blob/main/backend/graph/roles.py"
click node_graph_exporter "https://github.com/sha5hank007/citation-atlas_project/blob/main/backend/graph/exporter.py"
click node_downloader "https://github.com/sha5hank007/citation-atlas_project/blob/main/backend/papers/download.py"
click node_rag_pipeline "https://github.com/sha5hank007/citation-atlas_project/blob/main/backend/rag/pipeline.py"
click node_rag_query "https://github.com/sha5hank007/citation-atlas_project/blob/main/backend/rag/query.py"
click node_llm_client "https://github.com/sha5hank007/citation-atlas_project/blob/main/backend/llm/client.py"
click node_groq "https://github.com/sha5hank007/citation-atlas_project/blob/main/backend/llm/groq_client.py"
click node_gemini "https://github.com/sha5hank007/citation-atlas_project/blob/main/backend/llm/gemini_client.py"
click node_openrouter "https://github.com/sha5hank007/citation-atlas_project/blob/main/backend/llm/openrouter_client.py"
click node_config "https://github.com/sha5hank007/citation-atlas_project/blob/main/backend/config.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_frontend,node_graph_ui toneBlue
class node_server,node_main,node_config toneAmber
class node_query_expander,node_arxiv,node_semantic_scholar,node_graph_builder,node_graph_roles,node_graph_exporter toneMint
class node_downloader,node_rag_pipeline,node_vector_store,node_rag_query toneRose
class node_llm_client,node_groq,node_gemini,node_openrouter toneIndigo
```

## Components

### Browser UI

- [Research interface](https://github.com/sha5hank007/citation-atlas_project/blob/main/frontend/index.html): static HTML/D3 · `frontend/index.html`
- [Graph interaction](https://github.com/sha5hank007/citation-atlas_project/blob/main/frontend/graph.js): D3 client · `frontend/graph.js`

### Application API

- [HTTP server](https://github.com/sha5hank007/citation-atlas_project/blob/main/backend/server.py): FastAPI · Exposes graph and scoped question endpoints. · `backend/server.py`
- [Application orchestrator](https://github.com/sha5hank007/citation-atlas_project/blob/main/backend/main.py): Python service · `backend/main.py`
- [Runtime configuration](https://github.com/sha5hank007/citation-atlas_project/blob/main/backend/config.py): configuration · Selects LLM provider and credentials. · `backend/config.py`

### Discovery & Graph

- [Topic expansion](https://github.com/sha5hank007/citation-atlas_project/blob/main/backend/query/expander.py): query service · `backend/query/expander.py`
- [ArXiv discovery](https://github.com/sha5hank007/citation-atlas_project/blob/main/backend/harvester/arxiv.py): harvester adapter · Finds seed papers and accessible source PDFs. · `backend/harvester/arxiv.py`
- [Citation metadata](https://github.com/sha5hank007/citation-atlas_project/blob/main/backend/harvester/semantic_scholar.py): harvester adapter · Supplies citation and reference relationships. · `backend/harvester/semantic_scholar.py`
- [Citation graph builder](https://github.com/sha5hank007/citation-atlas_project/blob/main/backend/graph/builder.py): NetworkX graph · Builds directed paper and citation relationships in memory. · `backend/graph/builder.py`
- [Graph roles](https://github.com/sha5hank007/citation-atlas_project/blob/main/backend/graph/roles.py): graph analysis · `backend/graph/roles.py`
- [Graph exporter](https://github.com/sha5hank007/citation-atlas_project/blob/main/backend/graph/exporter.py): serialization · Produces browser-compatible nodes and edges. · `backend/graph/exporter.py`

### Local RAG

- [PDF acquisition](https://github.com/sha5hank007/citation-atlas_project/blob/main/backend/papers/download.py): document downloader · Uses ArXiv-first download with fallback behavior. · `backend/papers/download.py`
- [Index preparation](https://github.com/sha5hank007/citation-atlas_project/blob/main/backend/rag/pipeline.py): RAG pipeline · Extracts PDF text, chunks, embeds, and indexes papers. · `backend/rag/pipeline.py`
- **Paper chunk index**: ChromaDB · Persistent local vector storage for paper chunks.
- [Scoped retrieval](https://github.com/sha5hank007/citation-atlas_project/blob/main/backend/rag/query.py): RAG query · Retrieves chunks with selected-paper filtering. · `backend/rag/query.py`

### LLM Providers

- [LLM abstraction](https://github.com/sha5hank007/citation-atlas_project/blob/main/backend/llm/client.py): provider-neutral client · `backend/llm/client.py`
- [Groq provider](https://github.com/sha5hank007/citation-atlas_project/blob/main/backend/llm/groq_client.py): LLM adapter · `backend/llm/groq_client.py`
- [Gemini provider](https://github.com/sha5hank007/citation-atlas_project/blob/main/backend/llm/gemini_client.py): LLM adapter · `backend/llm/gemini_client.py`
- [OpenRouter provider](https://github.com/sha5hank007/citation-atlas_project/blob/main/backend/llm/openrouter_client.py): LLM adapter · `backend/llm/openrouter_client.py`

## Connections

- Research interface → Graph interaction: loads
- Graph interaction → HTTP server: graph and question requests
- HTTP server → Application orchestrator: delegates
- Application orchestrator → Topic expansion: expands topic
- Topic expansion → ArXiv discovery: search query
- Application orchestrator → Citation metadata: citation lookup
- ArXiv discovery → Citation graph builder: seed papers
- Citation metadata → Citation graph builder: citation metadata
- Citation graph builder → Graph roles: graph metrics
- Graph roles → Graph exporter: annotated graph
- Graph exporter → HTTP server: node/edge payload
- ArXiv discovery → PDF acquisition: paper sources
- PDF acquisition → Index preparation: PDFs
- Index preparation → Paper chunk index: embeddings and chunks
- Application orchestrator → Scoped retrieval: question and selected papers
- Scoped retrieval → Paper chunk index: filtered similarity search
- Scoped retrieval → LLM abstraction: retrieved source context
- LLM abstraction → Groq provider: configured provider
- LLM abstraction → Gemini provider: configured provider
- LLM abstraction → OpenRouter provider: configured provider
- Runtime configuration → LLM abstraction: provider and credentials
- LLM abstraction → HTTP server: grounded answer