sha5hank007/citation-atlas_project

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.