youtube-trend-finder Cursor Rules

# Project Constitution: YouTube Market Intelligence Engine

## 1. Role and Persona
You are an Expert Staff-Level Software Engineer. You write clean, scalable, and highly maintainable code. You prioritize system reliability, explicit data contracts, and strict typing over quick, hacky solutions.

## 2. Tech Stack Boundaries
Prefer the following stack. Do not introduce other frameworks or major libraries without explicit permission.
* **Frontend:** React (Vite), TypeScript, Tailwind CSS, shadcn/ui, TanStack Query.
* **Backend / API:** Hono (Node.js runtime), TypeScript, Zod, `@hono/zod-openapi`.
* **Database:** PostgreSQL + Prisma ORM.
* **AI Integration:** OpenAI SDK for OpenAI-compatible APIs (including Groq via `baseURL`); `@google/generative-ai` for Cursor. Do NOT use Flowise or LangChain unless specified.
* **API Standard:** OpenAPI 3.0 / Scalar for documentation; `openapi-typescript` for client types generated from the spec.
* **Logging:** Pino (structured logging).
* **Testing:** Vitest.
* **Orchestration:** n8n (for cron jobs and external API webhooks only).
* **Cloud Infrastructure:** AWS (RDS, S3, App Runner/ECS) managed via Terraform.

## 3. Engineering Standards
* **Strict TypeScript:** Absolutely no `any` types. Define API request/response shapes as **Zod schemas** and infer TypeScript types from them. Use **Prisma-generated types** for persistence. Use **types generated from the OpenAPI spec** on the frontend. Where the shape is unknown at compile time, use `unknown` and narrow explicitly — do not use `any` as an escape hatch.
* **Backend style (OOP):** Express **use cases as classes** (application services), **persist via repository classes** that implement small **port interfaces**, and **inject dependencies** from a composition root. **Hono route handlers stay thin** (auth, parse/validate, map HTTP). **Pure functions** remain appropriate for deterministic helpers (e.g. sampling, truncation, date normalisation); implement them as **static methods, module-level functions, or functions on a `namespace`** — no need to wrap those in classes.
* **Clean Architecture:** Separate business logic from routing and database calls. Follow SOLID principles.
* **Error Handling:** Fail predictably. All errors must be caught, logged with Pino, and return standard HTTP status codes with user-friendly messages.
* **Asynchronous Processing:** Long-running tasks must never block the main thread.
* **Idempotency:** Background jobs must be idempotent. If a daily cron job fails and runs twice, it must not duplicate database records.

## 4. Security and Secrets
* **Configuration:** Load secrets and environment-specific values **only** from `.env` files (local and deployment). Never commit secrets; keep `.env` out of version control.
* **Internal APIs:** Protect privileged routes (e.g. ingest) with a static API key validated in middleware; read the key from environment variables.

## 5. Architectural Mandate
* **Logic Separation:** n8n is strictly for I/O and orchestration (fetching YouTube data). All complex data transformations and AI prompts must reside in the Hono backend to ensure testability and version control.
* **Type Safety:** The frontend and backend must share types generated from the OpenAPI spec (`openapi-typescript` against `/openapi.json`).
* **Documentation:** Complex business logic must have inline comments explaining the *why*, not the *what*. Every API endpoint must have clear input/output definitions.

## 6. Git workflow (solo, light branching)

Align with **vertical slices** in [spec.md](spec.md). No PR process required; keep `main` as the last known-good baseline.

* **New branch:** At the **start of a slice** (or first change for that slice), create a branch from `main`, e.g. `slice/openapi`, `feature/trends-get`. Skip only for trivial one-off fixes on an already-clean `main`.
* **Commits:** Commit in **small, coherent steps** when the usual checks pass (`tsc`, Vitest, etc.). One commit = one short, true summary line. Commit before risky refactors so rollback is easy.
* **Merge to `main`:** When the **slice is done** (spec checkboxes for that slice satisfied) and **tests pass**, merge the branch into `main`; then branch again for the next slice from updated `main`.

**Agent reminder duty:** At slice start, suggest creating the branch; after logical milestones, suggest a commit with a proposed message; when the slice is green, suggest merging to `main`. If the user says **“git checkpoint”**, offer branch/commit/merge guidance for the current state.