# k-dense-ai/k-dense-byok architecture

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

- Interactive diagram: https://gitdiagram.com/k-dense-ai/k-dense-byok
- Repository: https://github.com/k-dense-ai/k-dense-byok

## Overview

K-Dense BYOK is a local-first, bring-your-own-key AI research workspace. A scientist describes a task in the web app; the backend opens a project-scoped agent session, resolves a model, and runs research work that can inspect files, execute analyses, and preserve results and notebook history. The product also includes scientific skills and workflows, evidence review, specialist subagents, compute jobs, and project cost controls. The graph combines documented capabilities with visible backend relationships; several feature implementations were not sampled, so those links are shown only when documented or left unverified.

Main entry points: [`server/src/agent/session-registry.ts`](https://github.com/k-dense-ai/k-dense-byok/blob/main/server/src/agent/session-registry.ts) (Live sessions), [`server/src/api/sessions.ts`](https://github.com/k-dense-ai/k-dense-byok/blob/main/server/src/api/sessions.ts) (Session routes), [`server/src/agent/run-pipeline.ts`](https://github.com/k-dense-ai/k-dense-byok/blob/main/server/src/agent/run-pipeline.ts) (Run pipeline), [`server/src/agent/models.ts`](https://github.com/k-dense-ai/k-dense-byok/blob/main/server/src/agent/models.ts) (Model resolution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Research workspace"]
  node_webapp["Web workspace<br/>[page.tsx]"]
end

subgraph group_runtime["Agent runtime"]
  node_api["HTTP API<br/>[index.ts]"]
  node_sessions["Session routes<br/>[sessions.ts]"]
  node_pipeline["Run pipeline<br/>[run-pipeline.ts]"]
  node_sessionreg["Live sessions"]
end

subgraph group_workspace["Project and records"]
  node_projects["Projects<br/>[projects.ts]"]
  node_sandbox[("Project files<br/>[sandbox-fs.ts]")]
  node_ledger[("Cost ledger<br/>[ledger.ts]")]
end

subgraph group_capabilities["Research capabilities"]
  node_notebook["Lab notebook<br/>[notebook.ts]"]
  node_evidence["Evidence packages<br/>[storage.ts]"]
  node_skills["Scientific skills<br/>[skills.ts]"]
  node_subagents["Specialist agents<br/>[subagents.ts]"]
end

subgraph group_services["Models and compute"]
  node_models["Model resolution<br/>[models.ts]"]
  node_providers["Model providers<br/>[provider-auth.ts]"]
  node_modal["Compute jobs<br/>[manager.ts]"]
  node_modaltool["Compute tools<br/>[modal-tool.ts]"]
end

node_scientist(("Scientist"))
node_modelservice{{"Selected AI provider"}}

node_scientist -->|"describes task"| node_webapp
node_webapp -.->|"uses"| node_api
node_api -->|"registers routes"| node_sessions
node_sessions -->|"creates sessions"| node_sessionreg
node_sessions -.->|"starts runs"| node_pipeline
node_pipeline -->|"pins session"| node_sessionreg
node_sessionreg -->|"sets up runtime"| node_models
node_models -->|"resolves authentication"| node_providers
node_models -.->|"sends model requests"| node_modelservice
node_projects -->|"resolves paths"| node_sandbox
node_pipeline -->|"tracks run spend"| node_ledger
node_sessions -.->|"serves notebook data"| node_notebook
node_scientist -->|"provides research files"| node_sandbox
node_pipeline -.->|"records file activity"| node_evidence
node_sessionreg -.->|"activates skills"| node_skills
node_sessionreg -.->|"delegates work"| node_subagents
node_sessionreg -->|"installs compute tools"| node_modaltool
node_modaltool -.->|"submits jobs"| node_modal
node_modal -->|"stages project files"| node_sandbox

click node_webapp "https://github.com/k-dense-ai/k-dense-byok/blob/main/web/src/app/page.tsx"
click node_api "https://github.com/k-dense-ai/k-dense-byok/blob/main/server/src/index.ts"
click node_sessions "https://github.com/k-dense-ai/k-dense-byok/blob/main/server/src/api/sessions.ts"
click node_pipeline "https://github.com/k-dense-ai/k-dense-byok/blob/main/server/src/agent/run-pipeline.ts"
click node_sessionreg "https://github.com/k-dense-ai/k-dense-byok/blob/main/server/src/agent/session-registry.ts"
click node_models "https://github.com/k-dense-ai/k-dense-byok/blob/main/server/src/agent/models.ts"
click node_providers "https://github.com/k-dense-ai/k-dense-byok/blob/main/server/src/agent/provider-auth.ts"
click node_projects "https://github.com/k-dense-ai/k-dense-byok/blob/main/server/src/projects.ts"
click node_sandbox "https://github.com/k-dense-ai/k-dense-byok/blob/main/server/src/sandbox-fs.ts"
click node_ledger "https://github.com/k-dense-ai/k-dense-byok/blob/main/server/src/cost/ledger.ts"
click node_notebook "https://github.com/k-dense-ai/k-dense-byok/blob/main/server/src/agent/notebook.ts"
click node_evidence "https://github.com/k-dense-ai/k-dense-byok/blob/main/server/src/evidence/storage.ts"
click node_skills "https://github.com/k-dense-ai/k-dense-byok/blob/main/server/src/agent/skills.ts"
click node_subagents "https://github.com/k-dense-ai/k-dense-byok/blob/main/server/src/agent/subagents.ts"
click node_modal "https://github.com/k-dense-ai/k-dense-byok/blob/main/server/src/modal/manager.ts"
click node_modaltool "https://github.com/k-dense-ai/k-dense-byok/blob/main/server/src/agent/modal-tool.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_webapp toneBlue
class node_api,node_sessions,node_pipeline,node_sessionreg toneAmber
class node_projects,node_sandbox,node_ledger toneMint
class node_notebook,node_evidence,node_skills,node_subagents toneRose
class node_models,node_providers,node_modal,node_modaltool,node_scientist,node_modelservice toneIndigo
```

## Components

### Research workspace

- [Web workspace](https://github.com/k-dense-ai/k-dense-byok/blob/main/web/src/app/page.tsx): `web/src/app/page.tsx`

### Agent runtime

- [HTTP API](https://github.com/k-dense-ai/k-dense-byok/blob/main/server/src/index.ts): `server/src/index.ts`
- [Session routes](https://github.com/k-dense-ai/k-dense-byok/blob/main/server/src/api/sessions.ts): `server/src/api/sessions.ts`
- [Run pipeline](https://github.com/k-dense-ai/k-dense-byok/blob/main/server/src/agent/run-pipeline.ts): `server/src/agent/run-pipeline.ts`
- [Live sessions](https://github.com/k-dense-ai/k-dense-byok/blob/main/server/src/agent/session-registry.ts): `server/src/agent/session-registry.ts`

### Project and records

- [Projects](https://github.com/k-dense-ai/k-dense-byok/blob/main/server/src/projects.ts): `server/src/projects.ts`
- [Project files](https://github.com/k-dense-ai/k-dense-byok/blob/main/server/src/sandbox-fs.ts): `server/src/sandbox-fs.ts`
- [Cost ledger](https://github.com/k-dense-ai/k-dense-byok/blob/main/server/src/cost/ledger.ts): `server/src/cost/ledger.ts`

### Research capabilities

- [Lab notebook](https://github.com/k-dense-ai/k-dense-byok/blob/main/server/src/agent/notebook.ts): `server/src/agent/notebook.ts`
- [Evidence packages](https://github.com/k-dense-ai/k-dense-byok/blob/main/server/src/evidence/storage.ts): `server/src/evidence/storage.ts`
- [Scientific skills](https://github.com/k-dense-ai/k-dense-byok/blob/main/server/src/agent/skills.ts): `server/src/agent/skills.ts`
- [Specialist agents](https://github.com/k-dense-ai/k-dense-byok/blob/main/server/src/agent/subagents.ts): `server/src/agent/subagents.ts`

### Models and compute

- [Model resolution](https://github.com/k-dense-ai/k-dense-byok/blob/main/server/src/agent/models.ts): `server/src/agent/models.ts`
- [Model providers](https://github.com/k-dense-ai/k-dense-byok/blob/main/server/src/agent/provider-auth.ts): `server/src/agent/provider-auth.ts`
- [Compute jobs](https://github.com/k-dense-ai/k-dense-byok/blob/main/server/src/modal/manager.ts): `server/src/modal/manager.ts`
- [Compute tools](https://github.com/k-dense-ai/k-dense-byok/blob/main/server/src/agent/modal-tool.ts): `server/src/agent/modal-tool.ts`

### Other components

- **Scientist**
- **Selected AI provider**

## Connections

- Scientist → Web workspace: describes task (evidence: `README.md`)
- Web workspace → HTTP API: uses
- HTTP API → Session routes: registers routes (evidence: `server/src/index.ts`)
- Session routes → Live sessions: creates sessions (evidence: `server/src/api/sessions.ts`)
- Session routes → Run pipeline: starts runs (evidence: `server/src/api/sessions.ts`)
- Run pipeline → Live sessions: pins session (evidence: `server/src/agent/run-pipeline.ts`)
- Live sessions → Model resolution: sets up runtime (evidence: `server/src/agent/session-registry.ts`)
- Model resolution → Model providers: resolves authentication (evidence: `server/src/agent/models.ts`)
- Model resolution → Selected AI provider: sends model requests
- Projects → Project files: resolves paths (evidence: `server/src/sandbox-fs.ts`)
- Run pipeline → Cost ledger: tracks run spend (evidence: `server/src/agent/run-pipeline.ts`)
- Session routes → Lab notebook: serves notebook data
- Scientist → Project files: provides research files (evidence: `README.md`)
- Run pipeline → Evidence packages: records file activity
- Live sessions → Scientific skills: activates skills
- Live sessions → Specialist agents: delegates work
- Live sessions → Compute tools: installs compute tools (evidence: `server/src/agent/session-registry.ts`)
- Compute tools → Compute jobs: submits jobs
- Compute jobs → Project files: stages project files (evidence: `server/src/modal/manager.ts`)