What Is the Directory Structure of Open-Notebook? A Complete Guide to the Three-Tier Codebase

The open-notebook repository follows a modular three-tier architecture with frontend/ (Next.js/React), api/ (FastAPI), and open_notebook/ (core Python library) as top-level directories, organized to separate concerns between the UI layer, REST API, and domain logic.

Open Notebook is an open-source AI-powered notebook application maintained by lfnovo. Understanding the directory structure of open-notebook is essential for contributors navigating its frontend, REST API, and database layers, as the codebase intentionally separates concerns into distinct, testable packages.

High-Level Repository Layout

The root directory organizes the application into six primary groups. This structure supports the three-tier architecture (frontend → API → database) while keeping documentation and deployment configurations accessible.

open-notebook/
├── frontend/          # Next.js/React UI (TypeScript)

├── api/               # FastAPI REST layer (Python)

├── open_notebook/     # Core backend library (domain, graphs, AI, DB)

├── docs/              # User & developer documentation

├── examples/          # Docker-Compose starter files

├── tests/             # Pytest suite (backend) & Jest/Vitest (frontend)

├── .env.example       # Template for required env vars

├── Dockerfile         # Container images for API

├── docker-compose.yml # Multi-service Docker config

├── README.md          # Project summary & quick-start guide

└── CONFIGURATION.md   # All configurable options

Each top-level directory maintains its own CLAUDE.md file containing architecture-specific notes for that layer.

Frontend Directory: Next.js UI Layer

The frontend/ directory houses the TypeScript/React user interface built on Next.js. This tier handles all client-side rendering, state management, and API consumption.

Key Subdirectories

• src/ – React components, custom hooks, and utility functions. Contains src/components/layout/AppSidebar.tsx and shared UI elements.
• app/ – Next.js route definitions using the App Router pattern. Entry points include app/page.tsx (landing) and app/layout.tsx (root layout).
• public/ – Static assets including icons and images such as public/logo.svg.
• tests/ – Vitest/Jest test suites validating component behavior, with examples like AppSidebar.test.tsx.

Configuration Files

The frontend tier includes package.json for NPM dependencies, next.config.ts for framework settings, and tailwind.config.ts for styling. The frontend/README.md provides setup instructions specific to the UI layer.

API Directory: FastAPI REST Layer

The api/ directory implements the RESTful middleware that bridges the frontend and core library. Built with FastAPI, this layer handles HTTP routing, authentication, and request validation.

Structural Components

• routers/ – Individual FastAPI routers for each domain object. Key files include routers/sources.py for content ingestion and routers/models.py for AI provider configuration.
• *_service.py files – Business-logic layer separating API concerns from domain operations. Examples include sources_service.py and models_service.py.
• main.py – FastAPI application bootstrap located at api/main.py, responsible for CORS configuration and router mounting.
• auth.py – Simple password-based authentication for development environments.
• client.py – Helper utilities for internal HTTP calls and health checks.

The api/CLAUDE.md file documents architectural decisions specific to the REST layer.

Core Library: Domain Logic and AI Workflows

The open_notebook/ package contains the domain-driven backend logic, including Pydantic models, LangGraph workflows, and database abstractions.

Module Breakdown

• domain/ – Pydantic models and business logic for entities like notebooks, sources, and credentials. Key files include domain/notebook.py and domain/credential.py.
• graphs/ – LangGraph workflow definitions orchestrating AI interactions. Contains graphs/chat.py for conversational flows and graphs/ask.py for query processing.
• ai/ – Multi-provider AI abstraction supporting 18+ LLM providers. Central files include ai/models.py for model selection and ai/provision.py for provider instantiation.
• utils/ – Helper utilities for text processing, encryption, and embeddings. Examples include utils/chunking.py and utils/encryption.py.
• database/ – SurrealDB repository pattern and async migrations. The database/repository.py file provides the async abstraction for all database operations, while database/async_migrate.py handles schema updates.
• config.py – Global configuration management loading environment variables across the core library.

