# companion-inc/feynman architecture

> Architecture diagram of the GitHub repository companion-inc/feynman, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/companion-inc/feynman
- Repository: https://github.com/companion-inc/feynman

## Overview

Feynman is an AI research agent and local science workbench. A user invokes the CLI with a research, ranking, paper, replication, recipe, or server command. CLI dispatches into Pi-backed model execution and research tools, which query scientific sources, normalize evidence, and return cited results. The optional workbench serves projects, chat, artifacts, notebooks, compute, and review through a local HTTP server and web UI, persisting state in an org SQLite database. The graph emphasizes sampled runtime paths; many individual database connectors are represented by their shared registries.

Main entry points: [`src/workbench/server.ts`](https://github.com/companion-inc/feynman/blob/main/src/workbench/server.ts) (Workbench Server), [`extensions/research-tools.ts`](https://github.com/companion-inc/feynman/blob/main/extensions/research-tools.ts) (Research Tools), [`src/cli.ts`](https://github.com/companion-inc/feynman/blob/main/src/cli.ts) (CLI Entry), [`src/model/commands.ts`](https://github.com/companion-inc/feynman/blob/main/src/model/commands.ts) (Command Routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and Commands"]
  node_cli["CLI Entry<br/>[cli.ts]"]
  node_command_router["Command Routing<br/>[commands.ts]"]
end

subgraph group_research["Research and Evidence"]
  node_research_tools["Research Tools<br/>[research-tools.ts]"]
  node_database_registry["Science Databases"]
  node_variant_sources["Variant Sources"]
  node_pubmed_parser["PubMed Parser"]
  node_web_search["Web Search<br/>[web-search.ts]"]
  node_paper_rank["PaperRank<br/>[paper-rank.ts]"]
end

subgraph group_runtime["Model Runtime"]
  node_pi_runtime["Pi Runtime<br/>[runtime.ts]"]
  node_pi_launch["Pi Launcher<br/>[launch.ts]"]
  node_model_catalog["Model Catalog<br/>[catalog.ts]"]
end

subgraph group_workbench["Science Workbench"]
  node_workbench_server["Workbench Server<br/>[server.ts]"]
  node_workbench_ui["Workbench UI<br/>[main.tsx]"]
  node_chat_runtime["Chat Runtime<br/>[chat-runtime.ts]"]
  node_notebook_execution["Notebook Execution"]
  node_artifact_actions["Artifact Actions"]
end

subgraph group_state["State and Integrations"]
  node_org_database[("Workbench Database<br/>[org-database.ts]")]
  node_settings_store["Settings Store<br/>[settings-store.ts]"]
  node_oauth_store["OAuth Store<br/>[oauth-store.ts]"]
end

node_user(("Researcher"))
node_science_apis[("Science APIs")]
node_model_providers["Model Providers"]
node_external_files[("Local Files")]

node_user -->|"invokes"| node_cli
node_cli -->|"dispatches"| node_command_router
node_command_router -->|"runs research"| node_research_tools
node_command_router -->|"runs ranking"| node_paper_rank
node_command_router -->|"runs search"| node_web_search
node_research_tools -->|"selects sources"| node_database_registry
node_database_registry -->|"dispatches variants"| node_variant_sources
node_variant_sources -->|"queries variants"| node_science_apis
node_research_tools -->|"parses papers"| node_pubmed_parser
node_research_tools -->|"queries science"| node_science_apis
node_web_search -->|"fetches evidence"| node_science_apis
node_paper_rank -->|"collects evidence"| node_research_tools
node_cli -->|"starts agent"| node_pi_launch
node_pi_launch -->|"launches runtime"| node_pi_runtime
node_pi_runtime -->|"resolves model"| node_model_catalog
node_pi_runtime -.->|"calls models"| node_model_providers
node_cli -->|"serves workbench"| node_workbench_server
node_workbench_ui -->|"calls API"| node_workbench_server
node_workbench_server -->|"submits chat"| node_chat_runtime
node_workbench_server -->|"executes cells"| node_notebook_execution
node_workbench_server -->|"handles artifacts"| node_artifact_actions
node_workbench_server -->|"reads settings"| node_settings_store
node_workbench_server -->|"finishes OAuth"| node_oauth_store
node_chat_runtime -->|"runs agent"| node_pi_runtime
node_artifact_actions -->|"reads artifacts"| node_external_files
node_workbench_server -->|"serves state"| node_org_database
node_org_database -->|"persists state"| node_external_files

click node_cli "https://github.com/companion-inc/feynman/blob/main/src/cli.ts"
click node_command_router "https://github.com/companion-inc/feynman/blob/main/src/model/commands.ts"
click node_research_tools "https://github.com/companion-inc/feynman/blob/main/extensions/research-tools.ts"
click node_database_registry "https://github.com/companion-inc/feynman/blob/main/extensions/research-tools/science-databases.ts"
click node_variant_sources "https://github.com/companion-inc/feynman/blob/main/extensions/research-tools/science-database-variants.ts"
click node_pubmed_parser "https://github.com/companion-inc/feynman/blob/main/extensions/research-tools/science-database-pubmed-parsers.ts"
click node_web_search "https://github.com/companion-inc/feynman/blob/main/src/web-search.ts"
click node_paper_rank "https://github.com/companion-inc/feynman/blob/main/src/rank/paper-rank.ts"
click node_pi_runtime "https://github.com/companion-inc/feynman/blob/main/src/pi/runtime.ts"
click node_pi_launch "https://github.com/companion-inc/feynman/blob/main/src/pi/launch.ts"
click node_model_catalog "https://github.com/companion-inc/feynman/blob/main/src/model/catalog.ts"
click node_workbench_server "https://github.com/companion-inc/feynman/blob/main/src/workbench/server.ts"
click node_workbench_ui "https://github.com/companion-inc/feynman/blob/main/workbench-web/src/main.tsx"
click node_chat_runtime "https://github.com/companion-inc/feynman/blob/main/src/workbench/chat-runtime.ts"
click node_notebook_execution "https://github.com/companion-inc/feynman/blob/main/src/workbench/notebook-execution.ts"
click node_artifact_actions "https://github.com/companion-inc/feynman/blob/main/src/workbench/artifact-actions.ts"
click node_org_database "https://github.com/companion-inc/feynman/blob/main/src/workbench/org-database.ts"
click node_settings_store "https://github.com/companion-inc/feynman/blob/main/src/workbench/settings-store.ts"
click node_oauth_store "https://github.com/companion-inc/feynman/blob/main/src/workbench/oauth-store.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_cli,node_command_router toneBlue
class node_research_tools,node_database_registry,node_variant_sources,node_pubmed_parser,node_web_search,node_paper_rank,node_science_apis,node_external_files toneAmber
class node_pi_runtime,node_pi_launch,node_model_catalog toneMint
class node_workbench_server,node_workbench_ui,node_chat_runtime,node_notebook_execution,node_artifact_actions toneRose
class node_org_database,node_settings_store,node_oauth_store,node_user,node_model_providers toneIndigo
```

## Components

### Entry and Commands

- [CLI Entry](https://github.com/companion-inc/feynman/blob/main/src/cli.ts): `src/cli.ts`
- [Command Routing](https://github.com/companion-inc/feynman/blob/main/src/model/commands.ts): `src/model/commands.ts`

### Research and Evidence

- [Research Tools](https://github.com/companion-inc/feynman/blob/main/extensions/research-tools.ts): `extensions/research-tools.ts`
- [Science Databases](https://github.com/companion-inc/feynman/blob/main/extensions/research-tools/science-databases.ts): `extensions/research-tools/science-databases.ts`
- [Variant Sources](https://github.com/companion-inc/feynman/blob/main/extensions/research-tools/science-database-variants.ts): `extensions/research-tools/science-database-variants.ts`
- [PubMed Parser](https://github.com/companion-inc/feynman/blob/main/extensions/research-tools/science-database-pubmed-parsers.ts): `extensions/research-tools/science-database-pubmed-parsers.ts`
- [Web Search](https://github.com/companion-inc/feynman/blob/main/src/web-search.ts): `src/web-search.ts`
- [PaperRank](https://github.com/companion-inc/feynman/blob/main/src/rank/paper-rank.ts): `src/rank/paper-rank.ts`

### Model Runtime

- [Pi Runtime](https://github.com/companion-inc/feynman/blob/main/src/pi/runtime.ts): `src/pi/runtime.ts`
- [Pi Launcher](https://github.com/companion-inc/feynman/blob/main/src/pi/launch.ts): `src/pi/launch.ts`
- [Model Catalog](https://github.com/companion-inc/feynman/blob/main/src/model/catalog.ts): `src/model/catalog.ts`

### Science Workbench

- [Workbench Server](https://github.com/companion-inc/feynman/blob/main/src/workbench/server.ts): `src/workbench/server.ts`
- [Workbench UI](https://github.com/companion-inc/feynman/blob/main/workbench-web/src/main.tsx): `workbench-web/src/main.tsx`
- [Chat Runtime](https://github.com/companion-inc/feynman/blob/main/src/workbench/chat-runtime.ts): `src/workbench/chat-runtime.ts`
- [Notebook Execution](https://github.com/companion-inc/feynman/blob/main/src/workbench/notebook-execution.ts): `src/workbench/notebook-execution.ts`
- [Artifact Actions](https://github.com/companion-inc/feynman/blob/main/src/workbench/artifact-actions.ts): `src/workbench/artifact-actions.ts`

### State and Integrations

- [Workbench Database](https://github.com/companion-inc/feynman/blob/main/src/workbench/org-database.ts): `src/workbench/org-database.ts`
- [Settings Store](https://github.com/companion-inc/feynman/blob/main/src/workbench/settings-store.ts): `src/workbench/settings-store.ts`
- [OAuth Store](https://github.com/companion-inc/feynman/blob/main/src/workbench/oauth-store.ts): `src/workbench/oauth-store.ts`

### Other components

- **Researcher**
- **Science APIs**
- **Model Providers**
- **Local Files**

## Connections

- Researcher → CLI Entry: invokes
- CLI Entry → Command Routing: dispatches
- Command Routing → Research Tools: runs research
- Command Routing → PaperRank: runs ranking
- Command Routing → Web Search: runs search
- Research Tools → Science Databases: selects sources
- Science Databases → Variant Sources: dispatches variants
- Variant Sources → Science APIs: queries variants
- Research Tools → PubMed Parser: parses papers
- Research Tools → Science APIs: queries science
- Web Search → Science APIs: fetches evidence
- PaperRank → Research Tools: collects evidence
- CLI Entry → Pi Launcher: starts agent
- Pi Launcher → Pi Runtime: launches runtime
- Pi Runtime → Model Catalog: resolves model
- Pi Runtime → Model Providers: calls models
- CLI Entry → Workbench Server: serves workbench
- Workbench UI → Workbench Server: calls API
- Workbench Server → Chat Runtime: submits chat
- Workbench Server → Notebook Execution: executes cells
- Workbench Server → Artifact Actions: handles artifacts
- Workbench Server → Settings Store: reads settings
- Workbench Server → OAuth Store: finishes OAuth
- Chat Runtime → Pi Runtime: runs agent
- Artifact Actions → Local Files: reads artifacts
- Workbench Server → Workbench Database: serves state
- Workbench Database → Local Files: persists state