# Backend Handoff

This is a handoff snapshot, not the product SSOT.

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

## Current State

The backend is a runnable Phase 1 scaffold for the public read surface. It is not production-ready yet.

Implemented:

- FastAPI app and API prefix.
- SQLAlchemy models for the Phase 1 table set.
- Alembic initial migration.
- Seed import script.
- Public read API for feed, reports, module detail, institutions, and listen list.
- Tests for current seed behavior and public response boundaries.

Not implemented:

- Authentication.
- User personal-state routes.
- Audio stream signing.
- Outbound attribution route.
- Internal management routes.
- Production object storage integration.
- Real Redis cache invalidation.
- Production deployment config.

## Repository Map

| Path | Purpose |
|---|---|
| `app/main.py` | FastAPI app, CORS, router registration. |
| `app/config.py` | Environment-driven settings. |
| `app/db.py` | Async SQLAlchemy engine and session dependency. |
| `app/cache.py` | Redis client helper and key prefixing. |
| `app/models/entities.py` | SQLAlchemy table models. |
| `app/routers/` | HTTP route handlers. |
| `app/services/catalog.py` | Public catalog response assembly. |
| `migrations/` | Alembic environment and migration files. |
| `scripts/import_seed_content.py` | Seed data importer and module fixture builder. |
| `tests/test_public_api.py` | Current API and seed behavior tests. |
| `docs/` | Engineering handoff documentation. |

## Solved Decisions

- Technical identifiers stay `report-notebooklm` / `rnb`; display name is `研听`.
- Public API responses expose `cache_version`, not `display_version` or module `version`.
- `study_guide` replaces legacy `faq`.
- Heavy modules use preview cards plus full-module endpoint.
- Raw artifacts stay internal; App consumes reviewed display artifacts only.
- Gray broker sources may be audio-ized only after the latest product decision and compliance review.
- Phase 1 has no interpretation-content download feature.

## Known Gaps

- `GET /audio/{audio_id}/stream` needs signed playback URL behavior.
- Auth and personal state APIs need implementation.
- `POST /outbound/events` needs implementation and validation for `click_id` / `tracking_id`.
- Internal publish/hide/import management endpoints need implementation.
- Cursor pagination and cache invalidation are seed-scale placeholders.
- Object storage policy needs a production decision for public vs signed module content.
- Release/deploy settings need staging and production environment values.
- Compliance must re-review gray-source audio and generated media rules before launch.

## Suggested Handoff Order

1. Read `docs/PROJECT_BRIEF.md`.
2. Read `docs/API_AND_DATA.md`.
3. Run the backend locally with seed data using `docs/RUNBOOK.md`.
4. Run `pytest -q` and smoke the three core public endpoints.
5. Pair with `report-notebooklm-app/` and verify `RNB_API_BASE` points to this service.
6. Choose the next work item from `docs/ROADMAP_AND_OPEN_ISSUES.md`.

## Definition of Done for Next Backend Work

- New API behavior has tests.
- Public responses do not expose internal/raw fields.
- Migrations include downgrade.
- New config is environment-driven.
- Seed data remains useful for App development.
- Documentation is updated when contract behavior changes.