V2

.cursor/commands/create-module.md

@@ -0,0 +1,180 @@
+# Create a new module (tbk CLI)
+
+## Overview
+
+Scaffold a fully-typed module with controller, service, router, schema, and model files, then wire it into the application routing system.
+
+## Inputs
+
+- **moduleName**: module folder/name in `src/modules/` (e.g., `product`)
+- **apiPath**: optional API root path; defaults to `/api` (e.g., `/api/v1`)
+
+## Steps
+
+1. **Generate module files**
+
+   ```bash
+   pnpm tbk generate:module <moduleName> --path <apiPath>
+   ```
+
+   Examples:
+
+   ```bash
+   pnpm tbk generate:module product --path /api
+   pnpm tbk generate:module product --path /api/v1
+   ```
+
+   This creates:
+
+   - `src/modules/<moduleName>/<moduleName>.dto.ts`
+   - `src/modules/<moduleName>/<moduleName>.model.ts`
+   - `src/modules/<moduleName>/<moduleName>.schema.ts`
+   - `src/modules/<moduleName>/<moduleName>.services.ts`
+   - `src/modules/<moduleName>/<moduleName>.controller.ts`
+   - `src/modules/<moduleName>/<moduleName>.router.ts` (exports `<MODULE>_ROUTER_ROOT` and default router)
+
+2. **Register router in routes**
+   Add an import and `router.use(...)` in `src/routes/routes.ts`:
+
+   ```ts
+   // add with other imports
+   import <moduleName>Router, { <MODULE_NAME>_ROUTER_ROOT } from '../modules/<moduleName>/<moduleName>.router';
+
+   // add with other router.use calls
+   router.use(<MODULE_NAME>_ROUTER_ROOT, <moduleName>Router);
+   ```
+
+   - Replace `<moduleName>` with your actual module name (e.g., `product`)
+   - Replace `<MODULE_NAME>` with the uppercased module name (e.g., `PRODUCT`)
+
+   Example for `product`:
+
+   ```ts
+   import productRouter, {
+     PRODUCT_ROUTER_ROOT,
+   } from '../modules/product/product.router';
+   router.use(PRODUCT_ROUTER_ROOT, productRouter);
+   ```
+
+3. **Rebuild OpenAPI documentation**
+
+   ```bash
+   pnpm openapi
+   ```
+
+   Auto-generates Swagger from MagicRouter + Zod schemas.
+
+4. **Typecheck and lint**
+
+   ```bash
+   pnpm typecheck && pnpm lint
+   ```
+
+5. **Register with admin dashboard** (if needed)
+
+   Add your module to `src/plugins/admin/registry.ts`:
+
+   ```ts
+   import <ModuleName>Model from '../modules/<moduleName>/<moduleName>.model';
+
+   export const adminResources: AdminResource[] = [
+     // ... existing resources
+     {
+       name: '<moduleName>s',
+       label: '<ModuleName>s',
+       model: <ModuleName>Model,
+       readOnlyFields: ['_id', 'createdAt', 'updatedAt']
+     },
+   ];
+   ```
+
+   - Replace `<moduleName>` with your module name (e.g., `product`)
+   - Replace `<ModuleName>` with PascalCase version (e.g., `Product`)
+   - Adjust `readOnlyFields` as needed for your module
+
+6. **Optional: Create seeder and factory**
+   ```bash
+   pnpm tbk make:factory <moduleName>/<Name>
+   pnpm tbk make:seeder <moduleName>/<Name>
+   ```
+
+## Module Checklist
+
+- [ ] Module files generated successfully
+- [ ] Router registered in `src/routes/routes.ts`
+- [ ] Module registered in admin dashboard (`src/plugins/admin/registry.ts`) (if needed)
+- [ ] OpenAPI documentation rebuilt
+- [ ] Code passes typecheck and lint
+- [ ] Environment variables added to `src/config/env.ts` and `.env.sample` (if needed)
+- [ ] Committed with Conventional Commits format
+
+## Response Validation
+
+Generated modules automatically use the **response validation system**:
+
+- **Response schemas** defined in schema files using `R.success()`, `R.paginated()`, `R.error()` helpers
+- **Response types** exported from schema files for type-safe controllers
+- **Typed response helpers** (`res.ok()`, `res.created()`, `res.noContent()`) in controllers
+- **OpenAPI documentation** includes accurate per-status response schemas
+- **Runtime validation** ensures responses match schemas (configurable via `RESPONSE_VALIDATION` env var)
+
+### Example from generated code:
+
+**Schema file (module.schema.ts):**
+
+```typescript
+import { R } from '../../openapi/response.builders';
+import { itemOutSchema } from './item.dto';
+
+// Response schemas
+export const getItemsResponseSchema = R.paginated(itemOutSchema);
+export const createItemResponseSchema = R.success(itemOutSchema);
+
+// Response types
+export type GetItemsResponseSchema = z.infer<typeof getItemsResponseSchema>;
+export type CreateItemResponseSchema = z.infer<typeof createItemResponseSchema>;
+```
+
+**Router (module.router.ts):**
+
+```typescript
+import { getItemsResponseSchema } from './module.schema';
+
+router.get(
+  '/',
+  {
+    requestType: { query: getItemsSchema },
+    responses: {
+      200: getItemsResponseSchema,
+    },
+  },
+  canAccess(),
+  handleGetItems,
+);
+```
+
+**Controller (module.controller.ts):**
+
+```typescript
+import type { ResponseExtended } from '../../types';
+import type { GetItemsResponseSchema } from './module.schema';
+
+export const handleGetItems = async (
+  req: Request<unknown, unknown, unknown, GetItemsSchemaType>,
+  res: ResponseExtended<GetItemsResponseSchema>,
+) => {
+  const { results, paginatorInfo } = await getItems(req.query);
+  return res.ok?.({
+    success: true,
+    data: { items: results, paginator: paginatorInfo },
+  });
+};
+```
+
+## Notes
+
+- Routes must use `MagicRouter`; the generator already sets this up and defines `<MODULE>_ROUTER_ROOT` using the `--path` you pass
+- Generated code uses **new response validation pattern** - see `docs/RESPONSE_VALIDATION.md` for details
+- Legacy `successResponse()` still works but new pattern is recommended
+- Keep environment configs valid, and update `src/config/env.ts` and `.env.sample` if you introduce new variables
+- Commit with Conventional Commits (e.g., `feat(<moduleName>): add <feature>`)

