create-tigra 1.1.0 → 2.0.1

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

@@ -0,0 +1,124 @@
+> **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
+```

package/template/_claude/rules/server/project-conventions.md

@@ -0,0 +1,150 @@
+> **SCOPE**: These rules apply specifically to the **server** directory.
+
+# Project Conventions
+
+## Stack
+
+| Technology | Purpose |
+|------------|---------|
+| Node.js 20+ LTS | Runtime |
+| Fastify | HTTP framework (plugins, route prefixes, centralized error handling) |
+| TypeScript (strict) | Language — always type parameters and return types |
+| MySQL 8.0+ | Primary database |
+| Prisma 6.x | ORM, migrations, schema source of truth |
+| Redis | Caching (frequently accessed data, lookups), rate limiting, background task signaling |
+| Zod | Runtime validation and type inference |
+| JWT (HS256/RS256) | Auth — minimal token payload (id, role), role-based access control |
+| PM2 + Nginx | Production deployment (cluster mode) |
+| Jest / Vitest | Testing — deterministic, mock external APIs |
+
+## Package Manager
+
+Detect from lockfile: `pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, else → npm.
+
+## Folder Structure
+
+```
+src/
+├── app.ts              # Fastify instance and plugin registration
+├── server.ts           # listen() call only, no app logic
+├── config/             # env, config, constants
+├── libs/               # shared libraries (db, redis, logger, auth)
+└── modules/<domain>/   # domain modules
+    ├── <domain>.routes.ts
+    ├── <domain>.controller.ts
+    ├── <domain>.service.ts
+    ├── <domain>.repo.ts
+    ├── <domain>.schemas.ts
+    └── <domain>.types.ts  (if needed)
+```
+
+New modules MUST follow `src/modules/<name>/` with the exact naming pattern above.
+
+## API Routes
+
+All routes prefixed with `/api/v1`. Grouped by domain: `/api/v1/<domain>/...`
+
+Register routes as Fastify plugins in `<domain>.routes.ts`.
+
+## Coding Style
+
+- TypeScript `strict` mode ON
+- `async/await` over `.then()`
+- Named exports (except `src/app.ts` which default-exports the Fastify instance)
+- Relative imports within a module (`./user.service`), aliased imports cross-module (`@modules/users/...`)
+- Use `logger` from `src/libs/logger` — never `console.log`
+
+## Layer Responsibilities
+
+| Layer | MUST | MUST NOT |
+|-------|------|----------|
+| **Routes** | Register Fastify plugins, define HTTP method + path | Contain any logic |
+| **Controllers** | Validate input (Zod), call services, return via `successResponse`/`paginatedResponse`, throw typed `AppError` | Business logic, direct DB access, manual error JSON, set HTTP status codes for errors |
+| **Services** | All business logic, throw `AppError` subclasses, call repos for DB ops, be stateless | Touch Fastify (request/reply), format responses, return HTTP status codes |
+| **Repositories** | Prisma queries, return raw data | Business logic, error formatting |
+
+## Postman Collection
+
+When API endpoints are created or modified, **always update the Postman collection** (`postman/collection.json`). If the collection does not exist, create it.
+
+### Collection Structure
+
+```
+postman/
+├── collection.json        # Postman v2.1 collection
+└── environment.json       # Environment variables template
+```
+
+### Environment Variables
+
+Use variables so requests are connected and portable:
+
+```json
+{
+  "variables": [
+    { "key": "baseUrl", "value": "http://localhost:3000/api/v1" },
+    { "key": "accessToken", "value": "" },
+    { "key": "refreshToken", "value": "" },
+    { "key": "userId", "value": "" }
+  ]
+}
+```
+
+- **`{{baseUrl}}`** — all request URLs use this prefix, never hardcoded hosts.
+- **`{{accessToken}}`** / **`{{refreshToken}}`** — set automatically via login/register test scripts.
+- **`{{userId}}`** and other IDs — captured from responses so subsequent requests can reference them.
+
+### Auto-set Tokens via Test Scripts
+
+The **Login** and **Register** requests MUST include a `Tests` script that stores tokens and user data into collection variables:
+
+```javascript
+if (pm.response.code === 200 || pm.response.code === 201) {
+  const res = pm.response.json();
+  pm.collectionVariables.set("accessToken", res.data.tokens.accessToken);
+  pm.collectionVariables.set("refreshToken", res.data.tokens.refreshToken);
+  pm.collectionVariables.set("userId", res.data.user.id);
+}
+```
+
+### Auth Header
+
+All authenticated requests use a collection-level or folder-level **Bearer Token** auth set to `{{accessToken}}`. Do not duplicate the auth header on every request — inherit from the parent folder.
+
+### Folder Organization
+
+Organize requests into folders matching domain modules:
+
+```
+Collection Root (Bearer Token: {{accessToken}})
+├── Auth (No Auth)
+│   ├── Register        → POST {{baseUrl}}/auth/register
+│   ├── Login           → POST {{baseUrl}}/auth/login    [sets tokens]
+│   ├── Refresh Token   → POST {{baseUrl}}/auth/refresh
+│   └── Logout          → POST {{baseUrl}}/auth/logout
+├── Users
+│   ├── Get Me          → GET {{baseUrl}}/users/me
+│   ├── Update Me       → PATCH {{baseUrl}}/users/me
+│   └── Delete Me       → DELETE {{baseUrl}}/users/me
+└── <Domain>            → One folder per module
+    ├── List            → GET {{baseUrl}}/<domain>
+    ├── Get by ID       → GET {{baseUrl}}/<domain>/{{<domain>Id}}
+    ├── Create          → POST {{baseUrl}}/<domain>
+    ├── Update          → PATCH {{baseUrl}}/<domain>/{{<domain>Id}}
+    └── Delete          → DELETE {{baseUrl}}/<domain>/{{<domain>Id}}
+```
+
+### Rules
+
+1. **Every route gets a request.** No endpoint should exist without a matching Postman request.
+2. **Include example request bodies** for POST/PATCH/PUT with realistic placeholder data.
+3. **Capture IDs from create responses** — add a `Tests` script that sets `{{<domain>Id}}` so Get/Update/Delete requests work without manual copy-paste.
+4. **Auth folder uses "No Auth"** — login and register don't need tokens. All other folders inherit Bearer Token from the collection root.
+5. **Keep it importable** — the collection must be valid Postman v2.1 JSON that anyone can import and run immediately after setting `baseUrl`.
+
+## Security
+
+- Validate all inputs with Zod schemas
+- Never interpolate raw values into SQL — always use Prisma query builder
+- Rate limit public endpoints
+- Avoid N+1 queries — prefer joins or batched queries

