# sethum-vs/researchbot architecture

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

- Interactive diagram: https://gitdiagram.com/sethum-vs/researchbot
- Repository: https://github.com/sethum-vs/researchbot

## Overview

ResearchBot is a macOS research-discovery and proposal-synthesis application backed by a Python engine. Users submit a research topic, the engine gathers and processes sources, builds a knowledge graph and analyzes research gaps; users can then generate proposals, review session history and export results to Google Workspace. The README documents these capabilities, while source excerpts and index references support the key orchestration links. Some subsystem details are documented but unsampled, so those links are cited to the README rather than treated as inspected implementation.

Main entry points: [`ResearchGraphApp/Backend/application/IngestSeedUseCase.py`](https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/application/IngestSeedUseCase.py) (Research Ingestion), [`ResearchGraphApp/Backend/application/ProposalOrchestrator.py`](https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/application/ProposalOrchestrator.py) (Proposal Orchestrator), [`ResearchGraphApp/App/ResearchBot/PythonBridge.swift`](https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/App/ResearchBot/PythonBridge.swift) (Python Bridge), [`ResearchGraphApp/Backend/infrastructure/FileStorage.py`](https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/infrastructure/FileStorage.py) (Session Storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["macOS Client"]
  node_interface["Research UI<br/>[ContentView.swift]"]
  node_bridge["Python Bridge<br/>[PythonBridge.swift]"]
  node_history["Session History<br/>[HistoryView.swift]"]
  node_graphview["Graph Explorer"]
  node_review["Proposal Review"]
  node_documents["Document Viewer"]
end

subgraph group_runtime["Backend Orchestration"]
  node_entry["Command Entry<br/>[main.py]"]
  node_ingest["Research Ingestion"]
  node_proposal["Proposal Orchestrator"]
  node_export["Workspace Export"]
end

subgraph group_discovery["Research Discovery"]
  node_inputanalysis["Input Analysis<br/>[InputAnalyzer.py]"]
  node_academic["Academic Search<br/>[AcademicScraper.py]"]
  node_social["Social Search<br/>[SocialScraper.py]"]
  node_webwiki["Web and Wiki<br/>[WebScraper.py]"]
  node_pdf["PDF Extraction<br/>[PdfExtractor.py]"]
end

subgraph group_analysis["Analysis and Synthesis"]
  node_refiner["Data Refinement<br/>[DataRefiner.py]"]
  node_graphify["Graph Construction<br/>[GraphifyRunner.py]"]
  node_gapanalysis["Gap Analysis<br/>[GraphAnalyzer.py]"]
  node_matcher["Paper Matching<br/>[SemanticMatcher.py]"]
  node_synthesis["Proposal Synthesis"]
  node_chunker["Text Chunking<br/>[TextChunker.py]"]
end

subgraph group_state["Session Data and Integrations"]
  node_storage[("Session Storage<br/>[FileStorage.py]")]
  node_proxy["Vertex Proxy<br/>[VertexProxy.py]"]
  node_workspace["Google Workspace"]
end

node_researcher(("Researcher"))
node_vertex{{"Vertex AI"}}
node_googleapis{{"Google APIs"}}

node_researcher -->|"submits topic"| node_interface
node_interface -->|"starts runs"| node_bridge
node_bridge -->|"invokes commands"| node_entry
node_entry -->|"dispatches ingestion"| node_ingest
node_entry -->|"dispatches proposal"| node_proposal
node_entry -->|"dispatches export"| node_export
node_ingest -->|"analyzes seed"| node_inputanalysis
node_ingest -->|"searches papers"| node_academic
node_ingest -->|"gathers social data"| node_social
node_ingest -->|"gathers web sources"| node_webwiki
node_ingest -->|"refines sources"| node_refiner
node_ingest -->|"triages papers"| node_pdf
node_ingest -->|"builds graph"| node_graphify
node_ingest -->|"analyzes gaps"| node_gapanalysis
node_ingest -->|"creates session"| node_storage
node_gapanalysis -->|"reads corpus"| node_storage
node_gapanalysis -->|"uses chunks"| node_chunker
node_proposal -->|"reads session"| node_storage
node_proposal -->|"finds papers"| node_academic
node_proposal -->|"extracts bookends"| node_pdf
node_proposal -->|"scores papers"| node_matcher
node_proposal -->|"generates proposal"| node_synthesis
node_bridge -->|"queries graph"| node_proxy
node_proxy -->|"interrogates graph"| node_graphify
node_graphview -->|"sends queries"| node_bridge
node_history -->|"requests sessions"| node_bridge
node_review -->|"exports proposal"| node_bridge
node_export -->|"exports session"| node_workspace
node_workspace -->|"reads artifacts"| node_storage
node_workspace -->|"creates documents"| node_googleapis
node_graphify -->|"routes model calls"| node_proxy
node_proxy -->|"forwards requests"| node_vertex
node_academic -->|"triages PDFs"| node_pdf
node_documents -.->|"displays artifacts"| node_storage

click node_interface "https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/App/ResearchBot/ContentView.swift"
click node_bridge "https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/App/ResearchBot/PythonBridge.swift"
click node_history "https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/App/ResearchBot/HistoryView.swift"
click node_graphview "https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/App/ResearchBot/GraphTerminalView.swift"
click node_review "https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/App/ResearchBot/ProposalReviewView.swift"
click node_documents "https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/App/ResearchBot/MarkdownViewer.swift"
click node_entry "https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/main.py"
click node_ingest "https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/application/IngestSeedUseCase.py"
click node_proposal "https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/application/ProposalOrchestrator.py"
click node_export "https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/application/ExportWorkspaceUseCase.py"
click node_inputanalysis "https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/application/InputAnalyzer.py"
click node_academic "https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/infrastructure/AcademicScraper.py"
click node_social "https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/infrastructure/SocialScraper.py"
click node_webwiki "https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/infrastructure/WebScraper.py"
click node_pdf "https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/infrastructure/PdfExtractor.py"
click node_refiner "https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/application/DataRefiner.py"
click node_graphify "https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/infrastructure/GraphifyRunner.py"
click node_gapanalysis "https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/application/GraphAnalyzer.py"
click node_matcher "https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/infrastructure/SemanticMatcher.py"
click node_synthesis "https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/application/ProposalSynthesizer.py"
click node_chunker "https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/infrastructure/TextChunker.py"
click node_storage "https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/infrastructure/FileStorage.py"
click node_proxy "https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/infrastructure/VertexProxy.py"
click node_workspace "https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/infrastructure/GoogleWorkspaceManager.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_interface,node_bridge,node_history,node_graphview,node_review,node_documents toneBlue
class node_entry,node_ingest,node_proposal,node_export toneAmber
class node_inputanalysis,node_academic,node_social,node_webwiki,node_pdf,node_googleapis toneMint
class node_refiner,node_graphify,node_gapanalysis,node_matcher,node_synthesis,node_chunker toneRose
class node_storage,node_proxy,node_workspace,node_researcher,node_vertex toneIndigo
```

## Components

### macOS Client

- [Research UI](https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/App/ResearchBot/ContentView.swift): `ResearchGraphApp/App/ResearchBot/ContentView.swift`
- [Python Bridge](https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/App/ResearchBot/PythonBridge.swift): `ResearchGraphApp/App/ResearchBot/PythonBridge.swift`
- [Session History](https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/App/ResearchBot/HistoryView.swift): `ResearchGraphApp/App/ResearchBot/HistoryView.swift`
- [Graph Explorer](https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/App/ResearchBot/GraphTerminalView.swift): `ResearchGraphApp/App/ResearchBot/GraphTerminalView.swift`
- [Proposal Review](https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/App/ResearchBot/ProposalReviewView.swift): `ResearchGraphApp/App/ResearchBot/ProposalReviewView.swift`
- [Document Viewer](https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/App/ResearchBot/MarkdownViewer.swift): `ResearchGraphApp/App/ResearchBot/MarkdownViewer.swift`

### Backend Orchestration

- [Command Entry](https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/main.py): `ResearchGraphApp/Backend/main.py`
- [Research Ingestion](https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/application/IngestSeedUseCase.py): `ResearchGraphApp/Backend/application/IngestSeedUseCase.py`
- [Proposal Orchestrator](https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/application/ProposalOrchestrator.py): `ResearchGraphApp/Backend/application/ProposalOrchestrator.py`
- [Workspace Export](https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/application/ExportWorkspaceUseCase.py): `ResearchGraphApp/Backend/application/ExportWorkspaceUseCase.py`

### Research Discovery

- [Input Analysis](https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/application/InputAnalyzer.py): `ResearchGraphApp/Backend/application/InputAnalyzer.py`
- [Academic Search](https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/infrastructure/AcademicScraper.py): `ResearchGraphApp/Backend/infrastructure/AcademicScraper.py`
- [Social Search](https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/infrastructure/SocialScraper.py): `ResearchGraphApp/Backend/infrastructure/SocialScraper.py`
- [Web and Wiki](https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/infrastructure/WebScraper.py): `ResearchGraphApp/Backend/infrastructure/WebScraper.py`
- [PDF Extraction](https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/infrastructure/PdfExtractor.py): `ResearchGraphApp/Backend/infrastructure/PdfExtractor.py`

### Analysis and Synthesis

- [Data Refinement](https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/application/DataRefiner.py): `ResearchGraphApp/Backend/application/DataRefiner.py`
- [Graph Construction](https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/infrastructure/GraphifyRunner.py): `ResearchGraphApp/Backend/infrastructure/GraphifyRunner.py`
- [Gap Analysis](https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/application/GraphAnalyzer.py): `ResearchGraphApp/Backend/application/GraphAnalyzer.py`
- [Paper Matching](https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/infrastructure/SemanticMatcher.py): `ResearchGraphApp/Backend/infrastructure/SemanticMatcher.py`
- [Proposal Synthesis](https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/application/ProposalSynthesizer.py): `ResearchGraphApp/Backend/application/ProposalSynthesizer.py`
- [Text Chunking](https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/infrastructure/TextChunker.py): `ResearchGraphApp/Backend/infrastructure/TextChunker.py`

### Session Data and Integrations

- [Session Storage](https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/infrastructure/FileStorage.py): `ResearchGraphApp/Backend/infrastructure/FileStorage.py`
- [Vertex Proxy](https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/infrastructure/VertexProxy.py): `ResearchGraphApp/Backend/infrastructure/VertexProxy.py`
- [Google Workspace](https://github.com/sethum-vs/researchbot/blob/main/ResearchGraphApp/Backend/infrastructure/GoogleWorkspaceManager.py): `ResearchGraphApp/Backend/infrastructure/GoogleWorkspaceManager.py`

### Other components

- **Researcher**
- **Vertex AI**
- **Google APIs**

## Connections

- Researcher → Research UI: submits topic (evidence: `README.md`)
- Research UI → Python Bridge: starts runs (evidence: `ResearchGraphApp/App/ResearchBot/ContentView.swift`)
- Python Bridge → Command Entry: invokes commands (evidence: `README.md`)
- Command Entry → Research Ingestion: dispatches ingestion (evidence: `ResearchGraphApp/Backend/main.py`)
- Command Entry → Proposal Orchestrator: dispatches proposal (evidence: `ResearchGraphApp/Backend/main.py`)
- Command Entry → Workspace Export: dispatches export (evidence: `ResearchGraphApp/Backend/main.py`)
- Research Ingestion → Input Analysis: analyzes seed (evidence: `ResearchGraphApp/Backend/application/IngestSeedUseCase.py`)
- Research Ingestion → Academic Search: searches papers (evidence: `ResearchGraphApp/Backend/application/IngestSeedUseCase.py`)
- Research Ingestion → Social Search: gathers social data (evidence: `README.md`)
- Research Ingestion → Web and Wiki: gathers web sources (evidence: `ResearchGraphApp/Backend/application/IngestSeedUseCase.py`)
- Research Ingestion → Data Refinement: refines sources (evidence: `README.md`)
- Research Ingestion → PDF Extraction: triages papers (evidence: `README.md`)
- Research Ingestion → Graph Construction: builds graph (evidence: `README.md`)
- Research Ingestion → Gap Analysis: analyzes gaps (evidence: `ResearchGraphApp/Backend/application/IngestSeedUseCase.py`)
- Research Ingestion → Session Storage: creates session (evidence: `ResearchGraphApp/Backend/application/IngestSeedUseCase.py`)
- Gap Analysis → Session Storage: reads corpus (evidence: `ResearchGraphApp/Backend/application/GraphAnalyzer.py`)
- Gap Analysis → Text Chunking: uses chunks (evidence: `ResearchGraphApp/Backend/application/GraphAnalyzer.py`)
- Proposal Orchestrator → Session Storage: reads session (evidence: `ResearchGraphApp/Backend/application/ProposalOrchestrator.py`)
- Proposal Orchestrator → Academic Search: finds papers (evidence: `ResearchGraphApp/Backend/application/ProposalOrchestrator.py`)
- Proposal Orchestrator → PDF Extraction: extracts bookends (evidence: `ResearchGraphApp/Backend/application/ProposalOrchestrator.py`)
- Proposal Orchestrator → Paper Matching: scores papers (evidence: `ResearchGraphApp/Backend/application/ProposalOrchestrator.py`)
- Proposal Orchestrator → Proposal Synthesis: generates proposal (evidence: `ResearchGraphApp/Backend/application/ProposalOrchestrator.py`)
- Python Bridge → Vertex Proxy: queries graph (evidence: `README.md`)
- Vertex Proxy → Graph Construction: interrogates graph (evidence: `README.md`)
- Graph Explorer → Python Bridge: sends queries (evidence: `ResearchGraphApp/App/ResearchBot/GraphTerminalView.swift`)
- Session History → Python Bridge: requests sessions (evidence: `ResearchGraphApp/App/ResearchBot/HistoryView.swift`)
- Proposal Review → Python Bridge: exports proposal (evidence: `ResearchGraphApp/App/ResearchBot/ProposalReviewView.swift`)
- Workspace Export → Google Workspace: exports session (evidence: `ResearchGraphApp/Backend/application/ExportWorkspaceUseCase.py`)
- Google Workspace → Session Storage: reads artifacts (evidence: `ResearchGraphApp/Backend/infrastructure/GoogleWorkspaceManager.py`)
- Google Workspace → Google APIs: creates documents (evidence: `README.md`)
- Graph Construction → Vertex Proxy: routes model calls (evidence: `README.md`)
- Vertex Proxy → Vertex AI: forwards requests (evidence: `README.md`)
- Academic Search → PDF Extraction: triages PDFs (evidence: `ResearchGraphApp/Backend/infrastructure/AcademicScraper.py`)
- Document Viewer → Session Storage: displays artifacts