# vahini-1/ai_scientist architecture

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

- Interactive diagram: https://gitdiagram.com/vahini-1/ai_scientist
- Repository: https://github.com/vahini-1/ai_scientist

## Overview

AI Scientist is a scientific experiment-planning workstation. A researcher submits a hypothesis and constraints, the backend gathers literature, supplier, and expert-memory context, then generates a structured experiment plan for review, chat, and export. The frontend also archives reports locally for later reopening. The graph preserves the documented report sections and the sampled backend orchestration; some frontend wiring and unsampled subsystems are represented only where the README supports them.

Main entry points: [`backend/src/index.ts`](https://github.com/vahini-1/ai_scientist/blob/main/backend/src/index.ts) (API routes), [`frontend/src/components/workstation/ReportView.tsx`](https://github.com/vahini-1/ai_scientist/blob/main/frontend/src/components/workstation/ReportView.tsx) (Experiment report), [`backend/src/env.ts`](https://github.com/vahini-1/ai_scientist/blob/main/backend/src/env.ts) (Backend config), [`frontend/src/App.tsx`](https://github.com/vahini-1/ai_scientist/blob/main/frontend/src/App.tsx) (Application shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workstation["Research workstation"]
  node_app["Application shell<br/>[App.tsx]"]
  node_prompt["Hypothesis input"]
  node_report["Experiment report<br/>[ReportView.tsx]"]
  node_review["Review controls<br/>[EditableText.tsx]"]
  node_library["Report library<br/>[LibraryView.tsx]"]
  node_chat["Report chat"]
  node_export["Report export<br/>[export.ts]"]
end

subgraph group_planning["Plan generation"]
  node_api["API routes<br/>[index.ts]"]
  node_plan["Plan schema<br/>[schema.ts]"]
  node_generator["Plan generation<br/>[azure.ts]"]
end

subgraph group_grounding["Research grounding"]
  node_novelty["Novelty search<br/>[researchAgent.ts]"]
  node_search["Grounding searches<br/>[tavily.ts]"]
end

subgraph group_services["External services"]
  node_config["Backend config<br/>[env.ts]"]
  node_semantic["Semantic Scholar"]
  node_tavily["Tavily search"]
  node_azure["Azure OpenAI"]
  node_supabase[("Supabase")]
  node_localstorage[("Browser local storage")]
end

subgraph group_persistence["Memory and archive"]
  node_state["Workstation state"]
  node_memory[("Expert memory<br/>[supabase.ts]")]
end

node_researcher(("Researcher"))

node_researcher -->|"opens workstation"| node_app
node_app -->|"provides state"| node_state
node_app -->|"routes to"| node_report
node_researcher -->|"submits hypothesis"| node_prompt
node_prompt -->|"requests plan"| node_api
node_api -->|"validates input"| node_plan
node_api -->|"checks novelty"| node_novelty
node_api -->|"gathers context"| node_search
node_api -->|"loads corrections"| node_memory
node_api -->|"generates plan"| node_generator
node_generator -->|"parses output"| node_plan
node_novelty -->|"queries papers"| node_semantic
node_novelty -->|"searches suppliers"| node_tavily
node_search -->|"runs searches"| node_tavily
node_generator -->|"calls model"| node_azure
node_memory -->|"reads and writes"| node_supabase
node_report -->|"renders edits"| node_review
node_researcher -->|"reviews plan"| node_report
node_researcher -->|"asks questions"| node_chat
node_chat -->|"requests report chat"| node_api
node_report -->|"exports report"| node_export
node_state -->|"persists reports"| node_localstorage
node_library -->|"reopens archives"| node_state
node_api -->|"saves review"| node_memory
node_config -.->|"configures access"| node_azure
node_config -.->|"configures access"| node_tavily
node_config -.->|"configures access"| node_supabase

click node_app "https://github.com/vahini-1/ai_scientist/blob/main/frontend/src/App.tsx"
click node_prompt "https://github.com/vahini-1/ai_scientist/blob/main/frontend/src/components/workstation/PromptInterface.tsx"
click node_report "https://github.com/vahini-1/ai_scientist/blob/main/frontend/src/components/workstation/ReportView.tsx"
click node_review "https://github.com/vahini-1/ai_scientist/blob/main/frontend/src/components/workstation/EditableText.tsx"
click node_library "https://github.com/vahini-1/ai_scientist/blob/main/frontend/src/components/workstation/LibraryView.tsx"
click node_chat "https://github.com/vahini-1/ai_scientist/blob/main/frontend/src/components/workstation/PromptInterface.tsx"
click node_export "https://github.com/vahini-1/ai_scientist/blob/main/frontend/src/lib/export.ts"
click node_state "https://github.com/vahini-1/ai_scientist/blob/main/frontend/src/context/workstation-context.tsx"
click node_api "https://github.com/vahini-1/ai_scientist/blob/main/backend/src/index.ts"
click node_plan "https://github.com/vahini-1/ai_scientist/blob/main/backend/src/schema.ts"
click node_generator "https://github.com/vahini-1/ai_scientist/blob/main/backend/src/azure.ts"
click node_novelty "https://github.com/vahini-1/ai_scientist/blob/main/backend/src/researchAgent.ts"
click node_search "https://github.com/vahini-1/ai_scientist/blob/main/backend/src/tavily.ts"
click node_memory "https://github.com/vahini-1/ai_scientist/blob/main/backend/src/supabase.ts"
click node_config "https://github.com/vahini-1/ai_scientist/blob/main/backend/src/env.ts"

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_app,node_prompt,node_report,node_review,node_library,node_chat,node_export toneBlue
class node_api,node_plan,node_generator toneAmber
class node_novelty,node_search toneMint
class node_config,node_semantic,node_tavily,node_azure,node_supabase,node_localstorage toneRose
class node_state,node_memory,node_researcher toneIndigo
```

## Components

### Research workstation

- [Application shell](https://github.com/vahini-1/ai_scientist/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Hypothesis input](https://github.com/vahini-1/ai_scientist/blob/main/frontend/src/components/workstation/PromptInterface.tsx): `frontend/src/components/workstation/PromptInterface.tsx`
- [Experiment report](https://github.com/vahini-1/ai_scientist/blob/main/frontend/src/components/workstation/ReportView.tsx): `frontend/src/components/workstation/ReportView.tsx`
- [Review controls](https://github.com/vahini-1/ai_scientist/blob/main/frontend/src/components/workstation/EditableText.tsx): `frontend/src/components/workstation/EditableText.tsx`
- [Report library](https://github.com/vahini-1/ai_scientist/blob/main/frontend/src/components/workstation/LibraryView.tsx): `frontend/src/components/workstation/LibraryView.tsx`
- [Report chat](https://github.com/vahini-1/ai_scientist/blob/main/frontend/src/components/workstation/PromptInterface.tsx): `frontend/src/components/workstation/PromptInterface.tsx`
- [Report export](https://github.com/vahini-1/ai_scientist/blob/main/frontend/src/lib/export.ts): `frontend/src/lib/export.ts`

### Plan generation

- [API routes](https://github.com/vahini-1/ai_scientist/blob/main/backend/src/index.ts): `backend/src/index.ts`
- [Plan schema](https://github.com/vahini-1/ai_scientist/blob/main/backend/src/schema.ts): `backend/src/schema.ts`
- [Plan generation](https://github.com/vahini-1/ai_scientist/blob/main/backend/src/azure.ts): `backend/src/azure.ts`

### Research grounding

- [Novelty search](https://github.com/vahini-1/ai_scientist/blob/main/backend/src/researchAgent.ts): `backend/src/researchAgent.ts`
- [Grounding searches](https://github.com/vahini-1/ai_scientist/blob/main/backend/src/tavily.ts): `backend/src/tavily.ts`

### External services

- [Backend config](https://github.com/vahini-1/ai_scientist/blob/main/backend/src/env.ts): `backend/src/env.ts`
- **Semantic Scholar**
- **Tavily search**
- **Azure OpenAI**
- **Supabase**
- **Browser local storage**

### Memory and archive

- [Workstation state](https://github.com/vahini-1/ai_scientist/blob/main/frontend/src/context/workstation-context.tsx): `frontend/src/context/workstation-context.tsx`
- [Expert memory](https://github.com/vahini-1/ai_scientist/blob/main/backend/src/supabase.ts): `backend/src/supabase.ts`

### Other components

- **Researcher**

## Connections

- Researcher → Application shell: opens workstation
- Application shell → Workstation state: provides state (evidence: `frontend/src/App.tsx`)
- Application shell → Experiment report: routes to (evidence: `frontend/src/App.tsx`)
- Researcher → Hypothesis input: submits hypothesis (evidence: `README.md`)
- Hypothesis input → API routes: requests plan (evidence: `README.md`)
- API routes → Plan schema: validates input (evidence: `backend/src/index.ts`)
- API routes → Novelty search: checks novelty (evidence: `backend/src/index.ts`)
- API routes → Grounding searches: gathers context (evidence: `backend/src/index.ts`)
- API routes → Expert memory: loads corrections (evidence: `backend/src/index.ts`)
- API routes → Plan generation: generates plan (evidence: `backend/src/index.ts`)
- Plan generation → Plan schema: parses output (evidence: `backend/src/azure.ts`)
- Novelty search → Semantic Scholar: queries papers (evidence: `backend/src/researchAgent.ts`)
- Novelty search → Tavily search: searches suppliers (evidence: `backend/src/researchAgent.ts`)
- Grounding searches → Tavily search: runs searches (evidence: `backend/src/tavily.ts`)
- Plan generation → Azure OpenAI: calls model (evidence: `backend/src/azure.ts`)
- Expert memory → Supabase: reads and writes (evidence: `backend/src/supabase.ts`)
- Experiment report → Review controls: renders edits (evidence: `frontend/src/components/workstation/ReportView.tsx`)
- Researcher → Experiment report: reviews plan (evidence: `README.md`)
- Researcher → Report chat: asks questions (evidence: `README.md`)
- Report chat → API routes: requests report chat (evidence: `README.md`)
- Experiment report → Report export: exports report (evidence: `README.md`)
- Workstation state → Browser local storage: persists reports (evidence: `README.md`)
- Report library → Workstation state: reopens archives (evidence: `README.md`)
- API routes → Expert memory: saves review (evidence: `backend/src/index.ts`)
- Backend config → Azure OpenAI: configures access
- Backend config → Tavily search: configures access
- Backend config → Supabase: configures access
