# arpitteli/open-notebook architecture

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

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

## Overview

1. **Overall shape**
   - This repo is a two-tier application: a **Python/FastAPI backend** plus a **Next.js/React frontend**.
   - It is designed as a self-hosted “Notebook LM” alternative where users ingest content, manage notebooks, chat/search over that content, and generate podcasts.

2. **Frontend boundary**
   - The `frontend/` app is the user-facing shell: dashboard, notebook views, source views, search, settings, podcasts, and auth.
   - It is built with **Next.js App Router**, React, and a component-heavy UI layer. Client state is split across hooks/stores, with query/cache management and modal/navigation/theme stores.
   - Frontend API calls are centralized under `frontend/src/lib/api/`, which forms the main boundary to the backend.

3. **Backend boundary**
   - The `api/` package is the HTTP service layer. `api/main.py` is the FastAPI entrypoint, and `api/routers/` contains the route surface area.
   - Routers are organized by domain: notebooks, sources, notes, chat, search, embeddings, settings, models, credentials, podcasts, insights, transformations, and auth.
   - The backend mostly acts as orchestration: validate requests, call service modules, and return API-friendly models.

4. **Core domain and service layer**
   - The real business logic is in `open_notebook/` and `api/*_service.py`.
   - `open_notebook/domain/` contains the domain objects for notebooks, credentials, transformations, content settings, and provider config.
   - `api/*.py` service modules wrap higher-level operations like notebook management, chat, context assembly, search, embeddings, source handling, model discovery, settings, and podcast generation.

5. **AI and retrieval pipeline**
   - The central flow is: **ingest content → chunk/process → embed/index → search/chat with context**.
   - `open_notebook/utils/chunking.py`, `embedding.py`, `context_builder.py`, and `token_utils.py` support this pipeline.
   - Search and chat use retrieval-augmented generation concepts: content is indexed, relevant chunks are selected, then prompts are assembled for the model.

6. **Graph/prompt orchestration**
   - `open_notebook/graphs/` contains the AI workflow layer: ask, chat, source chat, transformation, prompt handling, and tool integration.
   - Prompt templates live in `prompts/` and are separated by use case (`ask`, `chat`, `source_chat`, `podcast`).
   - This is the main abstraction boundary for LLM behavior: the app’s prompts and tool flows are not embedded in the UI or routers.

7. **Data storage and persistence**
   - The project uses **SurrealDB** as the primary database, configured externally in deployment examples and referenced by migration/repository code under `open_notebook/database/`.
   - Database schema is managed by SurrealQL migrations, and repository access is concentrated in `open_notebook/database/repository.py`.
   - The data model appears centered on notebooks, sources, notes, models, credentials, transformations, chat sessions/messages, and podcast artifacts.

8. **AI provider abstraction**
   - Provider integration is abstracted through `open_notebook/ai/` and the model-related API/services.
   - The README and code tree show support for many providers and capabilities: LLMs, embeddings, speech-to-text, and text-to-speech.
   - There is a provider discovery/configuration flow rather than hard-coding one vendor, which is important for the architecture diagram: provider choice is a first-class subsystem.

9. **Podcasts as a separate product path**
   - Podcast generation is its own subsystem, not just a chat export.
   - `api/podcast_service.py`, `api/episode_profiles_service.py`, `api/insights_service.py`, and `open_notebook/podcasts/` indicate a pipeline for turning source material into structured podcast episodes.
   - Frontend pages and panels for episode profiles and speaker profiles reinforce that podcast creation has its own UI, data model, and generation workflow.

10. **Source-centric chat and notebook-centric chat**
   - There are two related but distinct interaction patterns: **notebook-level chat/search** and **source-level chat**.
   - The frontend has dedicated source chat sessions and notebook chat columns, while backend routers include both generic chat and source-chat endpoints.
   - This suggests separate context scopes: one bound to a notebook’s collection of sources/notes, another bound to an individual source and its sessions.

11. **Authentication, settings, and operational controls**
   - Authentication is optional but supported through `api/auth.py` and frontend auth pages/components.
   - Settings and credentials are managed as first-class resources, which matters because model keys, encryption, and provider config are user-managed data.
   - Advanced admin-like operations include embedding rebuild, system info, model sync/testing, and migration banners, indicating the app expects ongoing operational maintenance from the UI.

