# lfnovo/open-notebook architecture

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

- Interactive diagram: https://gitdiagram.com/lfnovo/open-notebook
- Repository: https://github.com/lfnovo/open-notebook

## Overview

Open Notebook is a self-hosted research workspace for collecting and organizing sources, then using configurable AI models to search, chat, transform content, and generate podcasts. The principal workflow is user → web interface/API → source processing and notebook storage → embedding/search or contextual chat → cited research results. The map also includes model configuration and podcast generation as major capabilities. Several subsystem links are documented in the README; where source excerpts do not expose runtime wiring, those links are marked unverified or omitted.

Main entry points: [`open_notebook/domain/notebook.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/domain/notebook.py) (Notebooks and notes), [`api/routers`](https://github.com/lfnovo/open-notebook/tree/main/api/routers) (Feature routes), [`open_notebook/ai/models.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/ai/models.py) (Model manager), [`commands/embedding_commands.py`](https://github.com/lfnovo/open-notebook/blob/main/commands/embedding_commands.py) (Embedding jobs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_web["Notebook UI"]
  node_client["API client"]
end

subgraph group_api["API and jobs"]
  node_api_app["REST API<br/>[main.py]"]
  node_api_routes["Feature routes"]
  node_command_service["Job submission<br/>[command_service.py]"]
end

subgraph group_research["Research workflows"]
  node_source_processing["Source processing<br/>[source.py]"]
  node_source_commands["Source jobs<br/>[source_commands.py]"]
  node_embedding_jobs["Embedding jobs"]
  node_search["Search and ask<br/>[ask.py]"]
  node_chat["Research chat<br/>[chat.py]"]
  node_transformations["Transformations<br/>[transformation.py]"]
end

subgraph group_ai["AI and media"]
  node_model_manager["Model manager<br/>[models.py]"]
  node_provider_config["Provider registry"]
  node_podcast_jobs["Podcast generation"]
  node_podcast_service["Podcast service<br/>[podcast_service.py]"]
end

subgraph group_persistence["Domain and storage"]
  node_notebook_domain["Notebooks and notes<br/>[notebook.py]"]
  node_repository["Repository layer<br/>[repository.py]"]
end

node_user(("Researcher"))
node_database[("SurrealDB")]
node_ai_providers{{"AI providers"}}

node_user -->|"uses"| node_web
node_web -.->|"requests data"| node_client
node_client -.->|"calls API"| node_api_app
node_api_app -->|"routes requests"| node_api_routes
node_api_routes -->|"submits jobs"| node_command_service
node_api_routes -.->|"manages records"| node_notebook_domain
node_api_routes -->|"invokes ask flow"| node_search
node_api_routes -.->|"requests podcasts"| node_podcast_service
node_source_processing -->|"uses domain records"| node_notebook_domain
node_source_commands -.->|"runs processing"| node_source_processing
node_command_service -->|"submits embedding jobs"| node_embedding_jobs
node_embedding_jobs -->|"loads sources and notes"| node_notebook_domain
node_embedding_jobs -->|"generates embeddings"| node_model_manager
node_search -.->|"retrieves research context"| node_notebook_domain
node_chat -.->|"uses notebook context"| node_notebook_domain
node_transformations -.->|"transforms content"| node_notebook_domain
node_podcast_service -->|"submits generation"| node_podcast_jobs
node_podcast_jobs -->|"resolves models"| node_model_manager
node_model_manager -.->|"uses provider setup"| node_provider_config
node_model_manager -.->|"calls models"| node_ai_providers
node_notebook_domain -->|"loads and saves"| node_repository
node_repository -->|"queries records"| node_database

click node_web "https://github.com/lfnovo/open-notebook/tree/main/frontend/src/app/(dashboard)"
click node_client "https://github.com/lfnovo/open-notebook/tree/main/frontend/src/lib/api"
click node_api_app "https://github.com/lfnovo/open-notebook/blob/main/api/main.py"
click node_api_routes "https://github.com/lfnovo/open-notebook/tree/main/api/routers"
click node_command_service "https://github.com/lfnovo/open-notebook/blob/main/api/command_service.py"
click node_source_processing "https://github.com/lfnovo/open-notebook/blob/main/open_notebook/graphs/source.py"
click node_source_commands "https://github.com/lfnovo/open-notebook/blob/main/commands/source_commands.py"
click node_embedding_jobs "https://github.com/lfnovo/open-notebook/blob/main/commands/embedding_commands.py"
click node_search "https://github.com/lfnovo/open-notebook/blob/main/open_notebook/graphs/ask.py"
click node_chat "https://github.com/lfnovo/open-notebook/blob/main/open_notebook/graphs/chat.py"
click node_transformations "https://github.com/lfnovo/open-notebook/blob/main/open_notebook/graphs/transformation.py"
click node_notebook_domain "https://github.com/lfnovo/open-notebook/blob/main/open_notebook/domain/notebook.py"
click node_repository "https://github.com/lfnovo/open-notebook/blob/main/open_notebook/database/repository.py"
click node_model_manager "https://github.com/lfnovo/open-notebook/blob/main/open_notebook/ai/models.py"
click node_provider_config "https://github.com/lfnovo/open-notebook/blob/main/open_notebook/ai/provider_registry.py"
click node_podcast_jobs "https://github.com/lfnovo/open-notebook/blob/main/commands/podcast_commands.py"
click node_podcast_service "https://github.com/lfnovo/open-notebook/blob/main/api/podcast_service.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_web,node_client toneBlue
class node_api_app,node_api_routes,node_command_service,node_database toneAmber
class node_source_processing,node_source_commands,node_embedding_jobs,node_search,node_chat,node_transformations toneMint
class node_model_manager,node_provider_config,node_podcast_jobs,node_podcast_service toneRose
class node_notebook_domain,node_repository,node_user,node_ai_providers toneIndigo
```

## Components

### Web experience

- [Notebook UI](https://github.com/lfnovo/open-notebook/tree/main/frontend/src/app/(dashboard)): `frontend/src/app/(dashboard)`
- [API client](https://github.com/lfnovo/open-notebook/tree/main/frontend/src/lib/api): `frontend/src/lib/api`

### API and jobs

- [REST API](https://github.com/lfnovo/open-notebook/blob/main/api/main.py): `api/main.py`
- [Feature routes](https://github.com/lfnovo/open-notebook/tree/main/api/routers): `api/routers`
- [Job submission](https://github.com/lfnovo/open-notebook/blob/main/api/command_service.py): `api/command_service.py`

### Research workflows

- [Source processing](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/graphs/source.py): `open_notebook/graphs/source.py`
- [Source jobs](https://github.com/lfnovo/open-notebook/blob/main/commands/source_commands.py): `commands/source_commands.py`
- [Embedding jobs](https://github.com/lfnovo/open-notebook/blob/main/commands/embedding_commands.py): `commands/embedding_commands.py`
- [Search and ask](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/graphs/ask.py): `open_notebook/graphs/ask.py`
- [Research chat](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/graphs/chat.py): `open_notebook/graphs/chat.py`
- [Transformations](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/graphs/transformation.py): `open_notebook/graphs/transformation.py`

### AI and media

- [Model manager](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/ai/models.py): `open_notebook/ai/models.py`
- [Provider registry](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/ai/provider_registry.py): `open_notebook/ai/provider_registry.py`
- [Podcast generation](https://github.com/lfnovo/open-notebook/blob/main/commands/podcast_commands.py): `commands/podcast_commands.py`
- [Podcast service](https://github.com/lfnovo/open-notebook/blob/main/api/podcast_service.py): `api/podcast_service.py`

### Domain and storage

- [Notebooks and notes](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/domain/notebook.py): `open_notebook/domain/notebook.py`
- [Repository layer](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/database/repository.py): `open_notebook/database/repository.py`

### Other components

- **Researcher**
- **SurrealDB**
- **AI providers**

## Connections

- Researcher → Notebook UI: uses (evidence: `README.md`)
- Notebook UI → API client: requests data
- API client → REST API: calls API
- REST API → Feature routes: routes requests (evidence: `api/main.py`)
- Feature routes → Job submission: submits jobs (evidence: `api/routers/embedding.py`)
- Feature routes → Notebooks and notes: manages records (evidence: `api/routers/embedding.py`)
- Feature routes → Search and ask: invokes ask flow (evidence: `api/routers/search.py`)
- Feature routes → Podcast service: requests podcasts
- Source processing → Notebooks and notes: uses domain records (evidence: `open_notebook/graphs/source.py`)
- Source jobs → Source processing: runs processing
- Job submission → Embedding jobs: submits embedding jobs (evidence: `api/routers/embedding.py`)
- Embedding jobs → Notebooks and notes: loads sources and notes (evidence: `commands/embedding_commands.py`)
- Embedding jobs → Model manager: generates embeddings (evidence: `commands/embedding_commands.py`)
- Search and ask → Notebooks and notes: retrieves research context
- Research chat → Notebooks and notes: uses notebook context
- Transformations → Notebooks and notes: transforms content
- Podcast service → Podcast generation: submits generation (evidence: `api/podcast_service.py`)
- Podcast generation → Model manager: resolves models (evidence: `commands/podcast_commands.py`)
- Model manager → Provider registry: uses provider setup
- Model manager → AI providers: calls models
- Notebooks and notes → Repository layer: loads and saves (evidence: `open_notebook/domain/notebook.py`)
- Repository layer → SurrealDB: queries records (evidence: `open_notebook/database/repository.py`)
