Cursor Rules Template: Node.js + PostgreSQL Loyalty SaaS

Overview

Cursor rules configuration for building a loyalty and rewards SaaS targets retail brands with points, tiers, referrals, and analytics. This template covers a Node.js + PostgreSQL stack with TypeORM and a REST or GraphQL API pattern. It enables multi-tenant loyalty programs, configurable point accruals, tier progression, referral incentives, and analytics dashboards. The Cursor rules template provides a concrete, copyable .cursorrules block you can paste into your project root to enforce consistent engineering practices while guiding the AI on how to operate within this stack.

When to Use These Cursor Rules

Starting a loyalty SaaS for multiple retail brands with isolated tenants.
Enforcing a points-based earning and redemption model across apps and web stores.
Defining tier rules, expiry, and promotion-driven bonuses.
Integrating referrals and partner campaigns with analytics events.
Ensuring safe AI-assisted development with strict security and data access patterns.

Copyable .cursorrules Configuration

.cursorrules
# Cursor AI rules for a Node.js + PostgreSQL loyalty SaaS
# Framework Role & Context
FrameworkRoleAndContext:
  - Role: Backend Engineer for a loyalty & rewards SaaS serving retail brands
  - Context: Build APIs in Node.js (TypeScript) with PostgreSQL and TypeORM; multi-tenant loyalty programs with points, tiers, and referrals; analytics-driven dashboards

# Code Style and Style Guides
CodeStyleAndGuides:
  Language: TypeScript
  StyleGuide: Airbnb + Prettier
  Linting: ESLint
  Formatting: Prettier
  NamingConventions: camelCase for variables, PascalCase for classes

# Architecture & Directory Rules
ArchitectureAndDirectoryRules:
  ProjectRoot: project-root
  Directories:
    - src/api
    - src/db
    - src/services
    - src/entities
    - src/migrations
    - src/analytics
  API Pattern: NestJS-style modules or Express routers
  ORM: TypeORM
  Migrations: TypeORM migrations under src/db/migrations

# Authentication & Security Rules
AuthenticationAndSecurity:
  AuthStrategy: JWT HS256 with refresh tokens in httpOnly cookies
  SecretsFrom: ENV vars, Secret Manager
  PasswordHashing: bcrypt with 12 rounds
  TokenRotation: true
  Session: Stateless API surface with rotation checks

# Database and ORM patterns
DatabaseAndORM:
  Tables:
    - users
    - loyalty_accounts
    - points_transactions
    - tiers
    - referrals
    - redemptions
    - analytics_events
  Relations: OneToMany, ManyToOne, ManyToMany as appropriate
  Queries: Parameterized; avoid string concatenation
  SeedMigrations: Seed initial tiers and sample data for a multi-tenant setup

# Testing & Linting Workflows
TestingAndLintingWorkflows:
  UnitTests: Jest with ts-jest
  IntegrationTests: Supertest
  E2ETests: Cypress (optional)
  CI: GitHub Actions; caching; lint & test on push
  CoverageThreshold: 80%

# Prohibited Actions and Anti-patterns for the AI
ProhibitedActionsAndAntiPatterns:
  - Do not embed secrets in code or environment files checked in
  - Do not bypass DI container; use service patterns
  - Do not concatenate SQL strings; use parameterized queries
  - Do not access third-party endpoints without validation
  - Do not skip input validation or data sanitization

Recommended Project Structure

project-root/
  src/
    api/
      loyalty/
        controllers/
        services/
        dtos/
        entities/
        repositories/
    db/
      migrations/
      entities/
    analytics/
    config/
    tests/
  .env.example
  package.json
  tsconfig.json

Core Engineering Principles

Explicit types and strong typing across API, services, and DB layers.
Single responsibility and clear boundaries between modules (API, domain, data access, analytics).
Defensive programming: input validation, schema enforcement, and robust error handling.
Idempotent and auditable operations for points, tiers, and referrals.
Testability: unit, integration, and end-to-end coverage with clear seed data.
Secure by default: secrets management, scoped access, and minimal surface area.

Code Construction Rules

Use DTOs for all request inputs and validate with class-validator; reject unknown fields.
Define TypeORM entities with explicit relations and cascade rules; avoid circular cascades.
Implement repository pattern for data access; write migrations for schema changes.
All business logic in services; controllers should only orchestrate requests and responses.
Use parameterized queries and query builders; never interpolate strings into SQL.
All sensitive operations require authorization checks and tenant scoping.
Keep configuration in environment variables; use 12-factor app conventions.

Security and Production Rules

Authenticate with JWTs; rotate refresh tokens; store in httpOnly cookies.
Enforce rate limiting and IP-based throttling on write endpoints.
Encrypt sensitive data at rest where feasible; use column encryption for critical fields.
Validate all external inputs; sanitize and normalize data before persistence.
Audit trails for points, redemptions, and referrals; log non-sensitive events with correlation IDs.

Testing Checklist

Unit tests for all services and validators; mock DB interactions.
Integration tests for points accrual, tier progression, and referral flows against a test database.
End-to-end tests for loyalty checkout and redemption paths (optional integration).
CI checks: lint, type-check, unit tests, integration tests; test coverage >= 80%.
Security tests: basic fuzz tests for input validation and rate-limit enforcement.

Common Mistakes to Avoid

Hardcoding tenant IDs or secrets in code; always use environment/config.
Skipping input validation; allow only defined attributes.
Using non-parameterized queries or dynamic SQL without sanitization.
Overcomplicating the domain layer; prefer clear domain services and DTOs.
Neglecting migrations and relying on ad-hoc schema changes in production.

Related Cursor rules templates

Explore adjacent Cursor rules templates for similar stacks, workflows, and production constraints.

FAQ

What is the purpose of this Cursor rules template?

It provides a ready-to-paste, stack-specific set of Cursor AI guidance for building a Node.js + PostgreSQL loyalty SaaS, including code style, architecture, security, testing, and anti-patterns to keep AI-assisted development safe and predictable.

Which stack does this template cover?

The template targets a Node.js (TypeScript) backend with PostgreSQL using TypeORM, suitable for multi-tenant loyalty programs with points, tiers, referrals, and analytics dashboards.

How do I use the .cursorrules block?

Copy the entire code block under Copyable .cursorrules Configuration and place it at the project root or alongside your Cursor AI workflow to enforce the rules for your repository.

Can I customize for different retail brands?

Yes. The template outlines multi-tenant patterns, per-tenant configuration, and data isolation, so you can adapt the rules for each brand while maintaining a shared codebase.

What are the recommended testing approaches?

Use unit tests for services, integration tests for data access and domain boundaries, and optional end-to-end tests for critical customer journeys; enforce a minimum coverage threshold in CI.

Target User

Use Cases