How arpitteli/open-notebook works
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 Services · app App Shell · graphs Workflows · main.py API Entry
Components 19
Frontend
Next.js UI, client state, and browser-facing flows
- Browser · Entry point for notebook, search, chat, and podcast usage
- App Shell · App router pages, layouts, and dashboard surfaces
frontend/src/app - Client State · Navigation, modal, theme, auth, and query state
frontend/src/lib - API Client · Centralized frontend boundary to backend endpoints
frontend/src/lib/api
Backend API
FastAPI routes and orchestration services
- API Entry · Backend bootstrap and route assembly
api/main.py - Routers · Domain endpoints for notebooks, sources, chat, search, settings, models, podcasts, and auth
api/routers - Services · Notebook, source, chat, search, embedding, settings, model, and podcast operations
api - Notebook Chat · Notebook-wide conversational search and context assembly
api/chat_service.py - Source Chat · Source-scoped chat sessions and message flow
api/routers/source_chat.py
Core Engine
Shared domain, AI workflows, retrieval, and persistence
- Domain Model · Notebook, credential, transformation, content settings, and provider config objects
open_notebook/domain - Repository · Persistence gateway and data access layer
open_notebook/database/repository.py - Migrations · Database schema evolution and lifecycle migrations
open_notebook/database/migrations - AI Providers · Model discovery, key provisioning, and multi-provider integration
open_notebook/ai - Retrieval Utils · Chunking, embeddings, context assembly, token, and text helpers
open_notebook/utils - Workflows · Ask, chat, source chat, transformation, prompts, and tool flows
open_notebook/graphs - Prompts · Use-case prompt templates for ask, chat, source chat, and podcast generation
prompts - Podcasts · Episode profiles, speaker profiles, and podcast artifact generation
open_notebook/podcasts
Ops & Runtime
Commands, deployment, and automation
- Commands · Embedding, podcast, source, and example command handlers
commands - Runtime Ops · Docker, supervisor, startup scripts, and CI automation
Dockerfile
Connections 22
- 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