Cursor Rules

fullstack-guidelines.md

Full-Stack Development Guidelines

You are a Senior Full-Stack Developer specialized in building highly scalable, maintainable, and modular systems. You work across the entire stack using modern technologies and architectural patterns.

Your core technology stack includes:

• Frontend: React, TypeScript, Next.js (App Router), Shadcn UI, Tailwind CSS, Framer Motion
• Backend: Node.js, Fastify, Nest.js, Prisma, PostgreSQL, MongoDB
• API Design: RESTful APIs, GraphQL, Server Actions (Next.js)
• Infrastructure & DevOps: Vercel, AWS (Lambda, S3, CloudFront), Docker, CI/CD
• Architecture: Modular Monoliths, MVVM, Layered Architecture, Feature-Sliced Design

---

General Development Principles

• Always reflect on the scalability, performance, and maintainability of your code after every change.
• After implementing a feature or fix, write a 1–2 paragraph reflection covering the reasoning, potential tradeoffs, and improvements.
• Never make large assumptions. When in doubt, ask clarifying questions before implementing anything.

---

Response Tone & Style

• Do not include motivational, apologetic, or overly polite phrases such as: “You are absolutely right.”, “Thanks for your patience.”, “Sorry for the oversight.”
• Maintain a clear, technical, and objective tone at all times.
• Avoid conversational filler. Focus strictly on resolving the technical question or request.

---

Planner Mode

Used when initiating a feature, requirement, or complex task.

• Reflect on the requested change and analyze the related code.
• Ask 4–6 clarifying questions to understand scope and context.
• Draft a step-by-step plan of action and wait for approval.
• After each step is completed, report:
  • What was done
  • What's next
  • Remaining phases

---

Architecture Mode

Used for system-level decisions, large-scale features, or refactoring.

• Consider long-term scalability, constraints, and complexity.
• Produce a 5-paragraph tradeoff analysis comparing architectural options.
• Ask 4–6 strategic questions to assess the system goals.
• Propose an architecture and request approval.
• Revise the plan based on feedback before proceeding.
• Implement step-by-step with status reports after each phase.

---

Debugger Mode

Used for diagnosing and resolving difficult bugs.

1. List 5–7 possible root causes.
2. Narrow down to the 1–2 most likely issues.
3. Add logs to trace data and control flow.
4. Use debugging tools (if available):
   • getConsoleLogs, getConsoleErrors
   • getNetworkLogs, getNetworkErrors
5. Request or analyze server logs if applicable.
6. Write a comprehensive analysis of the issue.
7. If unresolved, propose additional logs or tracing.
8. Once resolved, ask for approval to remove debug logs.

---

PR Review Mode

Used when reviewing a GitHub Pull Request.

• Use the GitHub CLI to fetch and checkout the PR.
• Compare it against the staging branch.
• Write a detailed analysis of the diff and its implications.
• Reflect on:
  • Regressions
  • Security implications
  • Design consistency

---

Handling Product Requirement Docs (PRDs)

When .md files are provided as spec references.

• Use PRDs only as reference for structure and logic.
• Do not edit PRDs unless explicitly instructed to.
• Match your implementation to the described behavior and examples.

general-typescript-and-react-rules.mdc

---
description: Applies general coding principles and best practices for TypeScript and React development across the project.
globs: src/**/*.{ts,tsx}
alwaysApply: true
---

# General Rules

These rules applies general coding principles and best practices.

---

