create-tigra 3.0.3 → 3.1.0

package/template/_claude/rules/client/08-lockfile-cross-platform.md

@@ -1,79 +0,0 @@
-> **SCOPE**: These rules apply specifically to the **client** directory (Next.js App Router).
-
-# Lockfile — Cross-Platform Regeneration
-
-`client/package-lock.json` has burned us — and bots — multiple times in projects scaffolded from this template. Read this before touching it.
-
-## The trap
-
-`client/package-lock.json` is consumed by **three different environments**:
-
-| Environment | OS / libc | npm |
-|---|---|---|
-| Local dev (most contributors) | Windows / macOS | npm 11.x |
-| GitHub Actions CI (`server-ci.yml`, `client-ci.yml`) | `ubuntu-latest` (Debian glibc) | npm 10.x (ships with Node 20) |
-| Coolify / production deploy (`client/Dockerfile`) | `node:20-alpine` (musl) | npm 10.x |
-
-`npm ci` is **strict** — it refuses to install if the lockfile is even slightly out of sync with `package.json`, AND it only installs the platform-specific `optionalDependencies` whose top-level `node_modules/<pkg>` entries exist in the lockfile. If you regenerate on Windows with `npm install`, you get a Windows-leaning lockfile that:
-
-1. May be missing entries the newer npm 10 (CI) considers required (`Missing: @swc/helpers@0.5.21 from lock file` — common failure mode).
-2. Lacks `*-linux-x64-gnu` / `*-linuxmusl-x64` entries → CI's `next build` fails with `Cannot find module '../lightningcss.linux-x64-gnu.node'` or `No prebuild or local build of @parcel/watcher found.`
-
-Affected native packages (Next 16 + Tailwind v4 dep tree): `@parcel/watcher`, `lightningcss`, `@img/sharp`, `@next/swc`, `@swc/core`, `@tailwindcss/oxide`, `@unrs/resolver-binding`, `@rolldown/binding`.
-
-## Canonical fix (use this exactly)
-
-Whenever you regenerate `client/package-lock.json` — even just because `package.json` changed by one dep — run **all three** steps. They are additive (`--package-lock-only` doesn't touch `node_modules`).
-
-```bash
-cd client
-
-# 0. (Optional) Start fresh if the existing lockfile is already broken:
-rm -rf node_modules package-lock.json
-
-# 1. Sync the lockfile against package.json (fixes the "Missing: foo from lock file" class).
-npx -y npm@10 install --package-lock-only
-
-# 2. Add Linux/glibc native variants (GitHub Actions Ubuntu).
-npx -y npm@10 install --os=linux --cpu=x64 --libc=glibc --package-lock-only
-
-# 3. Add Linux/musl native variants (Coolify Alpine deploy).
-npx -y npm@10 install --os=linux --cpu=x64 --libc=musl --package-lock-only
-```
-
-### Required choices
-
-- **`npx -y npm@10` explicitly.** Local default npm 11.x resolves a tree npm 10 strict-checks reject. Match CI's npm version or you'll push a lockfile that fails immediately.
-- **`--package-lock-only`** keeps each command at ~1 sec (no install, no audit).
-- **Three platforms.** Even if you only intend to fix CI, do the musl pass too — Coolify deploy will fail otherwise.
-- **Skip darwin** unless a team member dev's on macOS and reports `npm ci` failing. Not worth the lockfile churn pre-emptively.
-
-## Verify before committing
-
-```bash
-cd client
-
-# A. Strict install passes with CI's npm version (this is the exact check CI runs):
-npx -y npm@10 ci --include=optional --no-audit --no-fund 2>&1 | tail -3
-# Expect: "added N packages in Xs". Any "EUSAGE" / "Missing:" means step 1 didn't take.
-
-# B. All native deps have glibc + musl entries:
-for pkg in '@next/swc' '@swc/core' '@parcel/watcher' '@rolldown/binding' \
-           '@tailwindcss/oxide' '@unrs/resolver-binding' 'lightningcss'; do
-  g=$(grep -cE "node_modules/${pkg}.*-linux-x64-(gnu|glibc)\"" package-lock.json)
-  m=$(grep -cE "node_modules/${pkg}-linux-x64-musl\"" package-lock.json)
-  echo "$pkg glibc=$g musl=$m"
-done
-# Expect every line: glibc=1 musl=1. (sharp uses different naming — check separately:
-# grep -oE 'node_modules/@img/sharp[-a-z0-9]*' package-lock.json | sort -u)
-```
-
-If either check fails, the lockfile is not ready — do not commit.
-
-## Anti-patterns (don't do these — every one has burned us)
-
-1. **Plain `npm install` on Windows/macOS.** Uses local npm 11; produces lockfiles CI rejects.
-2. **Whack-a-mole pinning** in `package.json` `optionalDependencies` (e.g., adding only `@parcel/watcher-linux-x64-glibc` and hoping it fixes everything). It doesn't — there are 7+ such native deps and you'll bounce through them one CI failure at a time.
-3. **Disabling `npm ci` in CI** by switching to `npm install` to "fix" the symptom. That makes builds non-reproducible.
-4. **Bypassing the husky pre-commit hook** with `--no-verify` to push a broken lockfile fast.
-5. **Generating inside Docker on a hung Docker daemon** without verifying the daemon is healthy first — the run silently buffers and you wait 10+ minutes. (The non-Docker `npx npm@10 install --package-lock-only` chain above is faster and equally correct.)

package/template/_claude/rules/client/core.md

@@ -1,46 +0,0 @@
-> **SCOPE**: These rules apply specifically to the **client** directory (Next.js App Router).
-
-# Client Rules — Core Index
-
-**Read only the file relevant to your current task.**
-
-| You are doing... | Read this |
-|---|---|
-| Creating files, folders, feature modules | `01-project-structure.md` |
-| Building components, writing types/interfaces | `02-components-and-types.md` |
-| Fetching data, managing state, calling APIs, forms | `03-data-and-state.md` |
-| Choosing colors, styling, typography, spacing, motion, **theme colors**, **font presets** | `04-design-system.md` |
-| Auth tokens, env vars, security headers | `05-security.md` |
-| UX psychology, cognitive load, a11y, performance | `06-ux-checklist.md` |
-| Regenerating `client/package-lock.json`, fixing CI `npm ci` failures, cross-platform native binaries (`@parcel/watcher`, `lightningcss`, `@img/sharp`, etc.) | `08-lockfile-cross-platform.md` |
-
----
-
-## Architecture
-
-```
-Page (Server Component — fetches data)
-  → Feature Components (Server or Client)
-    → UI (shadcn/ui + Tailwind)
-
-State: Server data (SSR) → Server Components
-       Server data (client) → React Query
-       Global client state → Redux (auth only)
-       Local state → useState / useReducer
-       URL state → useSearchParams
-```
-
----
-
-## Non-negotiable rules
-
-1. **Mobile-first**: All Tailwind classes start at mobile. Desktop is the enhancement (`md:`, `lg:`). Touch targets min 44x44px. No functionality behind hover-only states.
-2. **Server Components by default.** Only add `'use client'` when you need hooks, state, or event handlers.
-3. **Component limits**: Max 250 lines, max 5 props, max 3 JSX nesting levels.
-4. **No hardcoded colors**: Use Tailwind semantic tokens (`bg-primary`, `text-foreground`). Never hardcode hex/rgb in components. **All color variables live in `src/styles/themes/default.css` using HEX values, NOT in `globals.css` or components.** Only edit the HEX values in `default.css` to customize the palette — never rename variables, change the file structure, or move color definitions elsewhere. The smooth transition system in `globals.css` and the variable naming are locked. Read `04-design-system.md` → "Theme System" for details.
-5. **No hardcoded fonts**: Use Tailwind font classes (`font-sans`, `font-heading`, `font-mono`). Never hardcode `font-family` in components. **Font families are defined in font preset files (`src/styles/fonts/*.css`).** To change fonts, update the `next/font/google` imports in `layout.tsx` and the font preset file. Read `04-design-system.md` → "Font Preset System" for details.
-6. **No inline styles**: Tailwind only. Use `cn()` for conditional classes.
-7. **Import order**: React/Next → third-party → UI → local → hooks → services → types → utils.
-8. **Forms**: Validate with Zod. Always validate client-side AND server-side.
-9. **Security**: Never inject raw HTML without sanitization. Never prefix secrets with `NEXT_PUBLIC_`.
-10. **Deployment**: Never remove `output: "standalone"` from `next.config.ts`. When adding `NEXT_PUBLIC_*` env vars, also add them as `ARG` + `ENV` in the Dockerfile builder stage. Read `07-deployment.md` for details.

package/template/_claude/rules/global/completion-reports.md

@@ -1,178 +0,0 @@
-> **SCOPE**: These rules apply to the **entire workspace** (server + client). Always active.
-
-# Task Completion Reports
-
-When you finish a task, phase, or multi-step implementation, you MUST provide a structured completion report. Freeform paragraphs like "Fixed issues and completed remaining tasks" are not acceptable. The report must give the user a clear, scannable picture of everything that changed, why, and what to do next.
-
----
-
-## When to Report
-
-| Situation | Report required? |
-|-----------|-----------------|
-| Completed a full task or feature | **Yes — Full Report** |
-| Completed a phase in a multi-phase plan | **Yes — Phase Report** (subset of Full Report) |
-| Fixed a bug | **Yes — Bug Fix Report** |
-| Small config change, typo fix, single-file edit | **No** — a 1-2 sentence explanation is fine |
-
----
-
-## Full Report Template
-
-Use this structure after completing a feature or multi-phase task. Omit sections that don't apply (e.g., skip "Database Changes" if no migrations were created), but never omit "Files Changed" or "How to Test".
-
-```
-## Summary
-[1-3 sentences: what was built/changed and why]
-
-## Files Changed
-
-### Created
-- `path/to/file.ts` — [purpose: what this file does]
-
-### Modified
-- `path/to/file.ts` — [what changed and why]
-
-### Deleted
-- `path/to/file.ts` — [why it was removed]
-
-## New API Endpoints (if applicable)
-| Method | Path | Auth | Description |
-|--------|------|------|-------------|
-
-## Database Changes (if applicable)
-- Migration: `YYYYMMDD_name` — [what it does]
-- New tables: [list]
-- Modified tables: [what changed]
-- Indexes added: [list]
-
-## Environment Variables (if applicable)
-| Variable | Required | Where | Description |
-|----------|----------|-------|-------------|
-[Where = .env / .env.example / Dockerfile ARG / Coolify]
-
-## Dependencies Added (if applicable)
-| Package | Purpose |
-|---------|---------|
-- Note if any require system-level installs (apk add)
-
-## Key Decisions & Trade-offs
-[Explain non-obvious choices. Why was approach A chosen over B? What assumptions were made? What are the limitations?]
-
-## Deployment & Production Impact (if applicable)
-[This section is REQUIRED whenever changes affect deployment, infrastructure, or production behavior. Include ALL that apply:]
-
-### Dockerfile Changes
-- [New ARG/ENV added, new COPY lines, new apk packages, port changes, etc.]
-
-### Environment / Coolify Configuration
-- [New env vars that must be set in Coolify/hosting platform]
-- [Build arguments that must be added]
-- [Volume mounts needed]
-
-### Database Migration Required
-- [Migration name and what it does]
-- [Must run `prisma migrate deploy` before/after deploying]
-- [Any data migration or backfill needed]
-
-### Infrastructure Changes
-- [New external services required (Redis, S3, third-party APIs)]
-- [DNS/domain changes needed]
-- [SSL/certificate changes]
-- [New cron jobs or background workers]
-
-### Deployment Order
-- [If server and client must be deployed in a specific order, state it]
-- [If a migration must run before the new code deploys, state it]
-
-### Rollback Plan
-- [What happens if this deployment fails — is it safe to roll back?]
-- [Are the database changes backwards-compatible with the previous code version?]
-
-## Breaking Changes (if any)
-- [What breaks, what to update, and how]
-
-## Manual Steps Required
-1. [Ordered list of things the user must do before this works]
-   - e.g., "Add GEMINI_API_KEY to .env"
-   - e.g., "Run npm run prisma:migrate dev"
-
-## How to Test
-1. [Step-by-step verification the user can follow]
-   - Be specific: exact commands, exact Postman steps, exact URLs
-   - Include expected responses where helpful
-
-## Known Limitations / TODOs (if any)
-- [Things not yet implemented, edge cases not handled, future improvements needed]
-```
-
----
-
-## Phase Report Template
-
-Use this when completing one phase of a multi-phase plan. Shorter than a Full Report but still structured.
-
-```
-## Phase N Complete: [Phase Title]
-
-### What was done
-- [Bullet list of concrete changes]
-
-### Files Changed
-- `path/to/file.ts` — [what and why]
-
-### Key Decisions
-- [Any non-obvious choices made during this phase]
-
-### Blockers or Concerns
-- [Anything that might affect subsequent phases]
-
-### Phase Status
-- [x] Phase N complete
-- [ ] Phase N+1: [title] — next
-```
-
----
-
-## Bug Fix Report Template
-
-```
-## Bug Fix: [Short description]
-
-### Root Cause
-[What was actually wrong — not just the symptom, but the underlying cause]
-
-### Fix Applied
-- `path/to/file.ts` — [what changed]
-
-### Why This Fix
-[Why this approach was chosen. What other approaches were considered and rejected.]
-
-### How to Verify
-1. [Steps to confirm the fix works]
-
-### Regression Risk
-- [Could this fix break anything else? What was checked?]
-```
-
----
-
-## Rules
-
-1. **Structure over prose.** Use the templates above. Tables, bullet points, and headers — not paragraphs.
-2. **Every file gets a "why".** Don't just list `file.ts` — explain what changed and why. "Added creditBalance: 0 to mocks" → "Added `creditBalance: 0` to user mocks in `setup.ts` because the new credits module added this required field to the User model, and existing test fixtures would fail validation without it."
-3. **Be specific in "How to Test".** Not "use Postman to test." Instead: "1. POST `{{baseUrl}}/auth/login` with test credentials. 2. POST `{{baseUrl}}/generations` with body `{ templateId: '...', image: <file> }`. 3. Expected: 201 with `{ success: true, data: { id, status: 'pending' } }`."
-4. **Explain decisions, not just actions.** "Used upsert for seed data" → "Used `upsert` instead of `create` for seed data so the seed script is idempotent — running it twice won't throw duplicate key errors."
-5. **Surface what the user needs to do.** If the user must add an env var, run a migration, install something, or restart a service — put it in "Manual Steps Required" prominently. Don't bury it in a paragraph.
-6. **Honest about limitations.** If something is incomplete, has edge cases, or needs future work — say so in "Known Limitations." Don't pretend everything is perfect.
-7. **Scale to the task.** A 5-phase feature gets a full report with every section. A single service method gets a shorter report. Use judgment, but always use the structured format.
-8. **Deployment impact is never optional.** If ANY of the following changed, the "Deployment & Production Impact" section is REQUIRED — no exceptions:
-   - New or modified environment variables
-   - New npm packages with native dependencies
-   - Database schema changes (new tables, columns, indexes)
-   - Dockerfile modifications needed
-   - New external service dependencies (APIs, Redis, S3, etc.)
-   - Port, entry point, or health check changes
-   - File upload/storage changes requiring volume mounts
-   - Changes to build process or build arguments
-   If none of these apply, explicitly state: "No deployment impact — no infrastructure, env, or database changes."

package/template/_claude/rules/global/core.md

@@ -1,104 +0,0 @@
-> **SCOPE**: These rules apply to the **entire workspace** (server + client). Always active.
-
-# Global Rules
-
-These rules are always in effect regardless of which directory you are working in.
-
----
-
-## New Project Setup
-
-When the user asks to create, scaffold, or start a new server or client project, **always run `/create-server` or `/create-client` first** before writing any code. These commands contain the full scaffolding templates, dependency lists, and boilerplate that match our architecture. Do not attempt to scaffold a project from memory.
-
----
-
-## Safe Editing
-
-1. **Small, focused changes**: Only modify what's necessary. Don't restructure code unless asked.
-2. **Preserve signatures**: Don't change existing function signatures, exports, or imports unless explicitly requested.
-3. **Extend, don't rewrite**: Add to existing modules. Don't gut and rebuild.
-4. **Protect critical flows**: Never break existing auth, core business flows, or payment logic.
-5. **No half-done work**: If something is incomplete, add a `// TODO:` with explanation.
-6. **No noisy logs**: No debug logs in production code. Mark temporary ones with `// TODO: remove debug log`.
-7. **Call out breaking changes**: If a breaking change is unavoidable, state it clearly in your explanation.
-8. **Assume production**: Treat this as a real production project. Avoid destructive or experimental changes.
-
----
-
-## TypeScript
-
-- **Strict mode ON** in both client and server. No exceptions.
-- **No `any`** — use `unknown` if the type is truly unknown.
-- **Explicit return types** on all functions.
-- **Always `import type`** for type-only imports.
-- **Validate all inputs with Zod** — client-side for UX, server-side for security.
-
----
-
-## Git & Branching
-
-- **Branch naming**: `feature/<name>`, `fix/<name>`, `chore/<name>`, `hotfix/<name>`.
-- **Commit messages**: Use conventional commits — `feat:`, `fix:`, `chore:`, `refactor:`, `docs:`, `test:`.
-  - Keep the subject line under 72 characters.
-  - Use imperative mood: "Add search filter" not "Added search filter".
-- **Never commit**: `.env` files, secrets, `node_modules`, build artifacts, OS files (`.DS_Store`, `Thumbs.db`).
-- **One logical change per commit**. Don't mix unrelated changes.
-
----
-
-## Environment & Configuration
-
-- **`.env` files are never committed.** Use `.env.example` as the template with placeholder values.
-- **Adding a new env var**: Add it to `.env.example` with a comment, and document where it's used.
-- **Keep `.env` and `.env.example` in sync**: Any change to `.env` (adding, removing, or renaming a variable) must be reflected in `.env.example`, and vice versa. They must always have the same set of variables.
-- **Keep `.env.example.production` in sync**: Every time `.env` or `.env.example` changes (variable added, removed, or renamed), also update `.env.example.production` in the same directory. If the file does not exist, create it. This file uses the same variable names but with **production-appropriate placeholder values** and comments (e.g., secure passwords, real domain URLs, SSL-enabled connection strings, stricter timeouts). See the server's `.env.example.production` for the expected style. This applies to both `server/` and `client/` directories.
-- **Secrets** (DB URLs, JWT secrets, API keys) must never be prefixed with `NEXT_PUBLIC_` and must never appear in client-side code.
-- **Public values only** (API base URL, app name) get the `NEXT_PUBLIC_` prefix.
-
----
-
-## Testing
-
-- **New features and bug fixes should include tests** unless the change is trivial (copy, config, styling).
-- **Test naming**: `describe('<ModuleName>')` → `it('should <expected behavior>')`.
-- **Tests must be deterministic**: No reliance on real time, network, or random values. Mock external dependencies.
-- **Don't test implementation details** — test behavior and outputs.
-- **No "mock-echo" tests**: Don't mock a dependency (Prisma/ORM, HTTP client) and then only assert it was called with the same arguments the code passes straight through — that restates the implementation and verifies no behavior. A "was-called-with" assertion is valid only when the layer *transformed* the input first (filtering, pagination math, conditional queries) or when you ALSO assert on the returned value / observable result.
-- **Don't test logic-free layers**: If a unit only forwards to a dependency with no logic of its own (a thin repository/passthrough), don't test it — put the test on the service/behavior layer, where the branches and bugs are.
-
----
-
-## Deployment Awareness
-
-Both server and client are deployed via **Docker on Coolify**. The `Dockerfile` in each directory is the production deployment contract. Code changes must never silently break the Docker build.
-
-**Always check deployment impact when you:**
-- Add a native/system npm dependency (needs `apk add` in Dockerfile)
-- Add, remove, or rename a `NEXT_PUBLIC_*` env var (needs `ARG` + `ENV` in client Dockerfile)
-- Change the build output directory, entry point file, or default port
-- Add runtime file dependencies (templates, static assets not in `public/`)
-- Change or remove a health check endpoint
-
-**See the deployment rules** in `server/deployment.md` and `client/07-deployment.md` for full details.
-
----
-
-## Task Completion Reports
-
-After completing any task, phase, or bug fix, you MUST provide a structured completion report — not freeform paragraphs. **Read `completion-reports.md`** for the required templates and rules. This includes deployment/production impact analysis whenever infrastructure, env vars, database, or Docker changes are involved.
-
----
-
-## Code Review Checklist
-
-Before considering work done, verify:
-
-- [ ] No `any` types.
-- [ ] No hardcoded values (URLs, colors, magic numbers) — use constants and tokens.
-- [ ] No `console.log` left in code.
-- [ ] No commented-out code without a `// TODO:` explaining why.
-- [ ] Inputs validated with Zod.
-- [ ] Error cases handled (not just the happy path).
-- [ ] Existing tests still pass.
-- [ ] No "mock-echo" tests (asserting only that a mock was called, without asserting behavior/output or testing a real transform).
-- [ ] Dockerfile still compatible with changes (see Deployment Awareness above).

package/template/_claude/rules/global/investigation-before-conclusions.md

@@ -1,57 +0,0 @@
-> **SCOPE**: These rules apply to the **entire workspace** (server + client). Always active.
-
-# Investigation Before Conclusions
-
-This project (create-tigra) generates starter templates for developers who may not have deep coding experience. They trust AI output without questioning it. **A wrong suggestion that "fixes" a non-existent problem can introduce real problems.** Every recommendation must be grounded in verified understanding of how the code actually works.
-
----
-
-## The Rule
-
-**Never suggest fixes, changes, or improvements until you have fully traced how the relevant system works in this codebase.** Seeing a file, a config, or a pattern is not enough. You must follow the code path end-to-end before making any claim.
-
----
-
-## Before Answering "Is This a Bug?" or "Does This Need Fixing?"
-
-1. **Trace the actual workflow.** If the question is about uploads, go read the upload service, follow where files are saved, how they're served, how they're deleted. If it's about auth, trace the full auth flow. Don't stop at the first file you find.
-
-2. **Understand the runtime environment.** Ask yourself: does this code run in Docker or locally? Is this a dev tool or a production path? Does docker-compose run the server or just infrastructure services (MySQL, Redis)? Don't assume — verify.
-
-3. **Verify the problem exists in the real workflow.** Not in theory, not in a hypothetical scenario — in the actual way developers use this project. If no one would ever hit the issue in normal usage, it's not a problem worth fixing.
-
-4. **Don't pattern-match to conclusions.** "Uploads + Docker + no volume = must fix" is pattern-matching, not investigation. The server runs locally with `npm run dev`, not inside Docker. The `docker-compose.yml` is for MySQL and Redis only. A volume for uploads in docker-compose would solve nothing.
-
-5. **If you're unsure, say so.** "I need to check how this works before I can answer" is always better than a confident wrong answer.
-
----
-
-## What NOT to Do
-
-| Bad behavior | Why it's dangerous |
-|---|---|
-| See a Dockerfile, immediately suggest `VOLUME` | The server may not run in Docker locally |
-| See docker-compose.yml, suggest adding volumes | docker-compose may only run infrastructure, not the app |
-| Find a missing config and assume it's a bug | It may be intentionally absent because it's not needed |
-| Suggest "best practice" improvements unprompted | Unnecessary changes confuse beginners and can introduce real bugs |
-| Stop researching after finding the first related file | The first file is not the full picture — trace the complete flow |
-| Offer a fix before confirming the problem is real | Fixing non-existent problems wastes time and creates new problems |
-
----
-
-## The Standard
-
-Before every suggestion, ask yourself:
-
-1. **Did I trace the full code path?** Not just one file — the whole flow.
-2. **Do I understand the runtime environment?** Where does this code actually run?
-3. **Would a real developer actually hit this problem?** In normal usage, not edge cases.
-4. **Am I solving a real problem or a theoretical one?**
-
-If the answer to any of these is "no" — keep investigating before responding.
-
----
-
-## Why This Matters
-
-create-tigra exists to help developers who are learning to code with AI assistance. These developers will trust your suggestions without pushback. A confident but wrong suggestion — like adding a Docker volume for a service that doesn't run in Docker — will send them down a rabbit hole debugging something that was never broken. **Your job is to understand what actually works and why, not to guess based on patterns.**

package/template/_claude/rules/server/core.md

@@ -1,52 +0,0 @@
-> **SCOPE**: These rules apply specifically to the **server** directory (Fastify backend).
-
-# Server Rules — Core Index
-
-**Do NOT read every rule file upfront.** Use this index to find the right rules for your current task.
-
----
-
-## When to read which file
-
-| You are doing... | Read this |
-|------------------|-----------|
-| Setting up a module, organizing code, understanding the stack | `project-conventions.md` |
-| Creating or modifying a route / controller | `project-conventions.md` + `response-handling.md` |
-| Returning data (success, error, or paginated) | `response-handling.md` |
-| Handling or throwing errors | `response-handling.md` |
-| Writing service or business logic | `project-conventions.md` (Layer Responsibilities) |
-| Changing DB schema, migrations, indexes | `database.md` |
-| Adding or changing API endpoints | `project-conventions.md` (Postman Collection) |
-| Adding dependencies, changing ports, entry points, or env vars | `deployment.md` |
-| Unsure where to start | This file |
-
----
-
-## Architecture at a glance
-
-```
-Request
-  -> Route (Fastify plugin, defines HTTP method + path)
-  -> Controller (validates input with Zod, calls service, returns response)
-  -> Service (business logic, throws typed errors)
-  -> Repository (Prisma queries, returns raw data)
-  -> Database
-```
-
-**Three strict boundaries:**
-1. **Controllers** — parse input, call services, format responses. No business logic. No direct DB access.
-2. **Services** — all business logic. No Fastify concepts (request, reply). Throw typed `AppError` instances.
-3. **Repositories** — Prisma queries only. No business logic. No error formatting.
-
----
-
-## Non-negotiable rules (always apply)
-
-1. **Response format**: All controllers use `successResponse()` / `paginatedResponse()`. No custom shapes.
-2. **Error handling**: Only throw `AppError` subclasses. Never raw `Error` or strings. Global error handler formats all errors.
-3. **Validation**: All input validated with Zod schemas before reaching services.
-4. **Database changes**: Always via Prisma migrations. Never raw DDL.
-5. **Logging**: Use `logger` from `src/libs/logger`. Never `console.log`.
-6. **Routes**: All prefixed with `/api/v1`. Registered as Fastify plugins.
-7. **Postman**: Every new or modified endpoint must be reflected in `postman/collection.json`. Create the collection if it doesn't exist.
-8. **Deployment**: Every change must remain compatible with the Dockerfile. Read `deployment.md` when adding system dependencies, changing ports, renaming entry points, or adding env vars.

package/template/_claude/rules/server/database.md

@@ -1,124 +0,0 @@
-> **SCOPE**: These rules apply specifically to the **server** directory.
-
-# Database & Migrations
-
-## Principles
-
-- **Database**: MySQL 8.0+
-- **ORM**: Prisma 6.x (do NOT upgrade to 7.x without testing)
-- **Schema source of truth**: `prisma/schema.prisma`
-- **Dev**: Fast iteration with resets. **Prod**: Safe, forward-only migrations.
-
----
-
-## Critical Rules
-
-| Rule | Detail |
-|------|--------|
-| Schema changes | Prisma migrations ONLY. Never raw DDL. Data changes (INSERT/UPDATE/DELETE) can be raw SQL. |
-| Dev conflicts | Don't fix migration files manually. Run `prisma:reset` then `prisma:seed`. |
-| `db push` | Prototyping only. NEVER in production. |
-| `prisma:reset` | Freely in dev. NEVER in production. |
-| Production deploys | ONLY `prisma:migrate deploy`. Never reset, never manual edits. |
-
----
-
-## Naming Conventions
-
-| Entity | Format | Example |
-|--------|--------|---------|
-| Tables | `snake_case` plural | `users`, `order_items` |
-| Columns | `snake_case` | `user_id`, `created_at` |
-| Foreign keys | `<table_singular>_id` | `user_id`, `category_id` |
-| Prisma models | `PascalCase` singular | `User`, `OrderItem` |
-
----
-
-## Required Fields
-
-Every main entity table MUST have:
-```prisma
-model EntityName {
-  id        String   @id @default(uuid())
-  createdAt DateTime @default(now())
-  updatedAt DateTime @updatedAt
-  // Optional:
-  deletedAt DateTime?            // Soft deletes (prefer for user content)
-  isActive  Boolean @default(true) // Disable without deleting
-}
-```
-
----
-
-## Relationships
-
-- Use proper foreign keys with `onDelete: Cascade` for dependent data
-- Explicit junction tables for many-to-many (not implicit)
-- Normalize shared lookup data into own tables (no duplicated strings)
-- Polymorphic attachments: use `entityType` + `entityId` with `@@index([entityType, entityId])`
-- **Column renames**: Two-step migration — add new column, migrate data, then drop old column. Renaming directly DROPS data.
-
----
-
-## Indexing
-
-**Always index:** foreign keys, filter columns (WHERE clauses), composite filters, unique constraints.
-
-**Never index:** low-cardinality booleans alone, text/blob columns, fields not used in WHERE/ORDER BY.
-
-```prisma
-@@index([userId])                    // Foreign key
-@@index([categoryId, isActive])      // Composite filter
-@@unique([email])                    // Unique constraint
-```
-
----
-
-## Migration Workflow
-
-1. Edit `prisma/schema.prisma`
-2. Run: `npm run prisma:migrate dev --name descriptive_name`
-3. If conflict: `npm run prisma:reset` then `npm run prisma:seed`
-4. Verify generated SQL and use `prisma:studio` to inspect
-
-**Adding NOT NULL column**: Must provide a default value or make it optional, otherwise Prisma will error.
-
----
-
-## Production Deployment
-
-**Pre-deploy**: All migrations tested locally, seed runs, migration files committed to git.
-
-```bash
-npm run prisma:migrate deploy  # Apply pending migrations (safe)
-npm run prisma:generate        # Regenerate client
-npm start                      # Restart application
-```
-
----
-
-## Troubleshooting
-
-| Symptom | Fix |
-|---------|-----|
-| `DATABASE_URL` not found | Verify `.env` exists with valid `DATABASE_URL`. If Prisma 7 issue, downgrade to v6. |
-| "Table already exists" | `npm run prisma:reset` (dev only) |
-| "Prisma Client is not generated" | `npm run prisma:generate` |
-| Slow queries | Add missing indexes via schema, use `EXPLAIN`, use `select` to limit fields |
-
----
-
-## Commands Reference
-
-```bash
-# Development
-npm run prisma:studio         # Visual DB browser
-npm run prisma:migrate dev    # Create migration
-npm run prisma:reset          # Drop all, rerun migrations
-npm run prisma:seed           # Repopulate test data
-npm run prisma:generate       # Regenerate client
-
-# Production
-npm run prisma:migrate deploy # Apply migrations (safe)
-npm run prisma:generate       # Regenerate client
-```