Features

Per-feature implementation notes. Each doc follows the same section order so they're skimmable:

1. Purpose — the problem it solves
2. Contract — what clients / callers see (often a pointer to API.md)
3. Implementation — how it's built, with pseudocode for tricky parts
4. Required variables and services — env vars, injected dependencies
5. Gotchas — edge cases and failure modes worth knowing
6. Testing — how to verify it

Index

Cross-cutting plumbing

• response-envelope.md — { success, data } wrapper + error filter
• pagination.md — offset/limit DTO and service helper
• slugs.md — validator, reserved list, rename mechanics
• events.md — in-process event emitter and the event catalog

Auth and permissions

• tokens.md — JWT + refresh, rotation, reuse detection
• permissions.md — guards, decorators, role/permission model

Catalog and meta

• catalog.md — GET /catalog assembly, caching, invalidation

Content

• content-submit.md — submit flow, URL→platform inference, slug generation
• content-search.md — single list+search endpoint, filter composition
• content-approval.md — approval state machine, idempotency
• related-content.md — v1 scoring, extensibility
• thumbnails.md — async mip generation pipeline

Tags

• tag-rename.md — atomic cross-collection rename

Suggested reading order for new features

Building a new entity? Skim response-envelope.md, pagination.md, slugs.md first — every CRUD endpoint uses them.

Touching auth? tokens.md + permissions.md in that order.

Touching content? content-submit.md and content-search.md are self-contained; content-approval.md pulls in events.md and thumbnails.md.