# 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:

```bash
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

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

## Migrate and Seed

```bash
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

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

API prefix:

```text
/api/report-notebooklm/v1
```

## Smoke Checks

```bash
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

```bash
source .venv/bin/activate
pytest -q
```

## App Integration

Start this backend first, then run the App with:

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

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

```bash
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.