12. **Deployment and runtime topology**
   - The repo supports multiple runtime modes: local development, Docker Compose, single-container deployment, and external-provider setups.
   - The default architecture is a web frontend talking to a backend API, with SurrealDB as an external service and optional local/remote AI services.
   - `run_api.py`, `Dockerfile`, `Dockerfile.single`, `supervisord*.conf`, and the example compose files show that backend and frontend can be packaged together or run separately depending on deployment style.

13. **Automation, commands, and integration points**
   - `commands/` provides structured command handlers for embedding, podcast, source, and example command flows.
   - `scripts/` and GitHub Actions are used for docs export, startup coordination, build/test/release automation, and release hygiene.
   - This indicates the repository is not only an application but also a packaged platform with CLI-like internal command flows and deployment automation.

14. **What to draw in an architecture diagram**
   - A good diagram should show: **browser/UI → Next.js frontend → FastAPI backend → SurrealDB + AI providers**.
   - Inside the backend, separate the **HTTP routers**, **service layer**, **domain/model layer**, **retrieval/graph orchestration**, and **database repository/migrations**.
   - Then show side workflows for **podcast generation**, **embedding rebuild/search**, and **source/chat session management**, because these are distinct business subsystems rather than just generic CRUD.

Main entry points: [`api`](https://github.com/arpitteli/open-notebook/tree/main/api) (Services), [`frontend/src/app`](https://github.com/arpitteli/open-notebook/tree/main/frontend/src/app) (App Shell), [`open_notebook/graphs`](https://github.com/arpitteli/open-notebook/tree/main/open_notebook/graphs) (Workflows), [`api/main.py`](https://github.com/arpitteli/open-notebook/blob/main/api/main.py) (API Entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Frontend"]
  node_browser(("Browser<br/>user client"))
  node_frontend_shell["App Shell<br/>Next.js app"]
  node_frontend_state["Client State<br/>hooks/stores"]
  node_frontend_api["API Client<br/>fetch layer"]
end

subgraph group_api["Backend API"]
  node_api_entry["API Entry<br/>FastAPI app<br/>[main.py]"]
  node_api_routers["Routers<br/>HTTP surface"]
  node_api_services["Services<br/>orchestration layer"]
  node_notebook_chat["Notebook Chat<br/>retrieval workflow<br/>[chat_service.py]"]
  node_source_chat["Source Chat<br/>session workflow<br/>[source_chat.py]"]
end

subgraph group_core["Core Engine"]
  node_domain_models["Domain Model<br/>entities"]
  node_repo_layer[("Repository<br/>SurrealDB access<br/>[repository.py]")]
  node_migrations["Migrations<br/>SurrealQL schema"]
  node_ai_providers{{"AI Providers<br/>provider abstraction"}}
  node_retrieval_utils["Retrieval Utils<br/>RAG pipeline"]
  node_graph_workflows["Workflows<br/>LLM graphs"]
  node_prompt_templates["Prompts<br/>jinja templates"]
  node_podcast_pipeline["Podcasts<br/>generation pipeline"]
end

subgraph group_ops["Ops & Runtime"]
  node_commands["Commands"]
  node_runtime["Runtime Ops<br/>deployment"]
end

node_browser -->|"use"| node_frontend_shell
node_frontend_shell -->|"state"| node_frontend_state
node_frontend_shell -->|"calls"| node_frontend_api
node_frontend_api -->|"requests"| node_api_entry
node_api_entry -->|"mounts"| node_api_routers
node_api_routers -->|"delegates"| node_api_services
node_api_services -->|"uses"| node_domain_models
node_api_services -->|"persists"| node_repo_layer
node_repo_layer -.->|"schema"| node_migrations
node_api_services -->|"invokes"| node_ai_providers
node_api_services -->|"builds"| node_retrieval_utils
node_retrieval_utils -->|"feeds"| node_graph_workflows
node_graph_workflows -->|"renders"| node_prompt_templates
node_graph_workflows -->|"runs on"| node_ai_providers
node_api_services -->|"orchestrates"| node_podcast_pipeline
node_podcast_pipeline -->|"uses"| node_prompt_templates
node_api_services -->|"supports"| node_source_chat
node_api_services -->|"supports"| node_notebook_chat
node_commands -.->|"automation"| node_retrieval_utils
node_commands -.->|"automation"| node_podcast_pipeline
node_runtime -.->|"starts"| node_api_entry
node_runtime -.->|"serves"| node_frontend_shell

click node_frontend_shell "https://github.com/arpitteli/open-notebook/tree/main/frontend/src/app"
click node_frontend_state "https://github.com/arpitteli/open-notebook/tree/main/frontend/src/lib"
click node_frontend_api "https://github.com/arpitteli/open-notebook/tree/main/frontend/src/lib/api"
click node_api_entry "https://github.com/arpitteli/open-notebook/blob/main/api/main.py"
click node_api_routers "https://github.com/arpitteli/open-notebook/tree/main/api/routers"
click node_api_services "https://github.com/arpitteli/open-notebook/tree/main/api"
click node_notebook_chat "https://github.com/arpitteli/open-notebook/blob/main/api/chat_service.py"
click node_source_chat "https://github.com/arpitteli/open-notebook/blob/main/api/routers/source_chat.py"
click node_domain_models "https://github.com/arpitteli/open-notebook/tree/main/open_notebook/domain"
click node_repo_layer "https://github.com/arpitteli/open-notebook/blob/main/open_notebook/database/repository.py"
click node_migrations "https://github.com/arpitteli/open-notebook/tree/main/open_notebook/database/migrations"
click node_ai_providers "https://github.com/arpitteli/open-notebook/tree/main/open_notebook/ai"
click node_retrieval_utils "https://github.com/arpitteli/open-notebook/tree/main/open_notebook/utils"
click node_graph_workflows "https://github.com/arpitteli/open-notebook/tree/main/open_notebook/graphs"
click node_prompt_templates "https://github.com/arpitteli/open-notebook/tree/main/prompts"
click node_podcast_pipeline "https://github.com/arpitteli/open-notebook/tree/main/open_notebook/podcasts"
click node_commands "https://github.com/arpitteli/open-notebook/tree/main/commands"
click node_runtime "https://github.com/arpitteli/open-notebook/tree/main/Dockerfile"

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_browser,node_frontend_shell,node_frontend_state,node_frontend_api toneBlue
class node_api_entry,node_api_routers,node_api_services,node_notebook_chat,node_source_chat toneAmber
class node_domain_models,node_repo_layer,node_migrations,node_ai_providers,node_retrieval_utils,node_graph_workflows,node_prompt_templates,node_podcast_pipeline toneMint
class node_commands,node_runtime toneRose
```

## Components

### Frontend

Next.js UI, client state, and browser-facing flows

- **Browser**: user client · Entry point for notebook, search, chat, and podcast usage
- [App Shell](https://github.com/arpitteli/open-notebook/tree/main/frontend/src/app): Next.js app · App router pages, layouts, and dashboard surfaces · `frontend/src/app`
- [Client State](https://github.com/arpitteli/open-notebook/tree/main/frontend/src/lib): hooks/stores · Navigation, modal, theme, auth, and query state · `frontend/src/lib`
- [API Client](https://github.com/arpitteli/open-notebook/tree/main/frontend/src/lib/api): fetch layer · Centralized frontend boundary to backend endpoints · `frontend/src/lib/api`

### Backend API

FastAPI routes and orchestration services

- [API Entry](https://github.com/arpitteli/open-notebook/blob/main/api/main.py): FastAPI app · Backend bootstrap and route assembly · `api/main.py`
- [Routers](https://github.com/arpitteli/open-notebook/tree/main/api/routers): HTTP surface · Domain endpoints for notebooks, sources, chat, search, settings, models, podcasts, and auth · `api/routers`
- [Services](https://github.com/arpitteli/open-notebook/tree/main/api): orchestration layer · Notebook, source, chat, search, embedding, settings, model, and podcast operations · `api`
- [Notebook Chat](https://github.com/arpitteli/open-notebook/blob/main/api/chat_service.py): retrieval workflow · Notebook-wide conversational search and context assembly · `api/chat_service.py`
- [Source Chat](https://github.com/arpitteli/open-notebook/blob/main/api/routers/source_chat.py): session workflow · Source-scoped chat sessions and message flow · `api/routers/source_chat.py`

### Core Engine

Shared domain, AI workflows, retrieval, and persistence

- [Domain Model](https://github.com/arpitteli/open-notebook/tree/main/open_notebook/domain): entities · Notebook, credential, transformation, content settings, and provider config objects · `open_notebook/domain`
- [Repository](https://github.com/arpitteli/open-notebook/blob/main/open_notebook/database/repository.py): SurrealDB access · Persistence gateway and data access layer · `open_notebook/database/repository.py`
- [Migrations](https://github.com/arpitteli/open-notebook/tree/main/open_notebook/database/migrations): SurrealQL schema · Database schema evolution and lifecycle migrations · `open_notebook/database/migrations`
- [AI Providers](https://github.com/arpitteli/open-notebook/tree/main/open_notebook/ai): provider abstraction · Model discovery, key provisioning, and multi-provider integration · `open_notebook/ai`
- [Retrieval Utils](https://github.com/arpitteli/open-notebook/tree/main/open_notebook/utils): RAG pipeline · Chunking, embeddings, context assembly, token, and text helpers · `open_notebook/utils`
- [Workflows](https://github.com/arpitteli/open-notebook/tree/main/open_notebook/graphs): LLM graphs · Ask, chat, source chat, transformation, prompts, and tool flows · `open_notebook/graphs`
- [Prompts](https://github.com/arpitteli/open-notebook/tree/main/prompts): jinja templates · Use-case prompt templates for ask, chat, source chat, and podcast generation · `prompts`
- [Podcasts](https://github.com/arpitteli/open-notebook/tree/main/open_notebook/podcasts): generation pipeline · Episode profiles, speaker profiles, and podcast artifact generation · `open_notebook/podcasts`

### Ops & Runtime

Commands, deployment, and automation

- [Commands](https://github.com/arpitteli/open-notebook/tree/main/commands): structured commands · Embedding, podcast, source, and example command handlers · `commands`
- [Runtime Ops](https://github.com/arpitteli/open-notebook/tree/main/Dockerfile): deployment · Docker, supervisor, startup scripts, and CI automation · `Dockerfile`

## Connections

- Browser → App Shell: use · Users interact with the Next.js application
- App Shell → Client State: state · Pages and components coordinate through client stores and hooks
- App Shell → API Client: calls · UI actions are routed through the API client boundary
- API Client → API Entry: requests · Frontend issues API requests to the FastAPI backend
- API Entry → Routers: mounts · Entrypoint registers the domain router surface
- Routers → Services: delegates · Routers validate and hand off to service modules
- Services → Domain Model: uses · Service logic is built around shared domain objects
- Services → Repository: persists · Services read and write application state through the repository
- Repository → Migrations: schema · Repository structure is governed by SurrealQL migrations
- Services → AI Providers: invokes · Model, embedding, speech, and provider discovery flows use AI abstractions
- Services → Retrieval Utils: builds · Chunking, embeddings, and context assembly support retrieval workflows
- Retrieval Utils → Workflows: feeds · Prepared context and embeddings drive graph-based LLM flows
- Workflows → Prompts: renders · Workflow nodes assemble use-case-specific prompt templates
- Workflows → AI Providers: runs on · LLM execution depends on provider-backed model access
- Services → Podcasts: orchestrates · Podcast generation is a dedicated service path
- Podcasts → Prompts: uses · Podcast outlines and transcripts use dedicated prompts
- Services → Source Chat: supports · Source-scoped chat is handled as a separate service workflow
- Services → Notebook Chat: supports · Notebook-wide chat and search are handled as another workflow
- Commands → Retrieval Utils: automation · Command handlers reuse core processing and embedding utilities
- Commands → Podcasts: automation · Command handlers can trigger podcast-related flows
- Runtime Ops → API Entry: starts · Deployment scripts and containers launch the backend service
- Runtime Ops → App Shell: serves · Runtime packaging may serve or co-locate the frontend app
