create-tigra 1.0.0

package/template/.claude/rules/server-02-general-rules.md

@@ -0,0 +1,112 @@
+---
+trigger: always_on
+globs: "server/**/*"
+---
+
+> **SCOPE**: These rules apply specifically to the **server** directory.
+
+You are a senior backend engineer helping build a high-traffic API server.
+
+### PROJECT CONTEXT
+
+- Stack:
+
+  - Node.js (LTS, 20+)
+  - Fastify as HTTP framework
+  - TypeScript
+  - MySQL as the primary relational database
+  - Redis for caching, sessions, and rate limiting
+  - Zod for runtime validation and type inference
+  - Drizzle ORM (or Prisma) for DB access and migrations
+  - Jest/Vitest for tests
+
+- Domain:
+
+  - Users & Roles
+  - Core Business Entities
+  - Locations & Mapping
+  - Media (images, galleries)
+  - Resources Availability & Pricing
+  - Transactions & Bookings
+  - Payments (integration with external providers)
+  - Messaging & Communications
+
+- Goals:
+  - Clean, layered architecture: Routes → Controllers → Services → Repositories → DB
+  - High performance (Fastify, Redis, proper indexes)
+  - Easy to maintain and scale
+  - Secure (auth, input validation, rate limiting)
+  - Clear separation of concerns
+
+### ARCHITECTURE & CODE STYLE
+
+1. Use TypeScript everywhere. Always type function parameters and return types.
+2. Organize by domain/module:
+
+   src/modules/<domain>/
+
+   - <domain>.routes.ts (Fastify route definitions)
+   - <domain>.controller.ts (HTTP handlers only; no business logic)
+   - <domain>.service.ts (business logic)
+   - <domain>.repo.ts (DB queries)
+   - <domain>.schemas.ts (Zod schemas for input/output)
+
+3. Fastify:
+
+   - Use plugins and route registration with prefixes (e.g., /api/v1/<resource>).
+   - Use schemas for validation & serialization.
+   - Implement centralized error handling.
+
+4. Database:
+
+   - Use migrations (via Drizzle/Prisma) for schema changes.
+   - Add proper indexes for search-heavy fields (identifiers, price, date, type).
+   - Avoid N+1 queries; prefer joins or batched queries.
+
+5. Redis:
+
+   - Use for caching frequently accessed data.
+   - Use for rate limiting and potentially for background task signaling.
+
+6. Auth:
+
+   - Use JWT with HS256 or RS256.
+   - Store only minimal user info in the token (id, role).
+   - Implement role-based access control.
+
+7. Security:
+
+   - Validate all inputs with Zod and Fastify schemas.
+   - Never interpolate raw values into SQL; always use the ORM query builder.
+   - Implement sane rate limiting for public endpoints.
+   - Sanitize outputs where necessary.
+
+8. Coding constraints:
+
+   - Do NOT break existing exports or types unless explicitly asked.
+   - When modifying existing files, keep changes focused and minimal.
+   - Reuse existing helpers (db, logger, env) instead of re-creating them.
+   - Add TODO comments for non-trivial follow-up tasks.
+
+9. When asked to implement a feature:
+
+   - First, summarize what needs to be done.
+   - Then list files to be created/modified.
+   - Then provide code for each file in separate code blocks.
+   - Ensure imports between files are correct and consistent with the project structure.
+
+10. Testing:
+
+- For core logic (calculations, transactions, payment callbacks), provide Jest/Vitest tests.
+- Tests should be deterministic and not hit external APIs directly (use mocks).
+
+### RESPONSE FORMAT
+
+Whenever you make changes:
+
+1. Briefly explain the approach (1–2 paragraphs).
+2. Show updated/created files with full content in code blocks.
+3. Mention any migrations or environment variables that must be added.
+4. If you are unsure, state your assumptions clearly.
+
+If instructions from earlier parts of the prompt conflict with the user’s new message, follow the user’s latest explicit instructions.

package/template/.claude/rules/server-03-migrations.md

@@ -0,0 +1,21 @@
+---
+trigger: always_on
+globs: "server/**/*"
+---
+
+> **SCOPE**: These rules apply specifically to the **server** directory.
+
+# Migration Rules for AI Agent
+
+CRITICAL: When user asks for schema changes:
+
+1. ALWAYS edit `prisma/schema.prisma` first
+2. THEN run: `npm run prisma:migrate dev --name descriptive_name`
+3. IF migration fails with conflicts:
+   - DON'T try to fix manually
+   - DO run: `npm run prisma:reset`
+   - Then: `npm run prisma:seed`
+4. NEVER use `prisma db push` unless explicitly asked
+
+Development = use prisma:reset freely
+Production = ONLY use prisma:migrate deploy

package/template/.claude/rules/server-04-pagination.md

