lfnovo--open-notebook
wehub-resource-sync
128 行
5.2 KiB
Markdown
128 行
5.2 KiB
Markdown
# 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](contributing.md)** for the workflow, then check:
|
|
- **[Quick Start](quick-start.md)** - Clone, install, verify in 5 minutes
|
|
- **[Development Setup](development-setup.md)** - Complete local environment guide
|
|
- **[Code Standards](code-standards.md)** - How to write code that fits our style
|
|
- **[Testing](testing.md)** - How to write and run tests
|
|
|
|
**First time?** Check out our [Contributing Guide](contributing.md) for the issue-first workflow.
|
|
|
|
### 🔒 I Want to Understand Security Practices
|
|
|
|
**[Security Guidelines](security.md)** 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](architecture.md)** covers:
|
|
- 3-tier system design
|
|
- Tech stack and rationale
|
|
- Key components and workflows
|
|
- Design patterns we use
|
|
|
|
For deeper dives into specific subsystems:
|
|
- **[Credentials](credentials.md)** - Provider credential storage, encryption, provisioning
|
|
- **[Content Processing](content-processing.md)** - Chunking, embedding, context building, encryption
|
|
- **[Podcasts](podcasts.md)** - Profile system, model registry, job lifecycle
|
|
- **[Prompts](prompts.md)** - Prompt engineering patterns
|
|
- **[Frontend](frontend.md)** - 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](../../VISION.md)** - Product identity and current posture
|
|
- **[Decision Records](decisions/README.md)** - ADRs and PDRs: the durable "why" behind structural choices
|
|
|
|
---
|
|
|
|
### 👨🔧 I'm a Maintainer
|
|
|
|
**[Maintainer Guide](maintainer-guide.md)** covers:
|
|
- Issue triage and management
|
|
- Pull request review process
|
|
- Communication templates
|
|
- Best practices
|
|
|
|
---
|
|
|
|
## 📚 Quick Links
|
|
|
|
| Document | For | Purpose |
|
|
|---|---|---|
|
|
| [Quick Start](quick-start.md) | New developers | Clone, install, and verify setup (5 min) |
|
|
| [Development Setup](development-setup.md) | Local development | Complete environment setup guide |
|
|
| [Contributing](contributing.md) | Code contributors | Workflow: issue → code → PR |
|
|
| [Code Standards](code-standards.md) | Writing code | Style guides for Python, FastAPI, DB |
|
|
| [Testing](testing.md) | Testing code | How to write and run tests |
|
|
| [Architecture](architecture.md) | Understanding system | System design, tech stack, workflows |
|
|
| [Credentials](credentials.md) | Understanding system | Provider credential subsystem |
|
|
| [Content Processing](content-processing.md) | Understanding system | Chunking, embedding, context building |
|
|
| [Podcasts](podcasts.md) | Understanding system | Podcast profiles and job lifecycle |
|
|
| [Prompts](prompts.md) | Understanding system | Prompt engineering patterns |
|
|
| [Frontend](frontend.md) | Understanding system | Next.js architecture and data flows |
|
|
| [Design Principles](design-principles.md) | All developers | Engineering practices and anti-patterns |
|
|
| [VISION.md](../../VISION.md) | All developers | Product identity and current posture |
|
|
| [Decision Records](decisions/README.md) | All developers | ADRs/PDRs — why things are the way they are |
|
|
| [Change Playbooks](change-playbooks.md) | Contributors & agents | Step-by-step recipes for common changes |
|
|
| [API Reference](api-reference.md) | Building integrations | Complete REST API documentation |
|
|
| [Security](security.md) | All developers | Security practices and vulnerability prevention |
|
|
| [Maintainer Guide](maintainer-guide.md) | Maintainers | Managing issues, PRs, labels |
|
|
|
|
---
|
|
|
|
## 🚀 Current Development Priorities
|
|
|
|
We're actively looking for help with:
|
|
|
|
1. **Frontend Enhancement** - Improve Next.js/React UI with real-time updates
|
|
2. **Performance** - Async processing and caching optimizations
|
|
3. **Testing** - Expand test coverage across components
|
|
4. **Documentation** - API examples and developer guides
|
|
5. **Integrations** - New content sources and AI providers
|
|
|
|
See GitHub Issues labeled `good first issue` or `help wanted`.
|
|
|
|
---
|
|
|
|
## 💬 Getting Help
|
|
|
|
- **Discord**: [Join our server](https://discord.gg/37XJPXfz2w) 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
|
|
- [FastAPI Docs](https://fastapi.tiangolo.com/)
|
|
- [SurrealDB Docs](https://surrealdb.com/docs)
|
|
- [LangChain Docs](https://python.langchain.com/)
|
|
- [Next.js Docs](https://nextjs.org/docs)
|
|
|
|
### Our Libraries
|
|
- [Esperanto](https://github.com/lfnovo/esperanto) - Multi-provider AI abstraction
|
|
- [Content Core](https://github.com/lfnovo/content-core) - Content processing
|
|
- [Podcast Creator](https://github.com/lfnovo/podcast-creator) - Podcast generation
|
|
|
|
---
|
|
|
|
Ready to get started? Head over to **[Quick Start](quick-start.md)**! 🎉
|