# ai4s-research/open-science architecture

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

- Interactive diagram: https://gitdiagram.com/ai4s-research/open-science
- Repository: https://github.com/ai4s-research/open-science

## Overview

Open Science Desktop is a local-first, model-agnostic AI research workbench. A user starts a session, works with an agent through the UI or CLI, and produces inspectable artifacts and reproducible runs whose provenance links outputs to their inputs and conversation. The desktop and headless server share the Rust core and gateway; the TypeScript SDK connects clients to the agent runtime. The README also documents projects and memory, notebooks, browser control, remote compute, and ACP integrations. Wiring for unsampled subsystems is limited to documented capabilities.

Main entry points: [`crates/osd-core/src/runtime.rs`](https://github.com/ai4s-research/open-science/blob/master/crates/osd-core/src/runtime.rs) (Agent Runtime), [`apps/desktop/src/app/router.tsx`](https://github.com/ai4s-research/open-science/blob/master/apps/desktop/src/app/router.tsx) (Workbench Routes), [`crates/osd-core/src/project.rs`](https://github.com/ai4s-research/open-science/blob/master/crates/osd-core/src/project.rs) (Workspace Files), [`apps/desktop/src/main.tsx`](https://github.com/ai4s-research/open-science/blob/master/apps/desktop/src/main.tsx) (Desktop Web UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User Clients"]
  node_webui["Desktop Web UI<br/>[main.tsx]"]
  node_routes["Workbench Routes<br/>[router.tsx]"]
  node_cli["osd CLI<br/>[main.rs]"]
end

subgraph group_agent["Agent Runtime"]
  node_sdk["Client SDK<br/>[index.ts]"]
  node_opencode["OpenCode Client<br/>[OpenCodeClient.ts]"]
  node_runtime["Agent Runtime<br/>[runtime.rs]"]
  node_sidecar["OpenCode Sidecar"]
end

subgraph group_research["Research Workflow"]
  node_projects["Projects<br/>[project.rs]"]
  node_sessions["Sessions &amp; History<br/>[runs.rs]"]
  node_runs["Reproducible Runs<br/>[runs.rs]"]
  node_provenance["Artifact Provenance<br/>[provenance.rs]"]
  node_notebooks["Notebook Runtime<br/>[jupyter.rs]"]
  node_inspector["Artifact Inspector"]
end

subgraph group_platform["Workspace Platform"]
  node_core["Headless Core<br/>[lib.rs]"]
  node_gateway["Authenticated Gateway<br/>[gateway.rs]"]
  node_workspace["Workspace Files<br/>[project.rs]"]
end

subgraph group_integrations["Integrations"]
  node_browser["Browser Control<br/>[browser.rs]"]
  node_remote["Remote Compute<br/>[ssh_session.rs]"]
  node_acp["ACP Bridge<br/>[server.ts]"]
end

node_user(("Researcher"))
node_editor(("External Editor"))
node_providers["Model Providers"]

node_user -->|"uses"| node_webui
node_webui -->|"routes to"| node_routes
node_user -->|"commands"| node_cli
node_routes -->|"client access"| node_sdk
node_cli -->|"API requests"| node_gateway
node_sdk -->|"client requests"| node_opencode
node_opencode -->|"HTTP and events"| node_sidecar
node_core -->|"provides runtime"| node_runtime
node_runtime -->|"starts and manages"| node_sidecar
node_core -->|"serves"| node_gateway
node_gateway -->|"serves UI"| node_webui
node_runtime -->|"model requests"| node_providers
node_runtime -->|"records conversations"| node_sessions
node_runtime -->|"works in"| node_workspace
node_projects -->|"organize"| node_workspace
node_runs -->|"capture outputs"| node_workspace
node_provenance -->|"links artifacts"| node_workspace
node_routes -->|"notebook access"| node_notebooks
node_routes -->|"inspect artifacts"| node_inspector
node_runtime -.->|"browser tools"| node_browser
node_runtime -.->|"remote execution"| node_remote
node_editor -.->|"ACP requests"| node_acp
node_acp -.->|"translates requests"| node_runtime

click node_webui "https://github.com/ai4s-research/open-science/blob/master/apps/desktop/src/main.tsx"
click node_routes "https://github.com/ai4s-research/open-science/blob/master/apps/desktop/src/app/router.tsx"
click node_cli "https://github.com/ai4s-research/open-science/blob/master/crates/osd-cli/src/main.rs"
click node_sdk "https://github.com/ai4s-research/open-science/blob/master/packages/sdk/src/index.ts"
click node_opencode "https://github.com/ai4s-research/open-science/blob/master/packages/sdk/src/OpenCodeClient.ts"
click node_core "https://github.com/ai4s-research/open-science/blob/master/crates/osd-core/src/lib.rs"
click node_runtime "https://github.com/ai4s-research/open-science/blob/master/crates/osd-core/src/runtime.rs"
click node_gateway "https://github.com/ai4s-research/open-science/blob/master/crates/osd-core/src/gateway.rs"
click node_workspace "https://github.com/ai4s-research/open-science/blob/master/crates/osd-core/src/project.rs"
click node_projects "https://github.com/ai4s-research/open-science/blob/master/crates/osd-core/src/project.rs"
click node_sessions "https://github.com/ai4s-research/open-science/blob/master/crates/osd-core/src/runs.rs"
click node_runs "https://github.com/ai4s-research/open-science/blob/master/crates/osd-core/src/runs.rs"
click node_provenance "https://github.com/ai4s-research/open-science/blob/master/crates/osd-core/src/provenance.rs"
click node_notebooks "https://github.com/ai4s-research/open-science/blob/master/apps/desktop/src-tauri/src/jupyter.rs"
click node_inspector "https://github.com/ai4s-research/open-science/blob/master/apps/desktop/src/components/inspector/ArtifactInspector.tsx"
click node_browser "https://github.com/ai4s-research/open-science/blob/master/apps/desktop/src-tauri/src/browser.rs"
click node_remote "https://github.com/ai4s-research/open-science/blob/master/apps/desktop/src-tauri/src/ssh_session.rs"
click node_acp "https://github.com/ai4s-research/open-science/blob/master/packages/sdk/src/acp/server.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_webui,node_routes,node_cli toneBlue
class node_sdk,node_opencode,node_runtime,node_sidecar toneAmber
class node_projects,node_sessions,node_runs,node_provenance,node_notebooks,node_inspector toneMint
class node_core,node_gateway,node_workspace toneRose
class node_browser,node_remote,node_acp,node_user,node_editor,node_providers toneIndigo
```

## Components

### User Clients

- [Desktop Web UI](https://github.com/ai4s-research/open-science/blob/master/apps/desktop/src/main.tsx): `apps/desktop/src/main.tsx`
- [Workbench Routes](https://github.com/ai4s-research/open-science/blob/master/apps/desktop/src/app/router.tsx): `apps/desktop/src/app/router.tsx`
- [osd CLI](https://github.com/ai4s-research/open-science/blob/master/crates/osd-cli/src/main.rs): `crates/osd-cli/src/main.rs`

### Agent Runtime

- [Client SDK](https://github.com/ai4s-research/open-science/blob/master/packages/sdk/src/index.ts): `packages/sdk/src/index.ts`
- [OpenCode Client](https://github.com/ai4s-research/open-science/blob/master/packages/sdk/src/OpenCodeClient.ts): `packages/sdk/src/OpenCodeClient.ts`
- [Agent Runtime](https://github.com/ai4s-research/open-science/blob/master/crates/osd-core/src/runtime.rs): `crates/osd-core/src/runtime.rs`
- **OpenCode Sidecar**

### Research Workflow

- [Projects](https://github.com/ai4s-research/open-science/blob/master/crates/osd-core/src/project.rs): `crates/osd-core/src/project.rs`
- [Sessions & History](https://github.com/ai4s-research/open-science/blob/master/crates/osd-core/src/runs.rs): `crates/osd-core/src/runs.rs`
- [Reproducible Runs](https://github.com/ai4s-research/open-science/blob/master/crates/osd-core/src/runs.rs): `crates/osd-core/src/runs.rs`
- [Artifact Provenance](https://github.com/ai4s-research/open-science/blob/master/crates/osd-core/src/provenance.rs): `crates/osd-core/src/provenance.rs`
- [Notebook Runtime](https://github.com/ai4s-research/open-science/blob/master/apps/desktop/src-tauri/src/jupyter.rs): `apps/desktop/src-tauri/src/jupyter.rs`
- [Artifact Inspector](https://github.com/ai4s-research/open-science/blob/master/apps/desktop/src/components/inspector/ArtifactInspector.tsx): `apps/desktop/src/components/inspector/ArtifactInspector.tsx`

### Workspace Platform

- [Headless Core](https://github.com/ai4s-research/open-science/blob/master/crates/osd-core/src/lib.rs): `crates/osd-core/src/lib.rs`
- [Authenticated Gateway](https://github.com/ai4s-research/open-science/blob/master/crates/osd-core/src/gateway.rs): `crates/osd-core/src/gateway.rs`
- [Workspace Files](https://github.com/ai4s-research/open-science/blob/master/crates/osd-core/src/project.rs): `crates/osd-core/src/project.rs`

### Integrations

- [Browser Control](https://github.com/ai4s-research/open-science/blob/master/apps/desktop/src-tauri/src/browser.rs): `apps/desktop/src-tauri/src/browser.rs`
- [Remote Compute](https://github.com/ai4s-research/open-science/blob/master/apps/desktop/src-tauri/src/ssh_session.rs): `apps/desktop/src-tauri/src/ssh_session.rs`
- [ACP Bridge](https://github.com/ai4s-research/open-science/blob/master/packages/sdk/src/acp/server.ts): `packages/sdk/src/acp/server.ts`

### Other components

- **Researcher**
- **External Editor**
- **Model Providers**

## Connections

- Researcher → Desktop Web UI: uses
- Desktop Web UI → Workbench Routes: routes to
- Researcher → osd CLI: commands
- Workbench Routes → Client SDK: client access
- osd CLI → Authenticated Gateway: API requests
- Client SDK → OpenCode Client: client requests
- OpenCode Client → OpenCode Sidecar: HTTP and events
- Headless Core → Agent Runtime: provides runtime
- Agent Runtime → OpenCode Sidecar: starts and manages
- Headless Core → Authenticated Gateway: serves
- Authenticated Gateway → Desktop Web UI: serves UI
- Agent Runtime → Model Providers: model requests
- Agent Runtime → Sessions & History: records conversations
- Agent Runtime → Workspace Files: works in
- Projects → Workspace Files: organize
- Reproducible Runs → Workspace Files: capture outputs
- Artifact Provenance → Workspace Files: links artifacts
- Workbench Routes → Notebook Runtime: notebook access
- Workbench Routes → Artifact Inspector: inspect artifacts
- Agent Runtime → Browser Control: browser tools
- Agent Runtime → Remote Compute: remote execution
- External Editor → ACP Bridge: ACP requests
- ACP Bridge → Agent Runtime: translates requests