# sudeshdahale/ai-research-copilot architecture

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

- Interactive diagram: https://gitdiagram.com/sudeshdahale/ai-research-copilot
- Repository: https://github.com/sudeshdahale/ai-research-copilot

## Overview

Arclight is a research-paper discovery and analysis copilot. Researchers search and filter papers, curate them in workspaces, then ask workspace-scoped questions or generate documents; frontend routes expose those workflows through the backend API. Search spans external scholarly catalogs, while saved papers and generated documents are durable, and semantic similarity uses embeddings. Agent requests retrieve papers before producing a fast streamed answer and intent-specific deeper analysis. Several backend routes and frontend components are unsampled, so their relationships are included only where the README or SOURCE INDEX documents them; unverified implementation details are omitted.

Main entry points: [`backend/app/api/v1/router.py`](https://github.com/sudeshdahale/ai-research-copilot/blob/main/backend/app/api/v1/router.py) (API router), [`frontend/src/routes/_app.tsx`](https://github.com/sudeshdahale/ai-research-copilot/blob/main/frontend/src/routes/_app.tsx) (Research workspace), [`backend/app/api/v1/agent.py`](https://github.com/sudeshdahale/ai-research-copilot/blob/main/backend/app/api/v1/agent.py) (Agent endpoint), [`backend/app/services/paper_service.py`](https://github.com/sudeshdahale/ai-research-copilot/blob/main/backend/app/services/paper_service.py) (Catalog search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Research interface"]
  node_web["Research workspace<br/>[_app.tsx]"]
  node_search_ui["Paper search<br/>[_app.search.tsx]"]
  node_library_ui["Paper library<br/>[_app.library.tsx]"]
  node_paper_ui["Paper details"]
  node_review_ui["Document review<br/>[_app.review.tsx]"]
  node_agent_ui["Agent chat<br/>[AgentChat.tsx]"]
end

subgraph group_api["API and access"]
  node_api_router["API router<br/>[router.py]"]
  node_auth["Authentication<br/>[auth.py]"]
end

subgraph group_discovery["Paper discovery"]
  node_search_api["Search endpoint<br/>[search.py]"]
  node_discover_api["Discover assistant<br/>[discover.py]"]
  node_paper_search["Catalog search<br/>[paper_service.py]"]
  node_ranking["Result ranking<br/>[ranking_service.py]"]
  node_search_cache["Search cache<br/>[cache.py]"]
end

subgraph group_research["Research analysis"]
  node_agent_api["Agent endpoint<br/>[agent.py]"]
  node_retrieval["Paper retrieval<br/>[retrieve.py]"]
  node_fast_pipeline["Fast answers<br/>[fast_pipeline.py]"]
  node_deep_pipeline["Deep analysis<br/>[deep_pipeline.py]"]
  node_analysis_nodes["Intent analysis"]
  node_llm["Language model<br/>[llm_service.py]"]
end

subgraph group_data["Persistence and jobs"]
  node_workspace_api["Workspace management<br/>[workspaces.py]"]
  node_documents_api["Document generation<br/>[documents.py]"]
  node_doc_worker["Generation worker"]
  node_postgres[("PostgreSQL and pgvector<br/>[session.py]")]
  node_vector_service["Vector similarity<br/>[vector_service.py]"]
end

node_researcher(("Researcher"))
node_redis[("Redis cache and broker")]
node_scholarly_apis["Scholarly catalogs"]
node_voyage["Voyage embeddings"]

node_researcher -->|"uses"| node_web
node_web -->|"opens"| node_search_ui
node_web -->|"opens"| node_library_ui
node_web -->|"opens"| node_paper_ui
node_web -->|"opens"| node_review_ui
node_web -->|"asks questions"| node_agent_ui
node_search_ui -->|"queries"| node_search_api
node_library_ui -->|"curates papers"| node_workspace_api
node_paper_ui -.->|"requests paper"| node_api_router
node_review_ui -->|"reviews documents"| node_documents_api
node_agent_ui -->|"streams request"| node_agent_api
node_api_router -->|"routes"| node_auth
node_api_router -->|"routes"| node_search_api
node_api_router -->|"routes"| node_discover_api
node_api_router -->|"routes"| node_workspace_api
node_api_router -->|"routes"| node_agent_api
node_api_router -->|"routes"| node_documents_api
node_search_api -->|"searches catalogs"| node_paper_search
node_paper_search -->|"queries"| node_scholarly_apis
node_paper_search -->|"ranks results"| node_ranking
node_search_api -->|"caches queries"| node_search_cache
node_discover_api -->|"re-queries"| node_paper_search
node_discover_api -->|"ranks candidates"| node_ranking
node_discover_api -.->|"uses cache"| node_redis
node_agent_api -->|"retrieves papers"| node_retrieval
node_agent_api -->|"streams answer"| node_fast_pipeline
node_agent_api -->|"dispatches analysis"| node_deep_pipeline
node_retrieval -->|"loads workspace papers"| node_postgres
node_retrieval -->|"searches globally"| node_paper_search
node_fast_pipeline -->|"streams completion"| node_llm
node_deep_pipeline -->|"selects intent node"| node_analysis_nodes
node_deep_pipeline -.->|"generates synthesis"| node_llm
node_workspace_api -->|"persists workspaces"| node_postgres
node_workspace_api -->|"saves papers"| node_postgres
node_documents_api -->|"queues jobs"| node_doc_worker
node_doc_worker -->|"persists documents"| node_postgres
node_documents_api -.->|"uses broker"| node_redis
node_paper_ui -->|"requests similarity"| node_vector_service
node_vector_service -->|"creates embeddings"| node_voyage
node_vector_service -->|"searches vectors"| node_postgres

click node_web "https://github.com/sudeshdahale/ai-research-copilot/blob/main/frontend/src/routes/_app.tsx"
click node_search_ui "https://github.com/sudeshdahale/ai-research-copilot/blob/main/frontend/src/routes/_app.search.tsx"
click node_library_ui "https://github.com/sudeshdahale/ai-research-copilot/blob/main/frontend/src/routes/_app.library.tsx"
click node_paper_ui "https://github.com/sudeshdahale/ai-research-copilot/blob/main/frontend/src/routes/_app.papers.%24id.tsx"
click node_review_ui "https://github.com/sudeshdahale/ai-research-copilot/blob/main/frontend/src/routes/_app.review.tsx"
click node_agent_ui "https://github.com/sudeshdahale/ai-research-copilot/blob/main/frontend/src/components/agent/AgentChat.tsx"
click node_api_router "https://github.com/sudeshdahale/ai-research-copilot/blob/main/backend/app/api/v1/router.py"
click node_auth "https://github.com/sudeshdahale/ai-research-copilot/blob/main/backend/app/api/v1/auth.py"
click node_search_api "https://github.com/sudeshdahale/ai-research-copilot/blob/main/backend/app/api/v1/search.py"
click node_discover_api "https://github.com/sudeshdahale/ai-research-copilot/blob/main/backend/app/api/v1/discover.py"
click node_paper_search "https://github.com/sudeshdahale/ai-research-copilot/blob/main/backend/app/services/paper_service.py"
click node_ranking "https://github.com/sudeshdahale/ai-research-copilot/blob/main/backend/app/services/ranking_service.py"
click node_search_cache "https://github.com/sudeshdahale/ai-research-copilot/blob/main/backend/app/core/cache.py"
click node_agent_api "https://github.com/sudeshdahale/ai-research-copilot/blob/main/backend/app/api/v1/agent.py"
click node_retrieval "https://github.com/sudeshdahale/ai-research-copilot/blob/main/backend/app/agents/nodes/retrieve.py"
click node_fast_pipeline "https://github.com/sudeshdahale/ai-research-copilot/blob/main/backend/app/agents/fast_pipeline.py"
click node_deep_pipeline "https://github.com/sudeshdahale/ai-research-copilot/blob/main/backend/app/agents/deep_pipeline.py"
click node_analysis_nodes "https://github.com/sudeshdahale/ai-research-copilot/tree/main/backend/app/agents/nodes"
click node_llm "https://github.com/sudeshdahale/ai-research-copilot/blob/main/backend/app/services/llm_service.py"
click node_workspace_api "https://github.com/sudeshdahale/ai-research-copilot/blob/main/backend/app/api/v1/workspaces.py"
click node_documents_api "https://github.com/sudeshdahale/ai-research-copilot/blob/main/backend/app/api/v1/documents.py"
click node_doc_worker "https://github.com/sudeshdahale/ai-research-copilot/blob/main/backend/app/workers/generate_document.py"
click node_postgres "https://github.com/sudeshdahale/ai-research-copilot/blob/main/backend/app/db/session.py"
click node_vector_service "https://github.com/sudeshdahale/ai-research-copilot/blob/main/backend/app/services/vector_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_web,node_search_ui,node_library_ui,node_paper_ui,node_review_ui,node_agent_ui toneBlue
class node_api_router,node_auth,node_redis toneAmber
class node_search_api,node_discover_api,node_paper_search,node_ranking,node_search_cache toneMint
class node_agent_api,node_retrieval,node_fast_pipeline,node_deep_pipeline,node_analysis_nodes,node_llm toneRose
class node_workspace_api,node_documents_api,node_doc_worker,node_postgres,node_vector_service,node_researcher,node_scholarly_apis,node_voyage toneIndigo
```

## Components

### Research interface

- [Research workspace](https://github.com/sudeshdahale/ai-research-copilot/blob/main/frontend/src/routes/_app.tsx): `frontend/src/routes/_app.tsx`
- [Paper search](https://github.com/sudeshdahale/ai-research-copilot/blob/main/frontend/src/routes/_app.search.tsx): `frontend/src/routes/_app.search.tsx`
- [Paper library](https://github.com/sudeshdahale/ai-research-copilot/blob/main/frontend/src/routes/_app.library.tsx): `frontend/src/routes/_app.library.tsx`
- [Paper details](https://github.com/sudeshdahale/ai-research-copilot/blob/main/frontend/src/routes/_app.papers.%24id.tsx): `frontend/src/routes/_app.papers.$id.tsx`
- [Document review](https://github.com/sudeshdahale/ai-research-copilot/blob/main/frontend/src/routes/_app.review.tsx): `frontend/src/routes/_app.review.tsx`
- [Agent chat](https://github.com/sudeshdahale/ai-research-copilot/blob/main/frontend/src/components/agent/AgentChat.tsx): `frontend/src/components/agent/AgentChat.tsx`

### API and access

- [API router](https://github.com/sudeshdahale/ai-research-copilot/blob/main/backend/app/api/v1/router.py): `backend/app/api/v1/router.py`
- [Authentication](https://github.com/sudeshdahale/ai-research-copilot/blob/main/backend/app/api/v1/auth.py): `backend/app/api/v1/auth.py`

### Paper discovery

- [Search endpoint](https://github.com/sudeshdahale/ai-research-copilot/blob/main/backend/app/api/v1/search.py): `backend/app/api/v1/search.py`
- [Discover assistant](https://github.com/sudeshdahale/ai-research-copilot/blob/main/backend/app/api/v1/discover.py): `backend/app/api/v1/discover.py`
- [Catalog search](https://github.com/sudeshdahale/ai-research-copilot/blob/main/backend/app/services/paper_service.py): `backend/app/services/paper_service.py`
- [Result ranking](https://github.com/sudeshdahale/ai-research-copilot/blob/main/backend/app/services/ranking_service.py): `backend/app/services/ranking_service.py`
- [Search cache](https://github.com/sudeshdahale/ai-research-copilot/blob/main/backend/app/core/cache.py): `backend/app/core/cache.py`

### Research analysis

- [Agent endpoint](https://github.com/sudeshdahale/ai-research-copilot/blob/main/backend/app/api/v1/agent.py): `backend/app/api/v1/agent.py`
- [Paper retrieval](https://github.com/sudeshdahale/ai-research-copilot/blob/main/backend/app/agents/nodes/retrieve.py): `backend/app/agents/nodes/retrieve.py`
- [Fast answers](https://github.com/sudeshdahale/ai-research-copilot/blob/main/backend/app/agents/fast_pipeline.py): `backend/app/agents/fast_pipeline.py`
- [Deep analysis](https://github.com/sudeshdahale/ai-research-copilot/blob/main/backend/app/agents/deep_pipeline.py): `backend/app/agents/deep_pipeline.py`
- [Intent analysis](https://github.com/sudeshdahale/ai-research-copilot/tree/main/backend/app/agents/nodes): `backend/app/agents/nodes`
- [Language model](https://github.com/sudeshdahale/ai-research-copilot/blob/main/backend/app/services/llm_service.py): `backend/app/services/llm_service.py`

### Persistence and jobs

- [Workspace management](https://github.com/sudeshdahale/ai-research-copilot/blob/main/backend/app/api/v1/workspaces.py): `backend/app/api/v1/workspaces.py`
- [Document generation](https://github.com/sudeshdahale/ai-research-copilot/blob/main/backend/app/api/v1/documents.py): `backend/app/api/v1/documents.py`
- [Generation worker](https://github.com/sudeshdahale/ai-research-copilot/blob/main/backend/app/workers/generate_document.py): `backend/app/workers/generate_document.py`
- [PostgreSQL and pgvector](https://github.com/sudeshdahale/ai-research-copilot/blob/main/backend/app/db/session.py): `backend/app/db/session.py`
- [Vector similarity](https://github.com/sudeshdahale/ai-research-copilot/blob/main/backend/app/services/vector_service.py): `backend/app/services/vector_service.py`

### Other components

- **Researcher**
- **Redis cache and broker**
- **Scholarly catalogs**
- **Voyage embeddings**

## Connections

- Researcher → Research workspace: uses
- Research workspace → Paper search: opens
- Research workspace → Paper library: opens
- Research workspace → Paper details: opens
- Research workspace → Document review: opens
- Research workspace → Agent chat: asks questions
- Paper search → Search endpoint: queries
- Paper library → Workspace management: curates papers
- Paper details → API router: requests paper
- Document review → Document generation: reviews documents
- Agent chat → Agent endpoint: streams request
- API router → Authentication: routes (evidence: `backend/app/api/v1/router.py`)
- API router → Search endpoint: routes (evidence: `backend/app/api/v1/router.py`)
- API router → Discover assistant: routes (evidence: `backend/app/api/v1/router.py`)
- API router → Workspace management: routes (evidence: `backend/app/api/v1/router.py`)
- API router → Agent endpoint: routes (evidence: `backend/app/api/v1/router.py`)
- API router → Document generation: routes (evidence: `backend/app/api/v1/router.py`)
- Search endpoint → Catalog search: searches catalogs
- Catalog search → Scholarly catalogs: queries
- Catalog search → Result ranking: ranks results
- Search endpoint → Search cache: caches queries
- Discover assistant → Catalog search: re-queries (evidence: `backend/app/api/v1/discover.py`)
- Discover assistant → Result ranking: ranks candidates (evidence: `backend/app/api/v1/discover.py`)
- Discover assistant → Redis cache and broker: uses cache
- Agent endpoint → Paper retrieval: retrieves papers (evidence: `backend/app/api/v1/agent.py`)
- Agent endpoint → Fast answers: streams answer (evidence: `backend/app/api/v1/agent.py`)
- Agent endpoint → Deep analysis: dispatches analysis (evidence: `backend/app/api/v1/agent.py`)
- Paper retrieval → PostgreSQL and pgvector: loads workspace papers (evidence: `backend/app/agents/nodes/retrieve.py`)
- Paper retrieval → Catalog search: searches globally (evidence: `backend/app/agents/nodes/retrieve.py`)
- Fast answers → Language model: streams completion (evidence: `backend/app/agents/fast_pipeline.py`)
- Deep analysis → Intent analysis: selects intent node (evidence: `backend/app/agents/deep_pipeline.py`)
- Deep analysis → Language model: generates synthesis
- Workspace management → PostgreSQL and pgvector: persists workspaces
- Workspace management → PostgreSQL and pgvector: saves papers
- Document generation → Generation worker: queues jobs
- Generation worker → PostgreSQL and pgvector: persists documents
- Document generation → Redis cache and broker: uses broker
- Paper details → Vector similarity: requests similarity
- Vector similarity → Voyage embeddings: creates embeddings
- Vector similarity → PostgreSQL and pgvector: searches vectors