package/template/_claude/rules/server/response-handling.md

@@ -0,0 +1,144 @@
+> **SCOPE**: These rules apply specifically to the **server** directory.
+
+# Response Handling
+
+All API responses follow a unified contract. No exceptions.
+
+---
+
+## Success Response
+
+```json
+{
+  "success": true,
+  "message": "Human-readable message",
+  "data": {}
+}
+```
+
+- `data` can be an object, array, or null
+- Controllers MUST use the shared `successResponse()` helper
+
+```typescript
+// Allowed
+return reply.send(successResponse("Item created successfully", item));
+
+// Forbidden — never send raw values or custom shapes
+reply.send(item);
+reply.send({ data: item });
+reply.send({ success: true, item });
+```
+
+---
+
+## Error Response
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "MACHINE_READABLE_CODE",
+    "message": "Human-readable, user-safe message"
+  }
+}
+```
+
+- `code`: stable machine-readable string (e.g. `RESOURCE_NOT_FOUND`, `VALIDATION_FAILED`)
+- Never expose internal details, stack traces, or SQL errors
+- Controllers MUST NOT manually construct error responses
+
+---
+
+## Paginated Response
+
+```json
+{
+  "success": true,
+  "message": "string",
+  "data": {
+    "items": [],
+    "pagination": {
+      "page": 1,
+      "limit": 10,
+      "totalItems": 237,
+      "totalPages": 24,
+      "hasNextPage": true,
+      "hasPreviousPage": false
+    }
+  }
+}
+```
+
+Controllers MUST use the shared `paginatedResponse()` helper:
+
+```typescript
+function paginatedResponse<T>(message: string, items: T[], page: number, limit: number, totalItems: number)
+
+// Allowed
+return reply.send(paginatedResponse("Items retrieved successfully", items, page, limit, totalCount));
+```
+
+### Pagination Input Validation
+
+All paginated endpoints MUST validate with this shared Zod schema:
+
+```typescript
+const PaginationSchema = z.object({
+  page: z.coerce.number().int().min(1).default(1),
+  limit: z.coerce.number().int().min(1).max(100).default(10)
+});
+```
+
+### Service Return Pattern for Pagination
+
+Services return `{ items, totalItems }`. Controllers build the pagination metadata.
+
+```typescript
+// Service returns:
+return { items, totalItems: count };
+// Offset calculation: (page - 1) * limit
+```
+
+### Filters with Pagination
+
+- Apply filters/sorting BEFORE `limit` and `offset`
+- Count total items AFTER filters but BEFORE pagination
+- Pages start at 1 (never 0)
+
+---
+
+## Error Architecture
+
+ONE global Fastify error handler via `fastify.setErrorHandler(...)`:
+- Maps `AppError` subclasses to HTTP status codes
+- Formats the unified error JSON structure
+- Logs internal details server-side only — never sends to client
+
+### AppError Subclasses
+
+All errors MUST extend `AppError` (which defines `code`, `message`, `statusCode`). Only throw these typed subclasses — never raw `Error`, strings, or plain objects.
+
+| Class | Status | Example Code |
+|-------|--------|--------------|
+| `BadRequestError` | 400 | `INVALID_INPUT` |
+| `ValidationError` | 422 | `VALIDATION_FAILED` |
+| `UnauthorizedError` | 401 | `UNAUTHORIZED` |
+| `ForbiddenError` | 403 | `FORBIDDEN` |
+| `NotFoundError` | 404 | `RESOURCE_NOT_FOUND` |
+| `ConflictError` | 409 | `EMAIL_ALREADY_EXISTS` |
+| `InternalError` | 500 | `INTERNAL_ERROR` |
+
+---
+
+## Controller Response Rules
+
+**ALWAYS:**
+- Use `successResponse()` or `paginatedResponse()` for all responses
+- Validate input with Zod before calling services
+- Throw typed `AppError` subclasses on failure
+
+**NEVER:**
+- Send raw values or custom JSON shapes
+- Set HTTP status codes for errors (global handler does this)
+- Catch errors unless rethrowing as typed `AppError`
+- Manually construct error response JSON

package/template/client/.env.example

@@ -0,0 +1,5 @@
+# Public API URL - points to the server's base URL
+NEXT_PUBLIC_API_BASE_URL=http://localhost:8000/api/v1
+
+# App name displayed in the UI
+NEXT_PUBLIC_APP_NAME={{PROJECT_DISPLAY_NAME}}

package/template/client/README.md

@@ -0,0 +1,36 @@
+This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+
+## Getting Started
+
+First, run the development server:
+
+```bash
+npm run dev
+# or
+yarn dev
+# or
+pnpm dev
+# or
+bun dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+
+You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+
+This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+
+## Learn More
+
+To learn more about Next.js, take a look at the following resources:
+
+- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
+- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+
+You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+
+## Deploy on Vercel
+
+The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+
+Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.

