mirror of https://github.com/lfnovo/open-notebook.git synced 2026-10-15 15:19:45 +00:00

docs: development docs match the codebase; add-a-provider playbook (#1458 )

* docs: development docs match the codebase; add-a-provider playbook

- architecture.md: rewritten as a ~110-line map verified against the code
  (processes, layout, data model from the migrations, graphs, model calls,
  background jobs); links the accurate topic pages
- testing.md, api-reference.md, code-standards.md: rewritten from the real
  suite, the /api prefix and Bearer auth, and the actual error-handling
  pattern (no longer contradicts AGENTS.md)
- change-playbooks.md: new "Add an AI provider" playbook (registry + the four
  hand-maintained copies + tests + docs, checked against #1443/#1444); fixes
  async nodes, command registration, polling paths, locale steps
  (LanguageToggle, satisfies TranslationShape), colocated frontend tests
- development-setup.md is the single setup page (deps, .env with localhost
  SURREAL_URL, DB -> API -> worker -> frontend, real log lines, /health);
  quick-start.md and README.dev.md point to it
- contributing.md: Conventional Commits, CHANGELOG rule, pre-PR checks that
  match CI; PR template gains ruff format and frontend checks
- AGENTS files agree with the docs (provider edits, routers vs services,
  async nodes, checkpoint path, ADR-013, stop_on); api/AGENTS.md is a plain
  link instead of a Claude-only @ import
- ADR index explains ADR-010 (reserved for #1332) and number-at-merge;
  GitHub-compatible encryption anchor; small credentials/security fixes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: address review (CI commands, async source creation, paths, ADR-010, language toggle)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

2026-10-04 23:06:36 -03:00

3.9 KiB

Raw Permalink Blame History

Open Notebook — Agent Rules

Open Notebook is an open-source, privacy-focused alternative to Google's Notebook LM: an AI-powered research assistant with multi-provider AI support, fully self-hostable.

This file holds the project-wide rules every coding session needs. Component rules: open_notebook/AGENTS.md (backend — also covers api/, commands/, prompts/) and frontend/AGENTS.md. Knowledge lives in the docs (see Where to look) — read it on demand instead of guessing.

Stack, ports, startup order

Three tiers: Next.js frontend (3000) → FastAPI (5055) → SurrealDB (8000).

Start in this order — each tier depends on the one below:

make database — SurrealDB (API fails without it)
make api — FastAPI; schema migrations run automatically on startup (check logs)
make worker-start — surreal-commands worker. Required: podcasts, embeddings and source processing are async jobs that silently queue forever without it
make frontend — UI (depends on the API for all data)

Or all at once: make start-all (status: make status, stop: make stop-all). First-time setup (uv sync, npm install, a .env with SURREAL_URL=ws://localhost:8000/rpc): development-setup.md.

Commands

Tests: uv run pytest tests/
Python lint/format/typecheck: uv run ruff check . --fix · uv run ruff format . · uv run python -m mypy .
Frontend (inside frontend/): npm run lint · npm run test · npm run build
CI runs uv run ruff check ., uv run ruff format --check ., mypy, pytest and, in frontend/, npm run lint, npm run test:coverage and npm run build; all must pass
Docker release: make docker-release (see .github/RELEASE_PROCESS.md)

Hard rules

Async-first: every DB query, graph invocation and AI call is await-ed. No sync DB access.
Never commit secrets. Credentials are encrypted at rest and require OPEN_NOTEBOOK_ENCRYPTION_KEY to be set.
CORS is wide-open and auth is a simple password middleware — dev defaults, not production hardening. Don't build features that assume otherwise.
Product direction questions (does this feature fit?) → VISION.md. Past decisions ("why is it like this?") → docs/7-DEVELOPMENT/decisions/. Structural decisions made while coding should produce a new decision record there.
Conventional Commits for commits and PR titles (fix(podcasts): …, feat(providers): …, docs: …).
Every user-visible change adds a CHANGELOG entry under ## [Unreleased], in the one section for its type (### Added / ### Changed / ### Deprecated / ### Removed / ### Fixed / ### Security); never create a duplicate section. Details: contributing.md.
Maintainer profile lives in .maintainer/; do not run release, triage or discussions workflows without it.

Where to look

Need	Location
Architecture (processes, layout, data model, workflows)	docs/7-DEVELOPMENT/architecture.md
Step-by-step recipes (add endpoint, provider, migration, command, i18n…)	docs/7-DEVELOPMENT/change-playbooks.md
Dev environment setup	docs/7-DEVELOPMENT/development-setup.md
Code standards & testing	docs/7-DEVELOPMENT/code-standards.md · testing.md
Product identity & current posture	VISION.md
Decision log (ADRs/PDRs)	docs/7-DEVELOPMENT/decisions/
Contribution process (Discussions → Issues → PRs)	docs/7-DEVELOPMENT/contributing.md
User/operator docs (install, configure, troubleshoot)	docs/