Sharkitect Solutions Claude Code Plugins Plus Skills Cursor Reference Architecture

Cursor Reference Architecture

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:

my-project/
├── .cursor/
│   └── rules/
│       ├── project.mdc          # alwaysApply: true (stack, conventions)
│       ├── security.mdc         # alwaysApply: true (security constraints)
│       ├── typescript.mdc       # globs: "**/*.ts,**/*.tsx"
│       ├── api-routes.mdc       # globs: "src/api/**/*.ts"
│       ├── database.mdc         # globs: "src/db/**/*.ts,prisma/**"
│       └── testing.mdc          # globs: "**/*.test.ts,**/*.spec.ts"
├── .cursorignore                # Exclude from AI + indexing
├── .cursorindexingignore        # Exclude from indexing only
├── .gitignore
├── src/
│   ├── api/                     # API routes
│   ├── services/                # Business logic
│   ├── db/                      # Database layer
│   ├── types/                   # Shared TypeScript types
│   ├── utils/                   # Utility functions
│   └── components/              # UI components
├── tests/
├── prisma/
├── docs/                        # Architecture docs (good for @Docs)
└── package.json

Why This Structure Helps Cursor

1. Glob patterns work predictably: src/api/**/*.ts cleanly scopes API rules
2. @Files references are intuitive: @src/types/user.ts is discoverable
3. Indexing is focused: clear separation of code vs build output vs data
4. Rules inheritance: project-level always-on + directory-scoped rules

Rules Architecture

Layer 1: Always-On Global Rules

# .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.

Indexing Strategy

Optimized .cursorignore

# Build output
dist/
build/
.next/
out/
.vercel/
.turbo/
coverage/

# Dependencies
node_modules/
.pnpm-store/

# Generated
*.min.js
*.min.css
*.d.ts.map
*.tsbuildinfo
pnpm-lock.yaml

# Data / Assets
*.csv
*.sql
*.sqlite
*.png
*.jpg
*.gif
*.svg
*.ico
*.woff
*.woff2
*.ttf

# Environment
.env*

# IDE
.vscode/
.idea/

.cursorindexingignore for Large References

# Not indexed, but accessible via @Files
docs/api-spec.yaml
tests/fixtures/
scripts/migration-data/

Monorepo Architecture

Turborepo / pnpm Workspaces

monorepo/
├── .cursor/
│   └── rules/
│       ├── monorepo.mdc         # alwaysApply: true (shared conventions)
│       ├── shared-types.mdc     # globs: "packages/shared/**"
│       ├── api.mdc              # globs: "apps/api/**"
│       └── web.mdc              # globs: "apps/web/**"
├── .cursorignore
├── apps/
│   ├── api/
│   ├── web/
│   └── admin/
├── packages/
│   ├── shared/
│   ├── ui/
│   └── config/
├── turbo.json
└── pnpm-workspace.yaml

Key rule for monorepos:

# .cursor/rules/monorepo.mdc
---
description: "Monorepo import conventions"
globs: ""
alwaysApply: true
---
# Import Conventions
- Import shared types: import { User } from '@myorg/shared'
- Import UI components: import { Button } from '@myorg/ui'
- NEVER use relative paths across package boundaries
- Each package has its own tsconfig.json extending root

Configuration Files Summary

Enterprise Considerations

• Rules as code: Treat .cursor/rules/ changes like infrastructure changes -- require PR review
• Template repository: Create a company template repo with standard rules, ignore files, and onboarding docs
• Compliance mapping: Map security rules to specific compliance controls (SOC 2 CC6.1, etc.)
• Architecture documentation: Keep docs/ directory indexed so AI can reference architecture decisions via @Docs

Resources

• Cursor Rules Documentation
• Codebase Indexing
• Ignore Files

Source: sharkitect-solutions/claude-code-plugins-plus-skills — distributed by TomeVault.