4.3 KiB
Claude Guide
Guidance for working with this codebase as an AI assistant. Read this first, then follow the task routing table to find the specific docs for your task.
Task Routing
Find your task type below and read only the listed docs. Do not read the entire vault for every task.
| Task | Read first |
|---|---|
| Bug in description rendering or tokens | 01-Architecture/07 - Render Engine + 05-Development/04 - Gotchas |
| New backend module or service | 05-Development/03 - Recipes + 04-Design-Guidelines/04 - Backend Architecture Patterns |
| New API endpoint + frontend wiring | 05-Development/03 - Recipes + 03-API-Reference/<relevant endpoint> |
| Frontend UI component or page | 04-Design-Guidelines/02 - CSS Conventions + 03 - Component Patterns |
| Frontend styling or visual change | 04-Design-Guidelines/01 - Visual Design + 02 - CSS Conventions |
| Database schema change | 01-Architecture/04 - Database Schema + 05-Development/03 - Recipes (Prisma recipe) |
| New lint rule | 05-Development/03 - Recipes + 02-Features/03 - Metadata Linting |
| Queue / background job issue | 01-Architecture/05 - Queue System + 05-Development/04 - Gotchas |
| Auth or permissions issue | 01-Architecture/06 - Authentication + 04-Design-Guidelines/04 - Backend Architecture Patterns |
| Unfamiliar with the codebase | 01-Architecture/01 - System Overview → 02 - Backend → 03 - Frontend |
After making changes, always verify using 05-Development/06 - Verifying Changes.
Do Not Do These
These are failure modes that come up repeatedly when working with LLMs in this codebase.
Do not create new utility or helper files. If something needs a helper, add it to the relevant service or component. Check 05-Development/03 - Recipes for the established pattern before creating anything new.
Do not add comments that describe what the code does. Only comment when the why is non-obvious — a hidden constraint, a workaround for a specific bug, a subtle invariant. See 04-Design-Guidelines/05 - Code Conventions for the full rule.
Do not introduce abstractions for things that appear in two or three places. This codebase favors repetition over premature abstraction. Add an abstraction only when a pattern appears three or more times with meaningful variation and the abstraction is simpler than the repetition.
Do not use SiYoutube from react-icons/si. It does not exist in v5. Use FaYoutube from react-icons/fa instead. All other platform icons are in react-icons/si.
Do not add error handling for scenarios that cannot happen. Trust Prisma's type guarantees and internal service calls. Only validate and handle errors at system boundaries: user input, external API calls, and queue job payloads.
Do not register a new module only in AppModule if it is also needed by queue processors. Always check whether the new module's services are used in any processor, and if so, register it in WorkerModule as well. Missing WorkerModule registration causes silent runtime errors in background jobs.
Do not remove or rename Prisma enum values. PostgreSQL enum removal requires a raw SQL migration and risks data loss. Mark deprecated values as hidden in the UI instead.
Do not call useQueryClient() inside a callback or effect. It must be called at the component top level and assigned to a local variable before use in onSuccess or event handlers.
Do not duplicate data-fetching logic for the render engine. VideoRenderService is the single source of truth for fetching all data needed for a render. Never replicate its data-fetching in a processor or service — always go through VideoRenderService.
Key Invariants
These are easy to miss and cause subtle bugs.
- Every database query must be scoped to
req.user.teamId. Never query across teams. - Every user-facing mutation (create/update/delete) must call
AuditService.log(). Background/system operations do not. - New
{video.*}or{collab.*}render tokens must be registered insystem-variables.registry.tsor they will silently resolve to nothing. Campaign.statusmust be exactly the lowercase string"active"for the campaign to be treated as active. Any other casing is inactive.- The
TOKEN_ENCRYPTION_KEYenv var must never change in production. Rotating it invalidates all stored YouTube OAuth tokens.