Backend Runbook

This is a handoff snapshot, not the product SSOT.

Product SSOT: mall-docs report-notebooklm docs, snapshot date: 2026-06-03.

Requirements

Python 3.12 or compatible with the configured project dependencies.
MySQL 8 for local/staging/prod-like runs.
Redis 7 for cache-compatible local/staging/prod-like runs.
A shell environment that can create a Python virtual environment.

SQLite is used by the automated tests through RNB_DATABASE_URL; production-like local runs should use MySQL.

Environment Variables

Create .env in the repository root:

RNB_DATABASE_URL=mysql+asyncmy://<db-user>:<db-pass>@<db-host>:<db-port>/report_notebooklm
RNB_REDIS_URL=redis://<redis-host>:<redis-port>/0
RNB_REDIS_KEY_PREFIX=rnb:

Do not commit .env.

Install

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Migrate and Seed

source .venv/bin/activate
alembic upgrade head
python scripts/import_seed_content.py

Seed import is destructive for seed tables. Use it only in local or disposable test data environments unless a production-safe importer is written.

Run API

source .venv/bin/activate
uvicorn app.main:app --reload --host <bind-host> --port <port>

API prefix:

/api/report-notebooklm/v1

Smoke Checks

API_BASE_URL=http://<api-host>:<port>/api/report-notebooklm/v1
curl "$API_BASE_URL/health"
curl "$API_BASE_URL/feed/recommended"
curl "$API_BASE_URL/reports/rep_ssga_gold"

Expected:

Health returns {"status":"ok"}.
Feed returns non-empty items.
Report detail returns modules and does not include display_version.

Test

source .venv/bin/activate
pytest -q

App Integration

Start this backend first, then run the App with:

flutter run -d chrome --dart-define=RNB_API_BASE=<api-base-url>

For Android emulator, use an API base URL reachable from that emulator:

flutter run -d <emulator-id> --dart-define=RNB_API_BASE=<emulator-api-base-url>

Only use cleartext HTTP for local debug builds. Release builds must use HTTPS.

Deployment Checks

Before staging or production:

Use environment variables for all database, Redis, object storage, auth, and signing settings.
Configure HTTPS at the gateway.
Confirm migrations can run forward and downgrade in staging.
Import reviewed content, not raw/unreviewed NotebookLM artifacts.
Smoke /health, /feed/recommended, report detail, audio stream, favorites, and outbound event once those APIs exist.
Confirm public responses do not expose local paths, raw payloads, notebook IDs, source IDs, conversation IDs, or secrets.

Operational Notes

Redis keys must use the rnb: prefix or a compatible namespace.
Object storage keys should use rnb/raw/, rnb/modules/, rnb/audio/, and rnb/images/ style prefixes.
Long NotebookLM operations should live in a resumable runner, not inside HTTP request handlers.

2.9 KiB Raw Blame History