@@ -0,0 +1,131 @@
+---
+trigger: always_on
+globs: "server/**/*"
+---
+
+> **SCOPE**: These rules apply specifically to the **server** directory.
+
+## Pagination Contract (MANDATORY)
+
+All paginated API responses MUST follow a unified structure. No exceptions are allowed.
+
+### Paginated Response Format
+
+Every paginated response MUST follow this exact structure:
+```json
+{
+  "success": true,
+  "message": "string",
+  "data": {
+    "items": [],
+    "pagination": {
+      "page": 1,
+      "limit": 10,
+      "totalItems": 237,
+      "totalPages": 24,
+      "hasNextPage": true,
+      "hasPreviousPage": false
+    }
+  }
+}
+```
+
+### Response Rules
+
+- `success` is always `true`
+- `message` is REQUIRED and must be human-readable
+- `data.items` contains the array of results (can be empty array)
+- `data.pagination` is REQUIRED and contains:
+  - `page` – current page number (starts at 1)
+  - `limit` – items per page
+  - `totalItems` – total count of items across all pages
+  - `totalPages` – calculated as `Math.ceil(totalItems / limit)`
+  - `hasNextPage` – boolean, `true` if `page < totalPages`
+  - `hasPreviousPage` – boolean, `true` if `page > 1`
+
+### Shared Pagination Helper (REQUIRED)
+
+Controllers MUST use a shared `paginatedResponse` helper:
+```typescript
+function paginatedResponse<T>(
+  message: string,
+  items: T[],
+  page: number,
+  limit: number,
+  totalItems: number
+)
+```
+
+**Allowed example:**
+```typescript
+return reply.send(paginatedResponse("Resources retrieved successfully", items, page, limit, totalCount));
+```
+
+**Forbidden examples:**
+```typescript
+reply.send({ items, page, total });
+reply.send({ success: true, data: items, pagination: {...} });
+reply.send({ items: items, meta: {...} });
+```
+
+### Pagination Input Validation (REQUIRED)
+
+All endpoints accepting pagination MUST validate using a 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)
+});
+```
+
+**Rules:**
+- `page` defaults to `1`, must be positive integer
+- `limit` defaults to `10`, must be between 1 and 100
+- Use `z.coerce.number()` to handle query string conversion
+- Controllers MUST validate pagination inputs before calling services
+
+### Service Layer Requirements
+
+Services handling pagination MUST:
+- Accept `page` and `limit` as parameters
+- Return both the `items` array AND `totalItems` count
+- NOT construct pagination metadata (controller responsibility)
+- Calculate offset as: `(page - 1) * limit`
+
+**Service return pattern:**
+```typescript
+return {
+  items: results,
+  totalItems: count
+};
+```
+
+### Filter & Sort with Pagination
+
+When combining filters/sorting with pagination:
+- Filters come BEFORE pagination in query parameters
+- Pagination params (`page`, `limit`) are separate from filters
+- Apply filters/sorting to query BEFORE applying `limit` and `offset`
+- Count total items AFTER filters but BEFORE pagination
+
+**Example query string:**
+```
+?category=active&minPrice=100&sortBy=price&order=asc&page=2&limit=20
+```
+
+### Strict Prohibitions
+
+These patterns are NOT allowed:
+- Multiple pagination formats across endpoints
+- Returning raw arrays without pagination wrapper
+- Custom pagination field names (e.g., `pageNumber`, `perPage`, `count`)
+- Including pagination in query results instead of metadata
+- Zero-indexed pages (always start at 1)
+- Omitting `totalItems` or `totalPages`
+
+### Enforcement Rule
+
+If a user instruction conflicts with this pagination contract:
+- Follow the user instruction ONLY if explicitly stated
+- Otherwise, this pagination contract is non-negotiable
+- Pagination structure MUST be consistent across ALL endpoints

package/template/.claude/rules/server-05-project-conventions.md

@@ -0,0 +1,72 @@
+---
+trigger: always_on
+globs: "server/**/*"
+---
+
+> **SCOPE**: These rules apply specifically to the **server** directory.
+
+# API Server – Project Conventions
+
+## Package manager
+
+- Detect the package manager from the lockfile:
+  - If `pnpm-lock.yaml` exists → use `pnpm`
+  - If `yarn.lock` exists → use `yarn`
+  - Else → use `npm`
+
+## File & folder structure
+
+- Keep everything under `src/`.
+- Prefer this layout:
+
+  - `src/app.ts` → Fastify instance and plugin registration
+  - `src/server.ts` → actual `listen()` call, no app logic
+  - `src/config/` → env, config, constants
+  - `src/libs/` → shared libraries (db, redis, logger, auth)
+  - `src/modules/<domain>/` → domain modules:
+    - `<domain>.routes.ts`
+    - `<domain>.controller.ts`
+    - `<domain>.service.ts`
+    - `<domain>.repo.ts`
+    - `<domain>.schemas.ts`
+    - `<domain>.types.ts` (if needed)
+
+- When adding new modules, stick to `src/modules/<name>/` and keep the exact naming pattern.
+
+## Coding style
+
+- Use TypeScript with `strict` mode ON.
+- Prefer `async/await` over `.then()`.
+- Prefer named exports over default exports, except for:
+  - `src/app.ts` → default export is the Fastify instance
+  - Frontend components (if any).
+- Use consistent import paths:
+  - Use relative imports inside a module: `./user.service`
+  - Use aliased imports for cross-module paths if configured (e.g. `@modules/users/...`).
+
+## Error handling
+
+- Controllers must never throw raw errors; they should:
+  - Either use a shared error helper, or
+  - Let Fastify’s error handler handle typed errors.
+- Never `console.log` for production logic:
+  - Use the shared `logger` from `src/libs/logger`.
+
+## API versioning & routes
+
+- All API routes must be prefixed with `/api/v1`.
+- Group routes by domain:
+  - `/api/v1/auth/...`
+  - `/api/v1/users/...`
+  - `/api/v1/<domain_resource>/...`
+- When adding new routes, register them in a Fastify plugin under `src/modules/<domain>/<domain>.routes.ts`.
+
+## Service Layer Rules
+
+- Every domain module must include a `<domain>.service.ts` file.
+- Services contain all business logic and must NOT depend on Fastify, reply, request, or HTTP-specific concepts.
+- Controllers must call services instead of performing logic directly.
+- Services may call repositories for DB operations.
+- Services must throw typed AppError instances for failures.
+- Services must not return success or error responses; they only return data or throw errors.
+- Services must be stateless and reusable.

package/template/.claude/rules/server-06-response-handling.md

@@ -0,0 +1,174 @@
+---
+trigger: always_on
+globs: "server/**/*"
+---
+
+> **SCOPE**: These rules apply specifically to the **server** directory.
+
+API Server – Error & Success Response Rules
+
+These rules define the ONLY allowed way to return success and error responses from the API. All AI assistants MUST follow this contract strictly.
+
+Unified Response Contract (MANDATORY)
+The API uses a single, stable response structure for all endpoints. No exceptions are allowed.
+
+Success Response Format
+Every successful response MUST follow this exact structure:
+
+{
+"success": true,
+"message": "string",
+"data": {}
+}
+
+Rules:
+
+success is always true
+
+message is REQUIRED and must be human-readable
+
+data can be an object, array, or null
+
+Controllers MUST use a shared success helper (for example successResponse)
+
+Controllers MUST NOT return raw values or custom-shaped JSON
+
+Allowed example:
+return reply.send(successResponse("Resource created successfully", data));
+
+Forbidden examples:
+reply.send(data);
+reply.send({ data: data });
+reply.send({ success: true, data });
+
+Error Response Format
+Every error response MUST follow this exact structure:
+
+{
+"success": false,
+"error": {
+"code": "ERROR_CODE",
+"message": "Human readable message"
+}
+}
+
+Rules:
+
+success is always false
+
+code must be a stable machine-readable string (for example RESOURCE_NOT_FOUND)
+
+message must be safe for end users
+
+Internal details, stack traces, or SQL errors MUST NOT be exposed
+
+Controllers MUST NOT manually send error responses
+
+Global Error Handling Architecture
+The server MUST define ONE global Fastify error handler using fastify.setErrorHandler(...).
+This global handler is responsible for:
+
+Mapping errors to HTTP status codes
+
+Formatting the unified error response
+
+Logging internal error details on server side only
+
+Error Throwing Rules (CRITICAL)
+Controllers and services MUST throw typed errors ONLY.
+They MUST NOT throw:
+
+raw Error
+
+strings
+
+unstructured objects
+
+Required Error Base Class
+All custom errors MUST extend a shared AppError class which defines:
+
+code
+
+message
+
+statusCode
+
+Allowed Error Types
+Allowed subclasses:
+
+BadRequestError
+
+ValidationError
+
+UnauthorizedError
+
+ForbiddenError
+
+NotFoundError
+
+ConflictError
+
+InternalError
+
+Each subclass MUST:
+
+extend AppError
+
+set a meaningful code
+
+set an appropriate statusCode
+
+Controller Responsibilities
+Controllers MUST:
+
+Validate input using Zod schemas
+
+Call service-layer logic only
+
+Return success responses using the shared success helper
+
+Throw typed errors when something fails
+
+Controllers MUST NOT:
+
+Set HTTP status codes for errors
+
+Build custom error JSON structures
+
+Catch errors unless rethrowing typed errors
+
+Service Layer Responsibilities
+Services MUST:
+
+Contain business logic
+
+Throw typed AppError errors when needed
+
+NEVER depend on Fastify reply or HTTP objects
+
+Logging Rules
+Logging MUST occur only inside:
+
+The global error handler
+
+Shared logging utilities
+
+Controllers MUST NOT log unless explicitly instructed. Internal logs MUST NOT be sent to the client.
+
+Strict Prohibitions
+These patterns are NOT allowed anywhere:
+
+Multiple response formats
+
+reply.send({ error: "text" })
+
+throw new Error("message")
+
+Returning raw errors from services
+
+Leaking stack traces or database internals to users
+
+Final Enforcement Rule
+If a user instruction conflicts with this document:
+Follow the user instruction ONLY if explicitly stated.
+Otherwise, this response contract is non-negotiable.