.cursor/commands/create-seeder.md

@@ -0,0 +1,131 @@
+# Create a module-tied seeder + factory (tbk CLI)
+
+## Overview
+
+Scaffold a seeder and its factory for a module, register it in the database seeder, and populate your database with test data.
+
+## Inputs
+
+- **module**: existing module folder in `src/modules/` (e.g., `user`)
+- **name**: base name used for both factory and seeder (CLI appends `Seeder`)
+
+## Steps
+
+1. **Generate factory and seeder files**
+
+   ```bash
+   # 1) Factory (used inside the seeder)
+   pnpm tbk make:factory <module>/<Name>
+
+   # 2) Seeder (will import and use the factory)
+   pnpm tbk make:seeder <module>/<Name>
+   ```
+
+   Examples:
+
+   ```bash
+   pnpm tbk make:factory payment/Payment && pnpm tbk make:seeder payment/Payment
+   pnpm tbk make:factory user/User && pnpm tbk make:seeder user/User
+   ```
+
+   This creates:
+
+   - `src/modules/<module>/factories/<name>.factory.ts` (lowercased file; exports `<camelName>Factory`)
+   - `src/modules/<module>/seeders/<Name>Seeder.ts`
+
+2. **Implement seeder logic**
+   Edit `src/modules/<module>/seeders/<Name>Seeder.ts` to import the factory and insert documents via the module model:
+
+   ```ts
+   import <Model> from '../<module>.model';
+   import { <camelName>Factory } from '../factories/<name>.factory';
+
+   export const <Name>Seeder = {
+     name: '<Name>Seeder',
+     groups: ['dev'],
+     // collections help --fresh drop only the affected collections
+     collections: ['<collection_name>'],
+     async run(ctx) {
+       ctx.logger.info('Running <Name>Seeder');
+
+       const docs = Array.from({ length: 10 }, (_, i) =>
+         <camelName>Factory.build(i + 1),
+       );
+
+       if (!ctx.env.dryRun) {
+         await <Model>.insertMany(docs);
+       }
+
+       // share references across seeders if needed
+       ctx.refs.set('<module>:seeded', docs.map((d) => d._id));
+     },
+   };
+   ```
+
+   - Replace `<Model>` with your module's mongoose model (e.g., `Payment`)
+   - Replace `<camelName>`/`<name>` with the factory export/file (e.g., `paymentFactory`/`payment`)
+   - Replace `<collection_name>` with the underlying collection name
+
+3. **Register seeder**
+   Add your seeder to `src/seeders/registry.ts`:
+
+   ```ts
+   import { <Name>Seeder } from '../modules/<module>/seeders/<Name>Seeder';
+
+   export const seeders = [
+     // existing seeders...
+     <Name>Seeder,
+   ];
+   ```
+
+4. **Run seeders**
+
+   ```bash
+   # default: group=dev, transactions enabled
+   pnpm tbk seed
+
+   # choose specific group
+   pnpm tbk seed --group dev
+   pnpm tbk seed --group test
+   pnpm tbk seed --group demo
+
+   # run specific seeders only (comma-separated names)
+   pnpm tbk seed --only <Name>Seeder,OtherSeeder
+
+   # drop involved collections before seeding
+   pnpm tbk seed --fresh
+
+   # dry run (log only, no writes)
+   pnpm tbk seed --dry-run
+
+   # set random seed value
+   pnpm tbk seed --seed 42
+
+   # disable transactions globally
+   pnpm tbk seed --no-transaction
+
+   # allow in production (blocked unless forced)
+   pnpm tbk seed --force
+   ```
+
+## Seeder Checklist
+
+- [ ] Factory file generated in `src/modules/<module>/factories/`
+- [ ] Seeder file generated in `src/modules/<module>/seeders/`
+- [ ] Factory implements `build(i, overrides)` method
+- [ ] Seeder registered in `src/seeders/registry.ts`
+- [ ] Collections specified in seeder config
+- [ ] MongoDB service running (`docker compose up -d`)
+- [ ] Seeder tested with `--dry-run` flag
+
+## Advanced Options
+
+- **Order dependencies**: Use `dependsOn` to order seeders (names must match other seeders' `name`)
+- **Share data**: Use `ctx.refs.set()` and `ctx.refs.get()` to pass data between seeders
+- **Group targeting**: Assign seeders to groups (`dev`, `test`, `demo`) for different environments
+
+## Notes
+
+- Factories live in `src/modules/<module>/factories/` and export `<camelName>Factory` with a `build(i, overrides)` helper
+- Ensure MongoDB is reachable before seeding (`docker compose up -d`)
+- Use transactions by default for data consistency; disable with `--no-transaction` if needed

.cursor/rules/architecture.mdc

@@ -0,0 +1,79 @@
+---
+alwaysApply: true
+description: Core architecture and patterns for the TypeScript backend toolkit
+---
+
+# Architecture Overview
+
+This is a TypeScript Express.js backend toolkit with a modular, type-safe architecture.
+
+## Core Patterns
+
+### MagicRouter System
+
+- All routes MUST use MagicRouter from [router.ts](mdc:src/plugins/magic/router.ts)
+- MagicRouter automatically generates OpenAPI/Swagger documentation from Zod schemas
+- Never use plain Express `app.get()` or `router.get()` - always use MagicRouter
+
+### Module Structure
+
+Modules live in [src/modules/](mdc:src/modules/) and follow this structure:
+
+```
+module-name/
+  ├── module.controller.ts    # Business logic handlers
+  ├── module.router.ts        # MagicRouter route definitions
+  ├── module.service.ts       # Database and external service interactions
+  ├── module.schema.ts        # Zod schemas for validation
+  ├── module.model.ts         # Mongoose models
+  └── module.dto.ts           # TypeScript types/interfaces
+```
+
+### Validation & Type Safety
+
+- ALWAYS use Zod schemas for request/response validation
+- Runtime validation via [validate-zod-schema.ts](mdc:src/middlewares/validate-zod-schema.ts)
+- Extend Zod with OpenAPI metadata using `.openapi()` method from [zod-extend.ts](mdc:src/plugins/magic/zod-extend.ts)
+- Use TypeScript strict mode - no `any` types
+
+### Configuration
+
+- All config in [env.ts](mdc:src/config/env.ts)
+- Environment variables validated with Zod
+- Time values are in milliseconds (converted from strings like "1d" or "7d")
+
+### Database
+
+- MongoDB with Mongoose ODM
+- Connection managed in [database.ts](mdc:src/lib/database.ts)
+- Models defined per module (e.g., [user.model.ts](mdc:src/modules/user/user.model.ts))
+
+### Background Jobs & Queues
+
+- BullMQ with Redis for all background jobs
+- Email queue in [email.queue.ts](mdc:src/queues/email.queue.ts)
+- Admin dashboard at `/queues`
+
+### Error Handling
+
+- Global error handler in [error-handler.ts](mdc:src/middlewares/error-handler.ts)
+- Throw errors with proper HTTP status codes
+- Errors are automatically caught and formatted
+
+## Technology Stack
+
+- **Runtime**: Node.js with TypeScript
+- **Framework**: Express.js
+- **Validation**: Zod
+- **Database**: MongoDB + Mongoose
+- **Cache/Queue**: Redis + BullMQ
+- **Auth**: JWT (with optional OTP)
+- **Storage**: AWS S3
+- **Email**: React Email + Mailgun
+- **Real-time**: Socket.io
+- **API Docs**: Swagger/OpenAPI (auto-generated)
+- **Logger**: Pino
+
+## Package Manager
+
+ALWAYS use `pnpm` - never npm or yarn