package/template/client/components.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/app/globals.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "lucide",
+  "rtl": false,
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "registries": {}
+}

package/template/client/eslint.config.mjs

@@ -0,0 +1,18 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+
+const eslintConfig = defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  // Override default ignores of eslint-config-next.
+  globalIgnores([
+    // Default ignores of eslint-config-next:
+    ".next/**",
+    "out/**",
+    "build/**",
+    "next-env.d.ts",
+  ]),
+]);
+
+export default eslintConfig;

package/template/client/next.config.ts

@@ -0,0 +1,34 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  async headers() {
+    return [
+      {
+        source: "/(.*)",
+        headers: [
+          { key: "X-Frame-Options", value: "DENY" },
+          { key: "X-Content-Type-Options", value: "nosniff" },
+          { key: "Referrer-Policy", value: "origin-when-cross-origin" },
+          { key: "X-XSS-Protection", value: "1; mode=block" },
+          {
+            key: "Content-Security-Policy",
+            value: [
+              "default-src 'self'",
+              "script-src 'self' 'unsafe-eval' 'unsafe-inline'",
+              "style-src 'self' 'unsafe-inline'",
+              "img-src 'self' blob: data: https:",
+              "font-src 'self'",
+              "object-src 'none'",
+              "base-uri 'self'",
+              "form-action 'self'",
+              "frame-ancestors 'none'",
+              `connect-src 'self' ${process.env.NEXT_PUBLIC_API_BASE_URL || "http://localhost:8000"}`,
+            ].join("; "),
+          },
+        ],
+      },
+    ];
+  },
+};
+
+export default nextConfig;

