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

> Explore the Open-Notebook directory structure. Understand the three-tier codebase including frontend Nextjs API FastAPI and the core Python library for clear separation of concerns.

- Repository: [Luis Novo/open-notebook](https://github.com/lfnovo/open-notebook)
- Tags: how-to-guide
- Published: 2026-06-13

---

**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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/app/page.tsx) (landing) and [`app/layout.tsx`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/AppSidebar.test.tsx).

### Configuration Files

The frontend tier includes [`package.json`](https://github.com/lfnovo/open-notebook/blob/main/package.json) for NPM dependencies, [`next.config.ts`](https://github.com/lfnovo/open-notebook/blob/main/next.config.ts) for framework settings, and [`tailwind.config.ts`](https://github.com/lfnovo/open-notebook/blob/main/tailwind.config.ts) for styling. The [`frontend/README.md`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/routers/sources.py) for content ingestion and [`routers/models.py`](https://github.com/lfnovo/open-notebook/blob/main/routers/models.py) for AI provider configuration.
- **`*_service.py` files** – Business-logic layer separating API concerns from domain operations. Examples include [`sources_service.py`](https://github.com/lfnovo/open-notebook/blob/main/sources_service.py) and [`models_service.py`](https://github.com/lfnovo/open-notebook/blob/main/models_service.py).
- **[`main.py`](https://github.com/lfnovo/open-notebook/blob/main/main.py)** – FastAPI application bootstrap located at [`api/main.py`](https://github.com/lfnovo/open-notebook/blob/main/api/main.py), responsible for CORS configuration and router mounting.
- **[`auth.py`](https://github.com/lfnovo/open-notebook/blob/main/auth.py)** – Simple password-based authentication for development environments.
- **[`client.py`](https://github.com/lfnovo/open-notebook/blob/main/client.py)** – Helper utilities for internal HTTP calls and health checks.

The [`api/CLAUDE.md`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/domain/notebook.py) and [`domain/credential.py`](https://github.com/lfnovo/open-notebook/blob/main/domain/credential.py).
- **`graphs/`** – LangGraph workflow definitions orchestrating AI interactions. Contains [`graphs/chat.py`](https://github.com/lfnovo/open-notebook/blob/main/graphs/chat.py) for conversational flows and [`graphs/ask.py`](https://github.com/lfnovo/open-notebook/blob/main/graphs/ask.py) for query processing.
- **`ai/`** – Multi-provider AI abstraction supporting 18+ LLM providers. Central files include [`ai/models.py`](https://github.com/lfnovo/open-notebook/blob/main/ai/models.py) for model selection and [`ai/provision.py`](https://github.com/lfnovo/open-notebook/blob/main/ai/provision.py) for provider instantiation.
- **`utils/`** – Helper utilities for text processing, encryption, and embeddings. Examples include [`utils/chunking.py`](https://github.com/lfnovo/open-notebook/blob/main/utils/chunking.py) and [`utils/encryption.py`](https://github.com/lfnovo/open-notebook/blob/main/utils/encryption.py).
- **`database/`** – SurrealDB repository pattern and async migrations. The [`database/repository.py`](https://github.com/lfnovo/open-notebook/blob/main/database/repository.py) file provides the async abstraction for all database operations, while [`database/async_migrate.py`](https://github.com/lfnovo/open-notebook/blob/main/database/async_migrate.py) handles schema updates.
- **[`config.py`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/docker-compose-dev.yml) – Development stack with SurrealDB, API, and UI
- [`docker-compose-ollama.yml`](https://github.com/lfnovo/open-notebook/blob/main/docker-compose-ollama.yml) – Local LLM deployment via Ollama
- [`docker-compose-full-local.yml`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/test_models_api.py) and [`ConfirmDialog.test.tsx`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/pyproject.toml)** – Poetry packaging configuration and Python dependencies
- **`Makefile`** – Convenience targets for testing, linting, and development workflows
- **[`CONFIGURATION.md`](https://github.com/lfnovo/open-notebook/blob/main/CONFIGURATION.md)** – Comprehensive reference for all environment variables and defaults
- **[`CHANGELOG.md`](https://github.com/lfnovo/open-notebook/blob/main/CHANGELOG.md)** – Release notes and version history

## Practical Code Examples

### Importing Core Domain Objects

To interact with the database layer from the core library:

```python
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:

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

```

The router definition resides in [`api/routers/sources.py`](https://github.com/lfnovo/open-notebook/blob/main/api/routers/sources.py).

### Using Frontend Components

Importing UI components in the Next.js application:

```tsx
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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/next.config.ts) and [`tailwind.config.ts`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/sources.py) and [`models.py`](https://github.com/lfnovo/open-notebook/blob/main/models.py)), service modules handling business logic, and [`main.py`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/database/repository.py). Schema migrations are handled by [`database/async_migrate.py`](https://github.com/lfnovo/open-notebook/blob/main/database/async_migrate.py), while connection settings are typically configured via environment variables referenced in [`open_notebook/config.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/config.py) and the root `.env.example` file.