Supporting Directories

Documentation (docs/)

Markdown-based documentation covering installation, configuration guides, and API references. The docs/5-CONFIGURATION/ai-providers.md file explains LLM provider wiring.

Examples (examples/)

Ready-to-run Docker Compose configurations for different deployment scenarios:

• docker-compose-dev.yml – Development stack with SurrealDB, API, and UI
• docker-compose-ollama.yml – Local LLM deployment via Ollama
• docker-compose-full-local.yml – Fully self-contained deployment

Tests (tests/)

Backend tests written in Pytest exercising API endpoints and graph logic, alongside frontend component tests. Representative files include test_models_api.py and ConfirmDialog.test.tsx.

Root Configuration Files

The repository root contains essential configuration and metadata:

• .env.example – Template for required environment variables without secrets
• Dockerfile and Dockerfile.single – Multi-stage container builds for the API service
• pyproject.toml – Poetry packaging configuration and Python dependencies
• Makefile – Convenience targets for testing, linting, and development workflows
• CONFIGURATION.md – Comprehensive reference for all environment variables and defaults
• CHANGELOG.md – Release notes and version history

Practical Code Examples

Importing Core Domain Objects

To interact with the database layer from the core library:

from open_notebook.domain.notebook import Notebook
from open_notebook.database.repository import Repository

async def get_notebook(notebook_id: str) -> Notebook:
    repo = Repository()
    return await repo.notebook.get(notebook_id)

Calling the REST API

Accessing the sources endpoint directly:

curl -X GET "http://localhost:5055/sources/12345" \
  -H "accept: application/json"

The router definition resides in api/routers/sources.py.

Using Frontend Components

Importing UI components in the Next.js application:

import { ModelSelector } from '@/components/source/ModelSelector';

export default function SettingsPage() {
  return (
    <section>
      <h2>AI Model Settings</h2>
      <ModelSelector />
    </section>
  );
}

The component source is located at frontend/src/components/source/ModelSelector.tsx.

Summary

The directory structure of open-notebook reflects its three-tier architecture through clear separation of concerns:

• frontend/ contains the Next.js/React UI tier with TypeScript components and Vitest tests
• api/ houses the FastAPI REST layer with routers in routers/ and business logic in *_service.py files
• open_notebook/ provides the core Python library with domain models, LangGraph workflows in graphs/, and SurrealDB abstractions in database/
• docs/ and examples/ offer documentation and deployment configurations
• Root configuration files like CONFIGURATION.md and .env.example govern environment setup

This modular layout enables independent testing of each tier and simplifies navigation for contributors working on specific layers.

Frequently Asked Questions

What is the purpose of the open_notebook/ directory?

The open_notebook/ directory serves as the core Python library containing domain logic, AI workflows, and database abstractions. It houses Pydantic models in domain/, LangGraph definitions in graphs/, and the SurrealDB repository pattern in database/, functioning as the backend brain that the FastAPI layer consumes.

Where are the frontend components located in open-notebook?

Frontend components reside in frontend/src/components/, with route definitions in frontend/app/ following the Next.js App Router convention. Static assets live in frontend/public/, while configuration files like next.config.ts and tailwind.config.ts sit in the frontend/ root.

How is the API layer structured in the open-notebook repository?

The API layer in api/ follows FastAPI conventions with domain-specific routers in routers/ (such as sources.py and models.py), service modules handling business logic, and main.py bootstrapping the application with CORS and middleware configurations. The *_service.py pattern separates HTTP handling from domain operations.

What database does open-notebook use and where is it configured?

Open Notebook uses SurrealDB as its primary database, with async repository patterns defined in open_notebook/database/repository.py. Schema migrations are handled by database/async_migrate.py, while connection settings are typically configured via environment variables referenced in open_notebook/config.py and the root .env.example file.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}