# ajayguptha-tech/researchos architecture

> Architecture diagram of the GitHub repository ajayguptha-tech/researchos, 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/ajayguptha-tech/researchos
- Repository: https://github.com/ajayguptha-tech/researchos

## Overview

ResearchOS turns a research idea into an evidence-backed plan, literature analysis, and roadmap, then supports project workspaces, paper drafting, and supervisor review. Users enter through the Next.js workspace; its API client communicates with the FastAPI routes, which expose research and collaboration capabilities backed by persistent domain data. The sampled pipeline explicitly plans, searches literature, and analyzes results. The README documents broader retrieval and methodology capabilities, but several service and route implementations were not sampled, so their internal links are left unasserted.

Main entry points: [`backend/app/api/v1/routes`](https://github.com/ajayguptha-tech/researchos/tree/main/backend/app/api/v1/routes) (REST API), [`ai/pipelines/research_pipeline.py`](https://github.com/ajayguptha-tech/researchos/blob/main/ai/pipelines/research_pipeline.py) (Research pipeline), [`backend/app/db/models.py`](https://github.com/ajayguptha-tech/researchos/blob/main/backend/app/db/models.py) (Domain models), [`frontend/app/workspace/[projectId]/page.tsx`](https://github.com/ajayguptha-tech/researchos/blob/main/frontend/app/workspace/%5BprojectId%5D/page.tsx) (Project workspace)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User interface"]
  node_workspace_ui["Workspace UI<br/>[page.tsx]"]
  node_project_ui["Project workspace<br/>[page.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["Backend API"]
  node_backend_api["REST API"]
  node_research_routes["Research routes<br/>[research.py]"]
  node_project_routes["Project routes<br/>[projects.py]"]
  node_paper_routes["Paper routes<br/>[papers.py]"]
  node_auth_routes["Authentication<br/>[auth.py]"]
  node_review_routes["Supervisor review<br/>[supervisor.py]"]
end

subgraph group_research["Research intelligence"]
  node_pipeline["Research pipeline"]
  node_planner["Research planner"]
  node_literature["Literature search"]
  node_analyzer["Paper analysis"]
  node_research_agents["Research agents"]
end

subgraph group_workspace["Research workspace"]
  node_documents["Document services"]
  node_drafting["Paper drafting<br/>[paper_drafts.py]"]
  node_roadmap["Roadmap service<br/>[roadmap_service.py]"]
end

subgraph group_storage["Persistence"]
  node_models["Domain models<br/>[models.py]"]
  node_paper_repository["Paper repository"]
  node_project_repository["Project repository"]
  node_database[("Relational database<br/>[session.py]")]
end

node_researcher(("Researcher"))
node_literature_sources["Literature sources"]

node_researcher -->|"uses"| node_workspace_ui
node_researcher -->|"opens project"| node_project_ui
node_workspace_ui -->|"requests through"| node_api_client
node_project_ui -->|"requests through"| node_api_client
node_api_client -->|"sends REST requests"| node_backend_api
node_backend_api -->|"routes research"| node_research_routes
node_backend_api -->|"routes projects"| node_project_routes
node_backend_api -->|"routes papers"| node_paper_routes
node_backend_api -->|"routes authentication"| node_auth_routes
node_backend_api -->|"routes review"| node_review_routes
node_pipeline -->|"plans idea"| node_planner
node_pipeline -->|"searches literature"| node_literature
node_pipeline -->|"analyzes results"| node_analyzer
node_literature -.->|"searches"| node_literature_sources
node_research_routes -.->|"orchestrates research"| node_pipeline
node_project_routes -.->|"uses roadmap logic"| node_roadmap
node_paper_routes -.->|"uses document logic"| node_documents
node_project_ui -->|"requests drafts via API"| node_drafting
node_drafting -.->|"generates drafts"| node_research_agents
node_auth_routes -->|"creates user records"| node_models
node_paper_repository -->|"queries paper model"| node_models
node_project_repository -->|"queries project model"| node_models
node_models -.->|"persists domain data"| node_database

click node_workspace_ui "https://github.com/ajayguptha-tech/researchos/blob/main/frontend/app/workspace/page.tsx"
click node_project_ui "https://github.com/ajayguptha-tech/researchos/blob/main/frontend/app/workspace/%5BprojectId%5D/page.tsx"
click node_api_client "https://github.com/ajayguptha-tech/researchos/blob/main/frontend/lib/api.ts"
click node_backend_api "https://github.com/ajayguptha-tech/researchos/tree/main/backend/app/api/v1/routes"
click node_research_routes "https://github.com/ajayguptha-tech/researchos/blob/main/backend/app/api/v1/routes/research.py"
click node_project_routes "https://github.com/ajayguptha-tech/researchos/blob/main/backend/app/api/v1/routes/projects.py"
click node_paper_routes "https://github.com/ajayguptha-tech/researchos/blob/main/backend/app/api/v1/routes/papers.py"
click node_auth_routes "https://github.com/ajayguptha-tech/researchos/blob/main/backend/app/api/v1/routes/auth.py"
click node_review_routes "https://github.com/ajayguptha-tech/researchos/blob/main/backend/app/api/v1/routes/supervisor.py"
click node_pipeline "https://github.com/ajayguptha-tech/researchos/blob/main/ai/pipelines/research_pipeline.py"
click node_planner "https://github.com/ajayguptha-tech/researchos/blob/main/ai/agents/research_planner_agent.py"
click node_literature "https://github.com/ajayguptha-tech/researchos/blob/main/ai/agents/literature_search_agent.py"
click node_analyzer "https://github.com/ajayguptha-tech/researchos/blob/main/ai/agents/paper_analyzer_agent.py"
click node_research_agents "https://github.com/ajayguptha-tech/researchos/tree/main/ai/agents"
click node_documents "https://github.com/ajayguptha-tech/researchos/blob/main/backend/app/services/document_service.py"
click node_drafting "https://github.com/ajayguptha-tech/researchos/blob/main/backend/app/api/v1/routes/paper_drafts.py"
click node_roadmap "https://github.com/ajayguptha-tech/researchos/blob/main/backend/app/services/roadmap_service.py"
click node_models "https://github.com/ajayguptha-tech/researchos/blob/main/backend/app/db/models.py"
click node_paper_repository "https://github.com/ajayguptha-tech/researchos/blob/main/backend/app/db/repositories/paper_repository.py"
click node_project_repository "https://github.com/ajayguptha-tech/researchos/blob/main/backend/app/db/repositories/project_repository.py"
click node_database "https://github.com/ajayguptha-tech/researchos/blob/main/backend/app/db/session.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_workspace_ui,node_project_ui,node_api_client toneBlue
class node_backend_api,node_research_routes,node_project_routes,node_paper_routes,node_auth_routes,node_review_routes toneAmber
class node_pipeline,node_planner,node_literature,node_analyzer,node_research_agents toneMint
class node_documents,node_drafting,node_roadmap toneRose
class node_models,node_paper_repository,node_project_repository,node_database,node_researcher,node_literature_sources toneIndigo
```

## Components

### User interface

- [Workspace UI](https://github.com/ajayguptha-tech/researchos/blob/main/frontend/app/workspace/page.tsx): `frontend/app/workspace/page.tsx`
- [Project workspace](https://github.com/ajayguptha-tech/researchos/blob/main/frontend/app/workspace/%5BprojectId%5D/page.tsx): `frontend/app/workspace/[projectId]/page.tsx`
- [API client](https://github.com/ajayguptha-tech/researchos/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`

### Backend API

- [REST API](https://github.com/ajayguptha-tech/researchos/tree/main/backend/app/api/v1/routes): `backend/app/api/v1/routes`
- [Research routes](https://github.com/ajayguptha-tech/researchos/blob/main/backend/app/api/v1/routes/research.py): `backend/app/api/v1/routes/research.py`
- [Project routes](https://github.com/ajayguptha-tech/researchos/blob/main/backend/app/api/v1/routes/projects.py): `backend/app/api/v1/routes/projects.py`
- [Paper routes](https://github.com/ajayguptha-tech/researchos/blob/main/backend/app/api/v1/routes/papers.py): `backend/app/api/v1/routes/papers.py`
- [Authentication](https://github.com/ajayguptha-tech/researchos/blob/main/backend/app/api/v1/routes/auth.py): `backend/app/api/v1/routes/auth.py`
- [Supervisor review](https://github.com/ajayguptha-tech/researchos/blob/main/backend/app/api/v1/routes/supervisor.py): `backend/app/api/v1/routes/supervisor.py`

### Research intelligence

- [Research pipeline](https://github.com/ajayguptha-tech/researchos/blob/main/ai/pipelines/research_pipeline.py): `ai/pipelines/research_pipeline.py`
- [Research planner](https://github.com/ajayguptha-tech/researchos/blob/main/ai/agents/research_planner_agent.py): `ai/agents/research_planner_agent.py`
- [Literature search](https://github.com/ajayguptha-tech/researchos/blob/main/ai/agents/literature_search_agent.py): `ai/agents/literature_search_agent.py`
- [Paper analysis](https://github.com/ajayguptha-tech/researchos/blob/main/ai/agents/paper_analyzer_agent.py): `ai/agents/paper_analyzer_agent.py`
- [Research agents](https://github.com/ajayguptha-tech/researchos/tree/main/ai/agents): `ai/agents`

### Research workspace

- [Document services](https://github.com/ajayguptha-tech/researchos/blob/main/backend/app/services/document_service.py): `backend/app/services/document_service.py`
- [Paper drafting](https://github.com/ajayguptha-tech/researchos/blob/main/backend/app/api/v1/routes/paper_drafts.py): `backend/app/api/v1/routes/paper_drafts.py`
- [Roadmap service](https://github.com/ajayguptha-tech/researchos/blob/main/backend/app/services/roadmap_service.py): `backend/app/services/roadmap_service.py`

### Persistence

- [Domain models](https://github.com/ajayguptha-tech/researchos/blob/main/backend/app/db/models.py): `backend/app/db/models.py`
- [Paper repository](https://github.com/ajayguptha-tech/researchos/blob/main/backend/app/db/repositories/paper_repository.py): `backend/app/db/repositories/paper_repository.py`
- [Project repository](https://github.com/ajayguptha-tech/researchos/blob/main/backend/app/db/repositories/project_repository.py): `backend/app/db/repositories/project_repository.py`
- [Relational database](https://github.com/ajayguptha-tech/researchos/blob/main/backend/app/db/session.py): `backend/app/db/session.py`

### Other components

- **Researcher**
- **Literature sources**

## Connections

- Researcher → Workspace UI: uses (evidence: `README.md`)
- Researcher → Project workspace: opens project (evidence: `README.md`)
- Workspace UI → API client: requests through (evidence: `frontend/app/workspace/page.tsx`)
- Project workspace → API client: requests through (evidence: `frontend/app/workspace/[projectId]/page.tsx`)
- API client → REST API: sends REST requests (evidence: `README.md`)
- REST API → Research routes: routes research (evidence: `backend/app/main.py`)
- REST API → Project routes: routes projects (evidence: `backend/app/main.py`)
- REST API → Paper routes: routes papers (evidence: `backend/app/main.py`)
- REST API → Authentication: routes authentication (evidence: `backend/app/main.py`)
- REST API → Supervisor review: routes review (evidence: `backend/app/main.py`)
- Research pipeline → Research planner: plans idea (evidence: `ai/pipelines/research_pipeline.py`)
- Research pipeline → Literature search: searches literature (evidence: `ai/pipelines/research_pipeline.py`)
- Research pipeline → Paper analysis: analyzes results (evidence: `ai/pipelines/research_pipeline.py`)
- Literature search → Literature sources: searches
- Research routes → Research pipeline: orchestrates research
- Project routes → Roadmap service: uses roadmap logic (evidence: `backend/app/api/v1/routes/projects.py`)
- Paper routes → Document services: uses document logic (evidence: `backend/app/api/v1/routes/papers.py`)
- Project workspace → Paper drafting: requests drafts via API (evidence: `frontend/app/workspace/[projectId]/page.tsx`)
- Paper drafting → Research agents: generates drafts (evidence: `backend/app/api/v1/routes/paper_drafts.py`)
- Authentication → Domain models: creates user records (evidence: `backend/app/api/v1/routes/auth.py`)
- Paper repository → Domain models: queries paper model (evidence: `backend/app/db/repositories/paper_repository.py`)
- Project repository → Domain models: queries project model (evidence: `backend/app/db/repositories/project_repository.py`)
- Domain models → Relational database: persists domain data
