Open Notebook Architecture

System Overview

Open Notebook is built as a modern Python web application with a clear separation between frontend and backend, using Docker for deployment.

┌─────────────────────────────────────────────────────┐
│                   Docker Compose                    │
│                                                     │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────┐  │
│  │   Next.js    │  │   FastAPI    │  │ SurrealDB │  │
│  │   Frontend   │──│   Backend    │──│           │  │
│  │  (port 8502) │  │  (port 5055) │  │ (port 8K) │  │
│  └──────────────┘  └──────────────┘  └───────────┘  │
│                          │                          │
│                    ┌─────┴─────┐                    │
│                    │ LangChain │                    │
│                    │ Esperanto │                    │
│                    └─────┬─────┘                    │
│                          │                          │
│              ┌───────────┼───────────┐              │
│              │           │           │              │
│          ┌───┴───┐   ┌───┴───┐   ┌───┴───┐          │
│          │OpenAI │   │Claude │   │Ollama │  ...     │
│          └───────┘   └───────┘   └───────┘          │
└─────────────────────────────────────────────────────┘

Core Components

FastAPI Backend

The REST API is built with FastAPI and organized into routers:

20 route modules covering notebooks, sources, notes, chat, search, podcasts, transformations, models, credentials, embeddings, settings, and more
Async/await throughout for non-blocking I/O
Pydantic models for request/response validation
Custom exception handlers mapping domain errors to HTTP status codes
CORS middleware for cross-origin access
Optional password authentication middleware

SurrealDB

SurrealDB serves as the primary data store, providing both document and relational capabilities:

Document storage for notebooks, sources, notes, transformations, and models
Relational references for notebook-source associations
Full-text search across indexed content
RocksDB backend for persistent storage on disk
Schema migrations run automatically on application startup

LangChain Integration

AI features are powered by LangChain with the Esperanto multi-provider library:

LangGraph manages conversational state for chat sessions
Embedding models power vector search across content
LLM chains drive transformations, note generation, and podcast scripting
Prompt templates stored in the prompts/ directory

Esperanto Multi-Provider Library

Esperanto provides a unified interface to 16+ AI providers:

Abstracts provider-specific API differences
Supports LLM, embedding, speech-to-text, and text-to-speech capabilities
Handles credential management and model discovery
Enables runtime provider switching without code changes

Next.js Frontend

The user interface is a React application built with Next.js:

Responsive design for desktop and tablet use
Real-time updates for chat and processing status
File upload with progress tracking
Audio player for podcast episodes

Data Flow

Source Ingestion

Upload/URL → Source Record Created → Processing Queue
                                         │
                              ┌──────────┼──────────┐
                              ▼          ▼          ▼
                          Text       Embedding   Metadata
                        Extraction   Generation  Extraction
                              │          │          │
                              └──────────┼──────────┘
                                         ▼
                                  Source Updated
                                  (searchable)

Chat Execution

User Message → Build Context (sources + notes)
                    │
                    ▼
              LangGraph State Machine
                    │
                    ├─ Retrieve relevant context
                    ├─ Format prompt with citations
                    └─ Stream LLM response
                         │
                         ▼
                   Response with
                   source citations

Podcast Generation

Notebook Content → Episode Profile → Script Generation (LLM)
                                          │
                                          ▼
                                    Speaker Assignment
                                          │
                                          ▼
                                    Text-to-Speech
                                    (per segment)
                                          │
                                          ▼
                                    Audio Assembly
                                          │
                                          ▼
                                    Episode Record
                                    + Audio File

Key Design Decisions

Multi-provider by default: Not locked to any single AI provider, enabling cost optimization and capability matching
Async processing: Long-running operations (source ingestion, podcast generation) run asynchronously with status polling
Self-hosted data: All data stays on the user's infrastructure with encrypted credential storage
REST-first API: Every UI action is backed by an API endpoint for automation
Docker-native: Designed for containerized deployment with persistent volumes

File Structure

open-notebook/
├── api/               # FastAPI REST API
│   ├── main.py        # App setup, middleware, routers
│   ├── routers/       # Route handlers (20 modules)
│   ├── models.py      # Pydantic request/response models
│   └── auth.py        # Authentication middleware
├── open_notebook/     # Core library
│   ├── ai/            # AI integration (LangChain, Esperanto)
│   ├── database/      # SurrealDB operations
│   ├── domain/        # Domain models and business logic
│   ├── graphs/        # LangGraph chat and processing graphs
│   ├── podcasts/      # Podcast generation pipeline
│   └── utils/         # Shared utilities
├── frontend/          # Next.js React application
├── prompts/           # AI prompt templates
├── tests/             # Test suite
└── docker-compose.yml # Deployment configuration