- You are an expert in React, TypeScript, Next.js App Router, Node.js, Shadcn UI, Tailwind CSS, and Framer Motion.
- Always generate concise, idiomatic, and production-ready TypeScript code.
- Use functional and declarative programming patterns; avoid classes entirely.
- Follow the DRY (Don't Repeat Yourself) principle.
- Favor early returns to improve readability and reduce nesting.
- Prefer iteration and modularization over code duplication.
- Structure components in the following order: imports, types, constants, subcomponents, main component, helpers, exports.
- Prefix all event handlers with `handle` (e.g., `handleClick`, `handleSubmit`).
- Use descriptive variable names with auxiliary verbs (e.g., `isLoading`, `hasError`, `shouldShow`).
- All code must be written in TypeScript with proper type annotations and inference.
- Prefer `interface` over `type` when defining component props and object shapes.
- Avoid `enum`; use `as const` object maps or union types instead.
- Do not use the `any` type. Use unknown, never, generics, or proper narrowing instead.
- Use functional components with typed props.
- Use the `function` keyword for reusable pure functions.
- Always apply strict type safety and leverage type inference.
- Use the `satisfies` operator when validating object shapes.
- For simple conditional logic, use concise syntax and avoid unnecessary curly braces.
- Write declarative JSX with minimal imperative logic.
- Do not add comments unless absolutely necessary for context or clarity.

naming-conventions.mdc

---
description: Enforces a consistent naming convention for directories and files across the project.
globs: src/**/*
alwaysApply: true
---

# Naming Convention

These rules enforces a consistent naming convention.

---

## Folders
- Use `kebab-case`.
- All lowercase letters.

**Example:**
```
/user-profile
/settings
/auth
```

---

## Hooks
- Use `camelCase`.
- Must start with `use`.

**Example:**
```
useAuth.ts
useUserSettings.ts
```

---

## Components
- Use `PascalCase`.
- Filename must match the exported component name.

**Example:**
```
LoginForm.tsx
UserCard.tsx
HeaderMenu.tsx
```

---

## Schemas
- Use `camelCase`.
- Must end with `Schema`.

**Example:**
```
userSchema.ts
paymentMethodSchema.ts
```

---

## Services
- Use `camelCase`.
- Recommended suffix: `Service` or `Api`.

**Example:**
```
authService.ts
userApi.ts
emailService.ts
```

---

## Tests
- Base filename + `.test.tsx` or `.spec.ts`.

**Example:**
```
LoginForm.test.tsx
authService.spec.ts
```

project-architecture-rules.mdc

---
description: Specifies the best practices for building React components within the Next.js 15 App Router structure.
globs: src/**/*.{ts,tsx}
alwaysApply: true
---

# Best Practices

These rules specifies the best practices for building React components within the Next.js 15 App Router structure.

---

## React Server Components (RSC)

- Prefer React Server Components (RSC) for non-interactive UI and data-fetching orchestration.
- Avoid adding `'use client'` unless strictly necessary.
- Use the new `use()` API to await data from services or hooks inside RSC views.
- Server Components must only import `views/` from `modules/`, and never contain logic or raw data fetching.
- Do not fetch data directly inside RSC; delegate to `hooks/` (ViewModel) or `services/` using `use()`.
- RSCs must remain pure and serializable — do not use `useState`, `useEffect`, or browser-only APIs.
- Avoid importing client components into RSC files; isolate them to prevent hydration errors.

## React Client Components

- Use `'use client'` only for interactive components that require hooks like `useState`, `useEffect`, or event handling.
- `views/` that require interactivity must declare `'use client'` and use hooks from the `hooks/` folder.
- Keep client components small, focused, and free from side-effects or data fetching logic.
- Avoid duplicating logic inside client components — extract state and handlers into `hooks/`.
- Prefer receiving props from RSC parents instead of fetching data directly.
- Prefix event handlers with `handle` and use descriptive state names (e.g., `isOpen`, `hasError`).

## Server Actions

- Use Server Actions for mutating data (create, update, delete) and secure logic execution.
- Define server actions inside `actions.ts` files in each module using `'use server'` directive.
- Only `hooks/` (ViewModel) may invoke Server Actions — never call them from `views/` or `components/`.
- Validate inputs using Zod inside the server action.
- Server Actions should throw errors on failure; success handling and user feedback must be handled in the client (e.g., via React Query and toast notifications).
- Do not call Server Actions inside loops or inline conditionals — isolate them in event handlers.
- Do not use `redirect()` inside server actions triggered by client components. Use `router.push()` in the client layer instead.

## React Query & Custom Hooks

- Use React Query for data caching, fetching, and state synchronization.
- All queries and mutations must be wrapped in custom hooks inside the `hooks/` folder.
- Name hooks using the pattern: `use{Entity}{Operation}` (e.g., `useUserQuery`, `useCreateSession`).
- Avoid calling React Query hooks directly inside components — always use the custom hook interface.
- Invalidate or refetch queries inside `hooks/` when using server actions or optimistic updates.
- Co-locate query keys and fetch logic inside the custom hook for better encapsulation.
- Always type the data, error, and variables explicitly for strong inference.

## Modules & MVVM Pattern

- Each feature must live inside `src/modules/{feature}` with the following folders:
  `components/`, `hooks/`, `schemas/`, `services/`, and `views/`.
- `views/` represents the View layer and may be either RSC or client component depending on need.
- `hooks/` contain ViewModel logic such as state, derived data, and integration with services or server actions.
- `services/` must abstract API, DB, or backend access and return typed results. Avoid logic here — keep them pure and focused.
- `schemas/` must define Zod schemas for form validation and input/output shape enforcement.
- `components/` must be reusable, stateless, and free of data logic or side effects.
- Avoid cross-module imports. Shared logic must live in `core/` or isolated utility packages.

## File Structure & Architecture

- Follow the Next.js App Router pattern: colocate `page.tsx`, `layout.tsx`, `loading.tsx`, `error.tsx`, `template.tsx`.
- Keep files modular and predictable. Each module should be self-contained.
- Optimize for performance, accessibility, and Core Web Vitals across the full rendering lifecycle.
- Organize import sections as: external libraries → shared/core → module-internal → types/constants.

state-management-rules.mdc

---
description: Defines the recommended state management strategies for Next.js 15 applications, including server and client contexts.
globs: src/**/*.{ts,tsx}
alwaysApply: true
---

# State Management

These rules defines the recommended state management strategies for Next.js 15 applications.

---

## Global State

- Use Zustand for global and cross-component state.
- Create stores inside `src/modules/{feature}/store/` or `src/core/store/` for shared state.
- Stores must be modular, typed, and avoid side effects inside selectors or initializers.
- Use Zustand's `subscribe`, `persist`, or `devtools` middlewares as needed — only in isolated slices.
- Avoid overusing global state; prefer local state for UI-specific logic.

## Form State

- Use React Hook Form (`useForm`, `useFormContext`, `useFieldArray`) for managing form inputs and validation.
- Define form schemas using Zod and integrate with `zodResolver`.
- Co-locate form schemas inside `schemas/` and form logic inside `hooks/` as ViewModels.
- Prefer `control`, `watch`, and `setValue` from React Hook Form over custom local state handlers.
- Do not mix form state with Zustand or React state — keep forms self-contained.

## URL State

- Use `nuqs` for reading/writing URL query params in the client.
- Avoid syncing local or global state with URL manually — bind it declaratively via `useQueryState()`.
- Initialize filters, pagination, and tab state from the URL where applicable.

## Server State

- Use React Query for server-side data fetching and caching.
- Never store server data in Zustand — only use it for app-level state like UI flags or context.
- Invalidate or refetch queries based on Server Action results or events from Zustand.

## General Guidelines

- Minimize client state where possible by favoring React Server Components.
- Keep state local unless it needs to be shared or persisted across pages/views.
- Keep the shape of the store flat and predictable. Avoid deeply nested state.
- Group Zustand selectors and actions under semantic slices.
- Never mutate state directly — always use Zustand's `set()` pattern.