Skip to content
Open

V2 #14

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
162 changes: 162 additions & 0 deletions .cursor/rules/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,162 @@
# Cursor Rules for TypeScript Backend Toolkit

This directory contains Cursor Rules (`.mdc` files) that help AI assistants understand and work with this codebase effectively.

## Rules Overview

### Core Architecture Rules

**[architecture.mdc](architecture.mdc)** - _Always Applied_

- Core architectural patterns
- Technology stack overview
- MagicRouter system
- Module structure
- Configuration management
- Background jobs and queues

### File-Type Specific Rules

**[routing.mdc](routing.mdc)** - _Applies to: `_.router.ts`, `_.routes.ts`_

- MagicRouter usage patterns
- Route configuration
- Authentication middleware
- File upload handling
- Common routing mistakes

**[schemas.mdc](schemas.mdc)** - _Applies to: `_.schema.ts`\*

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The asterisk * at the end of the file glob is being interpreted as a Markdown emphasis (italics) marker, which makes the documentation slightly harder to read. To ensure it's rendered as a literal character, it should be escaped with a backslash.

This same issue occurs on lines 36, 52, 63, and 71.

Suggested change
**[schemas.mdc](schemas.mdc)** - _Applies to: `_.schema.ts`\*
**[schemas.mdc](schemas.mdc)** - _Applies to: `_.schema.ts`\*_


- Zod schema patterns
- OpenAPI metadata
- Request/response validation
- Common schema patterns
- Type inference

**[controllers.mdc](controllers.mdc)** - _Applies to: `_.controller.ts`\*

- Controller patterns
- Request handling
- JWT payload access
- Error handling
- Response formatting

**[services.mdc](services.mdc)** - _Applies to: `_.service.ts`, `_.services.ts`_

- Service layer patterns
- Database operations
- Business logic
- Background jobs
- Error handling

**[models.mdc](models.mdc)** - _Applies to: `_.model.ts`\*

- Mongoose model patterns
- Schema definitions
- Indexes
- Hooks/middleware
- Virtual properties
- Instance and static methods

### Configuration & Environment

**[environment.mdc](environment.mdc)** - _Applies to: `.env_`, `config.service.ts`\*

- Environment variables
- Configuration management
- Required variables
- Adding new config
- Security best practices

**[email.mdc](email.mdc)** - _Applies to: `src/email/\*\*/_`, `email.queue.ts`\*

- Email system architecture
- React Email templates
- Mailgun integration
- Queue-based sending
- Common email patterns

### Development & Workflows

**[development.mdc](development.mdc)** - _Manual Application_

- Setup instructions
- Development commands
- Project structure
- Testing the API
- Debugging tips
- Common issues
- Production deployment

**[new-module.mdc](new-module.mdc)** - _Manual Application_

- Step-by-step guide for creating new modules
- Complete example with all files
- Registration steps
- Testing checklist

## How Rules Are Applied

### Automatic Application

Rules are automatically applied based on:

- **Always Apply**: Rules with `alwaysApply: true` in frontmatter
- **File Globs**: Rules with `globs` pattern matching current file
- **Description**: AI can fetch rules based on description

### Manual Application

Some rules (like `new-module.mdc` and `development.mdc`) are applied when:

- User explicitly references the task
- AI determines the rule is relevant to the current task

## Rule File Format

Each rule file uses Markdown with YAML frontmatter:

```markdown
---
alwaysApply: true|false
description: 'Rule description'
globs: '*.ts,*.tsx'
---

# Rule Content in Markdown

Rules can reference files using:
[filename.ext](mdc:path/to/filename.ext)
```

## Adding New Rules

To add a new rule:

1. Create a new `.mdc` file in this directory
2. Add YAML frontmatter with appropriate metadata
3. Write rule content in Markdown
4. Reference files using `[name](mdc:path)` format
5. Test with AI assistant

## Best Practices

- Keep rules focused and specific
- Use file globs to target specific file types
- Reference actual code files with `mdc:` links
- Provide examples and common patterns
- List common mistakes to avoid
- Keep rules up-to-date with codebase changes

## Rule Maintenance

When updating the codebase:

- Update relevant rules if patterns change
- Add new rules for new features/patterns
- Remove obsolete rules
- Keep examples current and working

## Questions?

If you need to modify or add rules, refer to the Cursor Rules documentation or ask the AI assistant for help.
79 changes: 79 additions & 0 deletions .cursor/rules/architecture.mdc
Original file line number Diff line number Diff line change
@@ -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 [magic-router.ts](mdc:src/openapi/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/openapi/zod-extend.ts)
- Use TypeScript strict mode - no `any` types

### Configuration

- All config in [config.service.ts](mdc:src/config/config.service.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 `/admin/queues`

### Error Handling

- Global error handler in [globalErrorHandler.ts](mdc:src/utils/globalErrorHandler.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
Loading