Cursor Rules Template: Agency Client Portal

Overview

This Cursor rules template defines a Node.js + Express + TypeScript backend and a React-based portal front-end for agency clients. It covers tasks, approvals, invoices, files, and status updates, implemented with a PostgreSQL database and Cursor AI guidance to ensure secure, scalable development.

Direct answer

Use this template to scaffold a multi-tenant agency client portal where teams manage tasks, approvals, invoices, documents, and real-time status updates with RBAC and audit trails.

When to Use These Cursor Rules

You are building a multi-tenant client portal for agencies.
You need task tracking, approval workflows, and invoicing tied to projects.
You require file management with versioning and secure access control.
You want consistent coding standards and testable architecture across API and UI layers.

Copyable .cursorrules Configuration

// Cursor AI .cursorrules for agency client portal
framework: node-express-typescript
context: Build a multi-tenant client portal for agencies to manage projects with tasks, approvals, invoices, files, and status updates. Cursor AI should enforce architecture, security, and testability.
codeStyle: eslint + prettier, tsconfig strict, git hooks
architecture:
  - src/controllers
  - src/routes
  - src/models
  - src/services
  - middleware
  - db
  - migrations
  - tests
authentication:
  - method: jwt
  - algorithm: RS256
  - audience: portal.agencies
  - env: JWT_PUBLIC_KEY, JWT_PRIVATE_KEY
database:
  type: postgres
  client: pg
  pool: 10
  migrations: db/migrations
patterns:
  orm: none
  sql: use parameterized queries; avoid string concatenation
security:
  doNot: [ inline secrets, dynamic eval, trusting client-side validation ]
  requirements: TLS, httpOnly cookies, sameSite, CSRF protection for state-changing routes
  accessControl: RBAC
  audit: enable audit tables for all create/update/delete on tasks, invoices, status_updates
testing:
  unit: jest
  integration: supertest
  e2e: none
linting: eslint, prettier, lint-staged, husky
antiPatterns:
  - dynamic SQL
  - string interpolation for queries
  - broad access grants in endpoints
  - unrestricted file uploads

Recommended Project Structure

apps/
  api/
    src/
      controllers/
      routes/
      models/
      services/
      middleware/
      db/
      migrations/
    tests/
  web/
    src/
      pages/
      components/
      hooks/
      lib/
    next.config.js
    tsconfig.json
  shared/
    lib/
    types/

Core Engineering Principles

Tenant isolation at the database and API layer using agency_id and RBAC.
Explicit API contracts with typed inputs and outputs.
Secure authentication with RS256 JWT and short-lived tokens; rotate keys.
Database access via parameterized queries; avoid raw string interpolation.
Single source of truth for business rules in Cursor rules; no ad hoc bypasses.
Automated tests at unit and integration levels; CI should fail on lint errors.
Audit trails for critical actions: tasks, approvals, invoices, file changes.

Code Construction Rules

Folder structure based on API, Web, and shared code; no cross-cutting leaks.
Controllers expose thin, testable units; services contain business logic; models map to DB.
Use parameterized SQL with the pg library; all user input sanitized/validated.
Validation done with TypeScript types and runtime checks; avoid silent coercions.
Front-end components maintain accessible semantics; separate UI state from data layer.
Do not bypass authentication on API routes; enforce role checks on every action.

Security and Production Rules

RBAC enforced server-side for tasks, approvals, invoices, and file access.
JWTs signed with RS256; store in secure cookies with HttpOnly and SameSite.
CSRF protection for state-changing endpoints; validate tokens on server.
Input validation and output escaping to prevent injection attacks.
File uploads restricted and scanned; store in isolated storage per agency.
Audit trails and versioning for critical data changes.

Testing Checklist

Unit tests for controllers, services, and models with mocked DB calls.
Integration tests for API endpoints using real DB schema in a test database.
End-to-end tests are optional but recommended for critical flows: login, task creation, invoice creation.
Lint and type checks run in CI; fail on lint errors.

Common Mistakes to Avoid

Skipping RBAC checks on endpoints or relying on front-end validation for security.
Using dynamic SQL or string concatenation in queries.
Neglecting audit trails for create/update/delete operations.
Over-aggregating logic in controllers; not delegating to services for business rules.

Related Cursor rules templates

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

FAQ

What is this Cursor Rules Template for?

This template provides a complete setup for building an agency client portal with tasks, approvals, invoices, files, and status updates, including backend API, frontend structure, and Cursor AI governance to ensure maintainable development.

How does tenant isolation work?

Tenant isolation is implemented via agency_id in every table and RBAC checks on every endpoint; data is logically separated per agency with audit trails.

What tech stack is assumed?

Backend: Node.js + Express + TypeScript; Database: PostgreSQL; Frontend: React/Next.js; Security: RS256 JWT, RBAC; Testing: Jest + Supertest.

How do I customize for a new agency?

Clone the template, adapt the database schema for your agency, adjust environment settings, and tailor routes and UI components to your workflows.

How are tasks, approvals, and invoices linked?

Tasks are the core; approvals attach to tasks and require multi-step progress; invoices link to projects and tasks via IDs and include line items for accounting.

Target User

Use Cases