package/template/client/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "{{PROJECT_NAME}}-client",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint src/"
+  },
+  "dependencies": {
+    "@hookform/resolvers": "^5.2.2",
+    "@reduxjs/toolkit": "^2.11.2",
+    "@tanstack/react-query": "^5.90.21",
+    "axios": "^1.13.5",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^0.563.0",
+    "next": "16.1.6",
+    "next-themes": "^0.4.6",
+    "radix-ui": "^1.4.3",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "react-hook-form": "^7.71.1",
+    "react-redux": "^9.2.0",
+    "sonner": "^2.0.7",
+    "tailwind-merge": "^3.4.0",
+    "tailwindcss-animate": "^1.0.7",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4",
+    "@tanstack/react-query-devtools": "^5.91.3",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "eslint": "^9",
+    "eslint-config-next": "16.1.6",
+    "shadcn": "^3.8.4",
+    "tailwindcss": "^4",
+    "tw-animate-css": "^1.4.0",
+    "typescript": "^5"
+  }
+}

package/template/client/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;

package/template/client/src/app/(auth)/layout.tsx

@@ -0,0 +1,18 @@
+import type React from 'react';
+
+import { APP_NAME } from '@/lib/constants/app.constants';
+
+export default function AuthLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}): React.ReactElement {
+  return (
+    <div className="flex min-h-dvh flex-col items-center justify-center px-4 py-12">
+      <span className="mb-8 text-xl font-semibold tracking-tight text-foreground">
+        {APP_NAME}
+      </span>
+      {children}
+    </div>
+  );
+}

package/template/client/src/app/(auth)/login/page.tsx

@@ -0,0 +1,13 @@
+import type React from 'react';
+
+import { LoginForm } from '@/features/auth/components/LoginForm';
+
+import type { Metadata } from 'next';
+
+export const metadata: Metadata = {
+  title: 'Sign in',
+};
+
+export default function LoginPage(): React.ReactElement {
+  return <LoginForm />;
+}

package/template/client/src/app/(auth)/register/page.tsx

@@ -0,0 +1,13 @@
+import type React from 'react';
+
+import { RegisterForm } from '@/features/auth/components/RegisterForm';
+
+import type { Metadata } from 'next';
+
+export const metadata: Metadata = {
+  title: 'Create account',
+};
+
+export default function RegisterPage(): React.ReactElement {
+  return <RegisterForm />;
+}

package/template/client/src/app/(main)/dashboard/page.tsx

@@ -0,0 +1,22 @@
+import type React from 'react';
+
+import type { Metadata } from 'next';
+
+export const metadata: Metadata = {
+  title: 'Dashboard',
+};
+
+export default function DashboardPage(): React.ReactElement {
+  return (
+    <div className="container mx-auto px-4 py-12 md:px-6 lg:px-8">
+      <div className="space-y-6">
+        <div>
+          <h1 className="text-3xl font-bold tracking-tight">Dashboard</h1>
+          <p className="mt-2 text-muted-foreground">
+            Welcome to your dashboard. This is where you&apos;ll manage everything.
+          </p>
+        </div>
+      </div>
+    </div>
+  );
+}

package/template/client/src/app/(main)/layout.tsx

@@ -0,0 +1,11 @@
+import type React from 'react';
+
+import { MainLayout } from '@/components/layout/MainLayout';
+
+export default function MainGroupLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}): React.ReactElement {
+  return <MainLayout>{children}</MainLayout>;
+}