# shrey-cs-ai/orbirag_app architecture

> Architecture diagram of the GitHub repository shrey-cs-ai/orbirag_app, 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/shrey-cs-ai/orbirag_app
- Repository: https://github.com/shrey-cs-ai/orbirag_app

## Overview

This repository implements Orbirag/Scholar Pulse, an academic research assistant with chat, literature search, paper management, citations, notes, methodology extraction, plagiarism analysis, and writing tools. A user’s research workflow enters the research API, which can search literature and save papers; separate chat and document routes support conversational answers and PDF Q&A. The research backend also exposes distinct research utilities and persistence services. Edges reflect shown calls, imports recorded in the SOURCE INDEX, or explicit service behavior; frontend application sources and some backend route details were not provided.

Main entry points: [`backend/backend_research/main.py`](https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_research/main.py) (Research API), [`backend/backend_chat/main.py`](https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_chat/main.py) (Chat API), [`backend/backend_research/services/rag_service.py`](https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_research/services/rag_service.py) (Document RAG), [`backend/backend_research/vector_store.py`](https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_research/vector_store.py) (Vector store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API entrypoints"]
  node_research_api["Research API<br/>[main.py]"]
  node_chat_api["Chat API<br/>[main.py]"]
  node_contracts["API contracts<br/>[schemas.py]"]
  node_chat_contracts["Chat contracts<br/>[models.py]"]
end

subgraph group_research["Research workflow"]
  node_literature_search["Literature search<br/>[search_service.py]"]
  node_library["Paper library<br/>[library_service.py]"]
  node_citations["Citation tools"]
  node_methodology["Methodology extraction"]
  node_plagiarism["Plagiarism tools"]
  node_notes["Research notes<br/>[notes_service.py]"]
  node_rag["Document RAG<br/>[rag_service.py]"]
  node_pdf["PDF processing<br/>[pdf_service.py]"]
end

subgraph group_assist["AI assistance"]
  node_embeddings["Embedding service"]
  node_chat_ai["AI chat service<br/>[ai_service.py]"]
  node_voice["Voice transcription"]
  node_word_counter["Text analysis"]
end

subgraph group_data["Persistence and identity"]
  node_vector_store[("Vector store<br/>[vector_store.py]")]
  node_database[("SQL database access<br/>[database.py]")]
  node_db_queries["Research queries<br/>[db_queries.py]"]
  node_user_service["User management<br/>[user_service.py]"]
  node_auth["Token verification<br/>[auth_service.py]"]
end

node_semantic_scholar(("Semantic Scholar"))
node_gemini(("Gemini"))
node_deepgram(("Deepgram"))
node_firebase(("Firebase Auth"))
node_postgres[("PostgreSQL")]
node_duckdb[("DuckDB VSS")]

node_research_api -->|"searches with"| node_literature_search
node_literature_search -->|"queries"| node_semantic_scholar
node_research_api -->|"manages papers"| node_library
node_research_api -->|"routes citation work"| node_citations
node_research_api -->|"requests extraction"| node_methodology
node_research_api -->|"runs checks"| node_plagiarism
node_research_api -->|"manages notes"| node_notes
node_research_api -->|"routes document Q&amp;A"| node_rag
node_research_api -->|"saves records"| node_db_queries
node_research_api -->|"manages users"| node_user_service
node_research_api -->|"opens sessions"| node_database
node_rag -->|"indexes and searches"| node_vector_store
node_rag -->|"asks with context"| node_chat_ai
node_vector_store -->|"uses embeddings"| node_embeddings
node_vector_store -->|"stores vectors"| node_duckdb
node_chat_api -->|"gets responses"| node_chat_ai
node_chat_api -->|"transcribes audio"| node_voice
node_chat_api -->|"extracts PDF text"| node_pdf
node_chat_api -->|"builds statistics"| node_word_counter
node_chat_ai -->|"generates answers"| node_gemini
node_voice -->|"transcribes audio"| node_deepgram
node_auth -->|"verifies tokens"| node_firebase
node_database -->|"connects to"| node_postgres
node_research_api -->|"uses schemas"| node_contracts
node_chat_api -->|"uses models"| node_chat_contracts

click node_research_api "https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_research/main.py"
click node_chat_api "https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_chat/main.py"
click node_contracts "https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_research/schemas.py"
click node_chat_contracts "https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_chat/models.py"
click node_literature_search "https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_research/services/search_service.py"
click node_library "https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_research/services/library_service.py"
click node_citations "https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_research/services/citation_service.py"
click node_methodology "https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_research/services/methodology_service.py"
click node_plagiarism "https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_research/services/plagiarism_service.py"
click node_notes "https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_research/services/notes_service.py"
click node_rag "https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_research/services/rag_service.py"
click node_vector_store "https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_research/vector_store.py"
click node_embeddings "https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_research/services/embedding_service.py"
click node_database "https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_research/database.py"
click node_db_queries "https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_research/db_queries.py"
click node_user_service "https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_research/services/user_service.py"
click node_chat_ai "https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_chat/services/ai_service.py"
click node_auth "https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_chat/services/auth_service.py"
click node_voice "https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_chat/services/deepgram_service.py"
click node_pdf "https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_chat/services/pdf_service.py"
click node_word_counter "https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_chat/services/word_counter_service.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_research_api,node_chat_api,node_contracts,node_chat_contracts toneBlue
class node_literature_search,node_library,node_citations,node_methodology,node_plagiarism,node_notes,node_rag,node_pdf,node_postgres,node_duckdb toneAmber
class node_embeddings,node_chat_ai,node_voice,node_word_counter toneMint
class node_vector_store,node_database,node_db_queries,node_user_service,node_auth toneRose
class node_semantic_scholar,node_gemini,node_deepgram,node_firebase toneIndigo
```

## Components

### API entrypoints

- [Research API](https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_research/main.py): `backend/backend_research/main.py`
- [Chat API](https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_chat/main.py): `backend/backend_chat/main.py`
- [API contracts](https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_research/schemas.py): `backend/backend_research/schemas.py`
- [Chat contracts](https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_chat/models.py): `backend/backend_chat/models.py`

### Research workflow

- [Literature search](https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_research/services/search_service.py): `backend/backend_research/services/search_service.py`
- [Paper library](https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_research/services/library_service.py): `backend/backend_research/services/library_service.py`
- [Citation tools](https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_research/services/citation_service.py): `backend/backend_research/services/citation_service.py`
- [Methodology extraction](https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_research/services/methodology_service.py): `backend/backend_research/services/methodology_service.py`
- [Plagiarism tools](https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_research/services/plagiarism_service.py): `backend/backend_research/services/plagiarism_service.py`
- [Research notes](https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_research/services/notes_service.py): `backend/backend_research/services/notes_service.py`
- [Document RAG](https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_research/services/rag_service.py): `backend/backend_research/services/rag_service.py`
- [PDF processing](https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_chat/services/pdf_service.py): `backend/backend_chat/services/pdf_service.py`

### AI assistance

- [Embedding service](https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_research/services/embedding_service.py): `backend/backend_research/services/embedding_service.py`
- [AI chat service](https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_chat/services/ai_service.py): `backend/backend_chat/services/ai_service.py`
- [Voice transcription](https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_chat/services/deepgram_service.py): `backend/backend_chat/services/deepgram_service.py`
- [Text analysis](https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_chat/services/word_counter_service.py): `backend/backend_chat/services/word_counter_service.py`

### Persistence and identity

- [Vector store](https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_research/vector_store.py): `backend/backend_research/vector_store.py`
- [SQL database access](https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_research/database.py): `backend/backend_research/database.py`
- [Research queries](https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_research/db_queries.py): `backend/backend_research/db_queries.py`
- [User management](https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_research/services/user_service.py): `backend/backend_research/services/user_service.py`
- [Token verification](https://github.com/shrey-cs-ai/orbirag_app/blob/main/backend/backend_chat/services/auth_service.py): `backend/backend_chat/services/auth_service.py`

### Other components

- **Semantic Scholar**
- **Gemini**
- **Deepgram**
- **Firebase Auth**
- **PostgreSQL**
- **DuckDB VSS**

## Connections

- Research API → Literature search: searches with (evidence: `backend/backend_research/main.py`)
- Literature search → Semantic Scholar: queries (evidence: `backend/backend_research/services/search_service.py`)
- Research API → Paper library: manages papers (evidence: `backend/backend_research/main.py`)
- Research API → Citation tools: routes citation work (evidence: `backend/backend_research/main.py`)
- Research API → Methodology extraction: requests extraction (evidence: `backend/backend_research/main.py`)
- Research API → Plagiarism tools: runs checks (evidence: `backend/backend_research/main.py`)
- Research API → Research notes: manages notes (evidence: `backend/backend_research/main.py`)
- Research API → Document RAG: routes document Q&A (evidence: `backend/backend_research/main.py`)
- Research API → Research queries: saves records (evidence: `backend/backend_research/main.py`)
- Research API → User management: manages users (evidence: `backend/backend_research/main.py`)
- Research API → SQL database access: opens sessions (evidence: `backend/backend_research/main.py`)
- Document RAG → Vector store: indexes and searches (evidence: `backend/backend_research/services/rag_service.py`)
- Document RAG → AI chat service: asks with context (evidence: `backend/backend_research/services/rag_service.py`)
- Vector store → Embedding service: uses embeddings (evidence: `backend/backend_research/vector_store.py`)
- Vector store → DuckDB VSS: stores vectors
- Chat API → AI chat service: gets responses (evidence: `backend/backend_chat/main.py`)
- Chat API → Voice transcription: transcribes audio (evidence: `backend/backend_chat/main.py`)
- Chat API → PDF processing: extracts PDF text (evidence: `backend/backend_chat/main.py`)
- Chat API → Text analysis: builds statistics (evidence: `backend/backend_chat/main.py`)
- AI chat service → Gemini: generates answers (evidence: `backend/backend_chat/services/ai_service.py`)
- Voice transcription → Deepgram: transcribes audio (evidence: `backend/backend_chat/services/deepgram_service.py`)
- Token verification → Firebase Auth: verifies tokens (evidence: `backend/backend_chat/services/auth_service.py`)
- SQL database access → PostgreSQL: connects to (evidence: `backend/backend_research/database.py`)
- Research API → API contracts: uses schemas (evidence: `backend/backend_research/main.py`)
- Chat API → Chat contracts: uses models (evidence: `backend/backend_chat/main.py`)
