# Purpose of the src Directory in lfnovo/open-notebook: Repository Structure Explained

> Discover the lfnovo/open-notebook repository structure. Learn where its production code resides, organized under top-level packages like open_notebook/, api/, and frontend/.

- Repository: [Luis Novo/open-notebook](https://github.com/lfnovo/open-notebook)
- Tags: internals
- Published: 2026-06-26

---

**The `lfnovo/open-notebook` repository does not contain a `src` directory; instead, production code is organized under dedicated top-level packages such as `open_notebook/`, `api/`, and `frontend/`.**

The Open Notebook project is an open-source application for AI-powered note-taking and knowledge management. Unlike traditional Python projects that use a generic `src` folder, this repository exposes its architecture through clearly-named top-level directories that make the codebase immediately navigable and align with modern Python packaging best practices.

## Repository Layout Without a src Folder

The codebase follows a **modular package structure** where each logical component lives in its own directory at the repository root. This design eliminates the need for a `src` directory while maintaining strict separation of concerns:

- **`open_notebook/`** – Core backend library containing domain models, database helpers, AI provisioning, utilities, and LangGraph workflows
- **`api/`** – FastAPI entry point and HTTP routers exposing notebook, source, chat, and other services
- **`frontend/`** – Next.js/React front-end handling UI, state management, and API client code
- **`commands/`** – CLI-style command definitions used by the background job system
- **`tests/`** – Pytest suites covering backend, API, and utility code

## Core Packages and Their Roles

### The open_notebook Package

Located at the repository root, the `open_notebook/` directory serves as the primary Python package. It contains the core business logic, including SurrealDB integration and text processing utilities found in [`open_notebook/utils/text_utils.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/utils/text_utils.py).

```python
from open_notebook.utils.text_utils import clean_text

sample = "  Open Notebook   "
print(clean_text(sample))

# → "Open Notebook"

```

*Source file:* [[`open_notebook/utils/text_utils.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/utils/text_utils.py)](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/utils/text_utils.py)

### The api Package

The `api/` directory houses the FastAPI application. The file [`api/main.py`](https://github.com/lfnovo/open-notebook/blob/main/api/main.py) serves as the entry point that wires all routers and starts the ASGI server.

*Source file:* [[`api/main.py`](https://github.com/lfnovo/open-notebook/blob/main/api/main.py)](https://github.com/lfnovo/open-notebook/blob/main/api/main.py)

### The frontend Package

This directory contains the Next.js/React application, providing the user interface and client-side state management.

## Key Source Files and Their Locations

Because the repository uses a flat, modular structure rather than a nested `src` layout, critical files are accessible via predictable paths:

**Package initialization** – Makes `open_notebook` importable as a Python package:  
[[`open_notebook/__init__.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/__init__.py)](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/__init__.py)

**Configuration handling** – Central settings for the application:  
[[`open_notebook/config.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/config.py)](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/config.py)

**Database repository** – Async CRUD helpers for SurrealDB:  
[[`open_notebook/database/repository.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/database/repository.py)](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/database/repository.py)

## Why This Repository Omits a src Directory

The absence of a `src` folder is intentional. By placing packages like `open_notebook/` and `api/` at the repository root, the project achieves **direct importability** without complex path manipulation. This aligns with Python best practices where each package is importable directly (e.g., `import open_notebook.utils.text_utils`), simplifying development and testing workflows.

## Summary

- The `lfnovo/open-notebook` repository contains **no `src` directory**.
- Code is organized into **top-level packages** (`open_notebook/`, `api/`, `frontend/`, `commands/`, `tests/`).
- The `open_notebook/` package contains core backend logic, database helpers, and AI workflows.
- The `api/` package contains the FastAPI entry point at [`api/main.py`](https://github.com/lfnovo/open-notebook/blob/main/api/main.py).
- The modular layout allows direct imports and clear architectural boundaries.

## Frequently Asked Questions

### Does lfnovo/open-notebook use a src layout?

No. The repository uses a **modular layout** where production code lives in top-level directories like `open_notebook/` and `api/` rather than under a generic `src` folder. This makes the codebase easier to navigate and eliminates the need for path manipulation during development.

### Where is the main application code located in open-notebook?

The main application code is split across three primary locations: the **`open_notebook/`** package (core backend logic and database), the **`api/`** directory (FastAPI HTTP server), and the **`frontend/`** directory (Next.js/React UI). The FastAPI entry point specifically resides in [`api/main.py`](https://github.com/lfnovo/open-notebook/blob/main/api/main.py).

### How do I import modules from the open_notebook package?

Since the package exists at the repository root, you can import modules directly using the package name. For example: `from open_notebook.utils.text_utils import clean_text` or `from open_notebook.database.repository import repository`. This works because [`open_notebook/__init__.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/__init__.py) makes the directory a proper Python package.

### Why doesn't this repository follow the src-layout convention?

The project maintains a **flat package structure** to keep imports simple and the architecture transparent. When packages are top-level, developers can run and import code without installing the package in editable mode or manipulating `PYTHONPATH`, which streamlines the development workflow for this SurrealDB-backed AI application.