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

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.

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)

The api Package

The api/ directory houses the FastAPI application. The file 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)

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)

Configuration handling – Central settings for the application:
[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)

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.
• 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.

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 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.

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