Execute reference architecture patterns for Cursor IDE projects. Triggers on "cursor architecture",
"cursor project structure", "cursor best practices", "cursor team setup". Use when working with cursor reference architecture functionality. Trigger with phrases like "cursor reference architecture", "cursor architecture", "cursor".
Reference architecture patterns for optimizing Cursor IDE project setup. Covers directory structure, rules organization, indexing strategy, and multi-project configuration for maximum AI effectiveness.
Project Layout for Cursor
A well-structured project makes AI features significantly more effective:
# .cursor/rules/project.mdc
---
description: "Core project context and conventions"
globs: ""
alwaysApply: true
---
# SaaS Dashboard Application
Stack: Next.js 15 (App Router), TypeScript 5.7, PostgreSQL 16, Prisma 6
Auth: NextAuth.js v5 with GitHub OAuth
Styling: Tailwind CSS 4
Testing: Vitest + Playwright
Package manager: pnpm
## Architecture Decisions
- Server Components by default, "use client" only when needed
- Repository pattern for database access
- Zod schemas for all external input validation
- Result types for error handling (never throw from services)
Layer 2: Security (Always-On)
# .cursor/rules/security.mdc
---
description: "Security constraints for all AI-generated code"
globs: ""
alwaysApply: true
---
# Security Requirements
- NEVER hardcode secrets, API keys, or passwords
- ALWAYS use parameterized queries (no string interpolation in SQL)
- ALWAYS validate and sanitize user input with Zod
- NEVER disable CORS, CSRF protection, or TLS verification
- Use httpOnly, secure, sameSite cookies for auth tokens
- Rate limit all public API endpoints
Layer 3: Technology-Specific (Glob-Scoped)
# .cursor/rules/react-components.mdc
---
description: "React component patterns"
globs: "src/components/**/*.tsx,app/**/*.tsx"
alwaysApply: false
---
# Component Standards
- Named exports only (no default exports)
- Props interface: {ComponentName}Props
- Use forwardRef for interactive components
- Colocate tests: Component.test.tsx next to Component.tsx
- Loading states: use Suspense boundaries, not conditional rendering
# .cursor/rules/api-routes.mdc
---
description: "API route handler patterns"
globs: "app/api/**/*.ts,src/api/**/*.ts"
alwaysApply: false
---
# API Route Standards
- All handlers wrapped in withAuth() middleware
- Input validation with Zod (parse body, params, query)
- Response shape: { data: T } or { error: string, code: string }
- HTTP status codes: 200 OK, 201 Created, 400 Bad Request, 401, 403, 404, 500
- Structured logging with requestId for traceability
# .cursor/rules/database.mdc
---
description: "Database access patterns"
globs: "src/db/**/*.ts,src/repositories/**/*.ts,prisma/**"
alwaysApply: false
---
# Database Conventions
- All queries via repository classes (never raw Prisma in API routes)
- Use transactions for multi-table writes
- Always include select/include to avoid over-fetching
- Pagination: cursor-based for lists, offset for admin tools
- Soft delete: use deletedAt timestamp, never hard delete user data
Layer 4: Manual Reference Rules
# .cursor/rules/deployment.mdc
---
description: "Deployment and infrastructure patterns"
globs: ""
alwaysApply: false
---
# Deployment
- Vercel for frontend, Railway for API
- Environment variables managed in Vercel/Railway dashboards
- Database migrations: `prisma migrate deploy` in CI
- Feature flags via LaunchDarkly
Reference manually with @Cursor Rules in Chat when discussing deployment.
