Initial commit: YouTube Studio Flow (backend, frontend, infrastructure, docs)

2026-08-11 12:27:44 +02:00
commit d5af006443
304 changed files with 74604 additions and 0 deletions
@@ -0,0 +1,60 @@
+# 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 in `system-variables.registry.ts` or they will silently resolve to nothing.
+- `Campaign.status` must be exactly the lowercase string `"active"` for the campaign to be treated as active. Any other casing is inactive.
+- The `TOKEN_ENCRYPTION_KEY` env var must never change in production. Rotating it invalidates all stored YouTube OAuth tokens.