Welcome to the Open Notebook development documentation! Whether you're contributing code, understanding our architecture, or maintaining the project, you'll find guidance here.
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 Discussions → Issues → PRs workflow.
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
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/.
- VISION.md - Product identity and current posture
- Decision Records - ADRs and PDRs: the durable "why" behind structural choices
Maintainer Guide covers:
- Issue triage and management
- Pull request review process
- Communication templates
- Best practices
| Document | For | Purpose |
|---|---|---|
| Quick Start | New developers | Clone, install, and verify setup (5 min) |
| Development Setup | Local development | Complete environment setup guide |
| Contributing | Community & code contributors | Workflow: Discussion → Issue → 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 |
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.
- Discord: Join our server for real-time discussions
- GitHub Discussions: For questions, ideas, features, product direction, design, and architecture
- GitHub Issues: For reproducible bugs and approved work items
Don't be shy! We're here to help new contributors succeed.
- Esperanto - Multi-provider AI abstraction
- Content Core - Content processing
- Podcast Creator - Podcast generation
Ready to get started? Head over to Quick Start! 🎉