Development

Welcome to the Open Notebook development documentation! Whether you're contributing code, understanding our architecture, or maintaining the project, you'll find guidance here.

🎯 Pick Your Path

👨‍💻 I Want to Contribute Code

Start with Contributing Guide for the workflow, then check:

Quick Start - Clone, install, verify in 5 minutes
Development Setup - Complete local environment guide
Code Standards - How to write code that fits our style
Testing - How to write and run tests

First time? Check out our Contributing Guide for the issue-first workflow.

🔒 I Want to Understand Security Practices

Security Guidelines covers:

Database query safety (preventing SurrealQL injection)
Template rendering safety (preventing SSTI)
File handling safety (preventing path traversal and LFI)
Secrets management and CORS configuration
Code review security checklist

🏗️ I Want to Understand the Architecture

Architecture Overview covers:

3-tier system design
Tech stack and rationale
Key components and workflows
Design patterns we use

For deeper dives into specific subsystems:

Credentials - Provider credential storage, encryption, provisioning
Content Processing - Chunking, embedding, context building, encryption
Podcasts - Profile system, model registry, job lifecycle
Prompts - Prompt engineering patterns
Frontend - Next.js layers and data flows

Normative rules for coding agents (and humans in a hurry) live in the AGENTS.md files at the repo root, open_notebook/, and frontend/.

🧭 Why Is It Like This?

VISION.md - Product identity and current posture
Decision Records - ADRs and PDRs: the durable "why" behind structural choices

👨‍🔧 I'm a Maintainer

Maintainer Guide covers:

Issue triage and management
Pull request review process
Communication templates
Best practices

📚 Quick Links

Document	For	Purpose
Quick Start	New developers	Clone, install, and verify setup (5 min)
Development Setup	Local development	Complete environment setup guide
Contributing	Code contributors	Workflow: issue → code → PR
Code Standards	Writing code	Style guides for Python, FastAPI, DB
Testing	Testing code	How to write and run tests
Architecture	Understanding system	System design, tech stack, workflows
Credentials	Understanding system	Provider credential subsystem
Content Processing	Understanding system	Chunking, embedding, context building
Podcasts	Understanding system	Podcast profiles and job lifecycle
Prompts	Understanding system	Prompt engineering patterns
Frontend	Understanding system	Next.js architecture and data flows
Design Principles	All developers	Engineering practices and anti-patterns
VISION.md	All developers	Product identity and current posture
Decision Records	All developers	ADRs/PDRs — why things are the way they are
Change Playbooks	Contributors & agents	Step-by-step recipes for common changes
API Reference	Building integrations	Complete REST API documentation
Security	All developers	Security practices and vulnerability prevention
Maintainer Guide	Maintainers	Managing issues, PRs, labels

🚀 Current Development Priorities

We're actively looking for help with:

Frontend Enhancement - Improve Next.js/React UI with real-time updates
Performance - Async processing and caching optimizations
Testing - Expand test coverage across components
Documentation - API examples and developer guides
Integrations - New content sources and AI providers

See GitHub Issues labeled good first issue or help wanted.

💬 Getting Help

Discord: Join our server for real-time discussions
GitHub Discussions: For architecture questions
GitHub Issues: For bugs and features

Don't be shy! We're here to help new contributors succeed.

📖 Additional Resources

External Documentation

Our Libraries

Esperanto - Multi-provider AI abstraction
Content Core - Content processing
Podcast Creator - Podcast generation

Ready to get started? Head over to Quick Start! 🎉