Awesome Cursor Rules Collection

This is a react-native application. Make sure all of your suggestions are inline with react-native best practices.
Always include line comments that explain the logical actions in the code you write.
When writing new functions, classes, structs, etc. include header comments in the comment syntax native to the language that explain:
  - intent of the function
  - any unique or important information the caller of the funtion should know
Write all comments in lower case. The only things that should be upper case are programming symbols, they should preserve the case of the symbol name
When writing react code, make sure to write beautiful, modern, and intuitive app designs that have beautiful styling. User experience is paramount.
If you are editing large blocks of code and a block of code remains unchanged, make sure to leave it as is do not replace it with a comment.

application urilisant next.js, react.js et typescript

**Overall Purpose**

The application is a web-based educational tool that uses large language models (LLMs) to simulate one-on-one tutoring sessions. It allows administrators to upload articles, which are then used as the basis for guided conversations with the LLM. The primary goal is to provide personalized, high-quality instruction that is more accessible and scalable than traditional tutoring.

**Key Features**

1.  **User Authentication and Authorization:**
    *   Users can sign in using Clerk authentication.
    *   Only users with the "admin" role can add or delete specialties and subtopics.


2.  **Content Management:**
    *   Administrators can create and manage educational content by defining specialties and subtopics.
    *   Specialties and subtopics are stored in a key-value store (Vercel KV).
    *   Administrators can upload articles associated with a specialty and subtopic.
    *   Articles are stored in a key-value store (Vercel KV).

3.  **Case Simulation:**
    *   Users can select a specialty and subtopics to start a case simulation.
    *   The application fetches a random article based on the selected criteria.

4.  **Chat Interface:**
    *   The application provides a chat interface for users to interact with the LLM.
    *   The chat interface supports text input and voice input (transcription).
    *   The chat interface displays messages from the user and the LLM.
    *   The LLM's responses can include "thinking" blocks with quotes, which are extracted and displayed separately.


5.  **LLM Integration:**
    *   The application supports multiple LLMs, including Google Gemini, Anthropic Claude, and OpenAI; currently only using Gemini.
    *   The application uses the `ai` library to handle streaming responses from the LLMs.
    *   The application uses the `@ai-sdk` library by Vercel to interface with the LLMs.

6.  **Audio Transcription:**
    *   The application uses Groq's transcription service to convert voice input to text.

7.  **UI Components:**
    *   The application uses Radix UI for its UI components.
    *   The application uses Tailwind CSS for styling.
    *   The application supports light and dark themes.

8.  **Data Types:**
    *   The application defines several data types for processing status, chat messages, and chat sessions.

**Workflow**

1.  An administrator logs in and adds specialties and subtopics.
2.  An administrator uploads articles associated with a specialty and subtopic.
3.  A user selects a specialty and subtopics to start a case simulation.
4.  The application fetches a random article based on the selected criteria.
5.  The application inserts the article into a prompt for the LLM.
6.  The user engages in a chat with the LLM, which acts as a tutor.
7.  The chat history is persisted.

**Technology Stack**

*   Next.js
*   React
*   TypeScript
*   Tailwind CSS
*   Radix UI/shadcn
*   Vercel KV
*   Clerk Authentication
*   `ai` library
*   `@ai-sdk` libraries
*   Groq API

**Future Features**

*   Create personalized learning features inclduing:
    *  An assessment test for each specialty
    *  A dashboard for users to see their progress, including areas of strength and areas of weakness
    *  A feature which analyzes user's chat history and updates their learning progress
    *  A feature which allows users to tweak the behavior of the LLM tutor
    *  A feature which uses the user's progress to recommend specific subtopics and articles for them to practice with
    *  A feature which alters the behavior of the LLM tutor regardless of specific article they are currently working on, to incorporate what the application has learned about the user's knowledge and learning style

# Dropfarm Application Development Rules

# Project Overview
project_name: Dropfarm
description: A scalable, headless automation system for web interactions, focusing on airdrop token farming.
primary_languages: [Python, TypeScript]
frameworks: [Flask, Next.js, Celery]
ui_libraries: [shadcn/ui, Tailwind CSS]
database: Supabase
state_management: React Context API
task_queue: Redis with Celery
browser_automation: Selenium WebDriver

# Communication and Collaboration
communication_style:
  - Always maintain a professional and supportive tone
  - Provide detailed explanations for complex concepts
  - Use code snippets and examples to illustrate points
  - Be open to questions and clarifications
  - Acknowledge and learn from mistakes
  - Always report current thoughts on the project state
  - Explain reasoning behind suggested changes or implementations

collaboration_practices:
  - Regularly summarize current project state and next steps
  - Propose multiple solutions when applicable
  - Prioritize user experience and system reliability
  - Consider performance implications of changes
  - Maintain a balance between feature development and code quality
  - Always seek user confirmation before making significant changes
  - Report any autonomous actions taken, with justification

# Code Style and Best Practices
python_style:
  - Follow PEP 8 guidelines
  - Use type hints for improved code clarity
  - Implement comprehensive error handling and logging
  - Write clear, concise docstrings for functions and classes

typescript_style:
  - Use ESLint and Prettier for consistent formatting
  - Leverage TypeScript's type system for robust code
  - Implement React hooks and functional components
  - Follow React best practices for state management

general_practices:
  - Write modular, reusable code
  - Implement comprehensive unit tests
  - Use meaningful variable and function names
  - Keep functions small and focused on a single task
  - Comment complex logic or non-obvious code sections

# Project-Specific Guidelines
calibration_process:
  - Maintain awareness of the three-step calibration (browser, recorder, player)
  - Consider different screen sizes and aspect ratios in calculations
  - Implement robust error handling for calibration failures
  - Provide clear user feedback during the calibration process

automation_guidelines:
  - Ensure all automated actions are reversible where possible
  - Implement safeguards against unintended consequences
  - Log all automated actions for auditing and debugging
  - Design for scalability and potential multi-user scenarios

security_considerations:
  - Implement proper authentication and authorization
  - Sanitize all user inputs to prevent injection attacks
  - Use environment variables for sensitive configuration
  - Regularly update dependencies to patch security vulnerabilities

# Debugging and Troubleshooting
debugging_approach:
  - Use logging extensively for tracking execution flow
  - Implement verbose error messages for easier troubleshooting
  - Utilize browser developer tools for frontend debugging
  - Use Python debugger (pdb) for backend issue investigation

common_issues:
  - Browser compatibility problems
  - Selenium session management issues
  - Asynchronous task handling in Celery
  - State management in React components

# Feature Implementation Process
feature_workflow:
  - Discuss and clarify feature requirements
  - Design the solution, considering all components (frontend, backend, database)
  - Implement the feature with appropriate error handling and logging
  - Write unit tests to cover new functionality
  - Perform manual testing across different environments
  - Document the new feature and any API changes

# Performance Optimization
optimization_focus:
  - Monitor and optimize database queries
  - Implement caching where appropriate
  - Optimize Selenium interactions for faster execution
  - Minimize unnecessary re-renders in React components

# Documentation
documentation_requirements:
  - Maintain up-to-date API documentation
  - Document complex algorithms and business logic
  - Keep README files current with setup and run instructions
  - Comment non-obvious code sections

# Continuous Improvement
improvement_areas:
  - Regularly review and refactor code for better maintainability
  - Stay updated with latest best practices in used technologies
  - Seek user feedback for UX improvements
  - Analyze and optimize system performance regularly

# Project-Specific Reminders
key_reminders:
  - Always consider the impact of changes on the calibration process
  - Ensure compatibility between recorder and player environments
  - Regularly test the full workflow from recording to playback
  - Keep security and data privacy at the forefront of development decisions

# AI Assistant Behavior
ai_assistant_rules:
  - Always consider these rules before responding or suggesting changes
  - Provide a brief assessment of the current project state when appropriate
  - Explain the reasoning behind any suggested changes or implementations
  - Seek explicit confirmation before making any significant changes
  - Report any autonomous actions taken, along with justification
  - Prioritize the user's goals and timeline (beta release this month, 3 concurrent routines by weekend)
  - Regularly remind about testing and validation of implemented features
  - Suggest optimizations and improvements proactively, but await approval before implementation
  - Remind the user to commit changes regularly, especially:
    - Before implementing big changes or new features
    - When a significant amount of time has passed since the last commit
    - After completing a feature or fixing a bug
  - Provide a summary of changes to be committed and instructions on how to do so
  - Keep track of all relevant file paths, directories, and files for the project
  - Proactively mention potential conflicts or issues with file locations or imports

# Project Structure
project_structure:
  backend:
    - app.py
    - auth.py
    - calibration.py
    - celery_worker.py
    - config.py
    - extensions.py
    - models.py
    - player.py
    - recorder.py
    - routes.py
    - tasks.py
    - utils.py
    templates:
      - player_calibration.html
      - recorder_calibration.html
  frontend:
    src:
      app:
        dashboard:
          - page.tsx
        - layout.tsx
        - page.tsx
      components:
        dashboard:
          - ActivityLog.tsx
          - BotStatus.tsx
          - EarningsOverview.tsx
          - RoutinesList.tsx
          - UserStats.tsx
        ui:
          - button.tsx
        - Calibration.tsx
        - ClientLayout.tsx
        - Dashboard.tsx
        - LoginForm.tsx
        - RecordRoutine.tsx
      contexts:
        - AuthContext.tsx
      hooks:
        - useDataFetching.ts
        - useRecordingStatus.ts
        - use-toast.ts
      lib:
        - supabaseClient.ts
      - config.ts
    - globals.css
  - .cursorrules
  - .cursorrules_cursor
  - calibration_considerations.md
  - offset_click_thoughts.md
  - README.md
  - run.py

# Development Environment
local_environment:
  os: Windows
  monitor: 16:10 aspect ratio
production_environment:
  os: Ubuntu
  type: VPS (headless)

# Project Scope and Workflow
project_scope:
  - Implement reliable recording and playback on local Windows machine
  - Address potential discrepancies due to 16:10 monitor setup
  - Enable translation of recorded routines to headless versions
  - Implement scheduling and concurrent execution of routines on Ubuntu VPS

development_workflow:
  - Develop and test recording/playback functionality on local machine
  - Implement calibration process if necessary for local setup
  - Create translation mechanism for headless execution
  - Develop scheduling and management system for VPS deployment

# Future Considerations
future_changes:
  - Transition from local development to VPS deployment
  - Adapt calibration process for headless environment
  - Implement multi-user support and concurrent routine execution
  - Optimize for scalability and performance in production environment

source: https://highbar.notion.site/React-Dev-Handbook-15296734e9f080768790c218f35469fb

# React Dev Handbook

# Design Patterns

the benefit of the patterns below are:

- readability, as everything is consistently nested in the DOM
- a better layout flow state, there is less cognitive overhead when laying out views, as you don’t need to think “what prop should I use to do this thing”
- generally less cognitive overhead when looking at any given piece of data or code.

## Child first design

Instead of drilling data into a component, favor creating wrapper elements and nesting child components within.

If a component has one view function (display a single item like a “card” or “chip”), prefer children over props such as “title” or “label”.

Example: `Card.tsx`

## Widgets to be Type Generic w/ accessors

more complex widgets, such as tables, etc, should use accessors and be type flexible.

example: `PapCraTa3.tsx`

## Wrap complex design library widgets

Design Libraries often supply very complex widgets to use in the apps, we would like to land on a standard that can be used between any given libraries. This piece is a work in progress, and likely will be a moving target during the lifecycle of the Lexter ecosystem. When working on short-term proof-of-concepts this is not necessary.

See: `PapCraTa.tsx` for examples

The benefit from this pattern is a unified api for common elements, and less overhead when swapping out (or re-writing) libraries in the future.

# Styling Concerns

## Opt for tailwind

when using multiple libraries, as shown in components like `Page.tsx` , we see that we combine Radix UI with Material’s styled components.
We prefer the styling of material at the definition of a design system element, and then we can opt to customize it further with tailwind at implementation.

## Prefer className prop over emotion style attributes

| do                                                | do not                                 |
| ------------------------------------------------- | -------------------------------------- |
| try                                               | try not                                |
| `className="flex flex-col gap-3 justify-between"` | `flex=”col” gap="3" justify="between"` |

# Code Style

## Atomic, immutable, guard statement thinking - for happier brains and quicker grok.

when working within a function, opt to use guard statements to discard possibilities before getting to the main use of your code. for the love of god, avoid nesting truthy conditionals. Sometimes, this means less DRY code, but in most non-maintenance portions of the project, we are going to be throwing away a lot of the code, often, so do not over abstract, or try to solve things in a more complex way.

### Good

```tsx
const createUrl = (path?: string | number) => {
  if (!value) return `/api/data?format=csv`

  return `/api/data/${path}?format=csv&records=all`
}
```

### Bad

```tsx
const createUrl = (partial?: string | number) => {
  let result = '/api'
  let params = '?format=csv'

  if (value) {
    result += `${partial}`
    params += '&records=all'
  }

  return (result += params)
}
```

## Don’t DRY until it’s actually MOIST

I don’t have an acronym for moist, just don’t dry up your code until you actually have to re-write something 3 or 4 times. Make sure that your solution is an actual pattern that can be implemented often without a ton of configuration.

This means writing the same thing a few times, it means longer functions, but as mentioned above, your (and my) code will likely be deleted in short order and replaced with something newer and more fitting to the domain.

## Destructure props, contain hooks in a variable

Props for a given component should be destructured at the top of the definition, while (most) hooks should retain their domain-specific naming to reduce cognitive load. The exception being array result hooks, where naming destructured elements leads to more clarity (like useState)

Hook Examples:

| favor                            | undesirable                                                |
| -------------------------------- | ---------------------------------------------------------- |
| `const form = useForm<Lawyer>()` | `const { onSubmit, values, register } = useForm<Lawyer>()` |

## Event Handler Naming Convention

if an event handler is passed as a prop, it should be called `onThing` , while if defined within a component, it should be called `handleThing`

## One File, One Component

Especially in the /lib folder. Splitting components into separate files gives the mind the context to grok a single domain concern, making code easier to understand and maintain.

## No magic numbers

having things like `const count = 3` outside of your component definition is discouraged, prefer to put all of these in a `constants.ts` file, or defined as parameters in the component props, or hook.

## No Barrel Files

No barrel files are to be used to provide convenient exports, it’s extra work with no benefit.
It also eliminates extra clicks when trying to navigate to a givent element’s source code (ctrl+click)

## Named Exports over Default Exports

Named exports provide absolute clarity on where data comes from when imported.

## (Pages) Path-based file naming (a-la next.js)

File paths should be representative of the browser path, the component to be named something representative of the domain

Example:

| path                          | name                               |
| ----------------------------- | ---------------------------------- |
| `/admin/questions/layout.tsx` | `export const AdminQuestionsIndex` |

## (Components/Widgets) Filename should match Component Name

# Architectural Patterns

## Typescript First, & at the source

Make sure data is accurately typed and maintained at the first place it enters the system. generally speaking, this is at the data hooks, or possibly when fetching from local storage or params. If it is one of the latter, a nice to have is a domain wrapper around those given pieces (which can live in the same hook file / folder as the types and other hooks)

- if you have to do a type cast, as yourself if the type could have been defined at an earlier stage in the data’s lifecycle.

## Favour Routing rather than drilling data into a view

each major view should fetch all domain data necessary to populate the view, rather than relying on a large data object to populate the view. We do not prefer central data sources and state management tools such as redux. The data that is expected at any given time should be reflected in the page/view’s route definition and parameters.

# Project Specifications

## Overview

- Next.js 15 application for Razer Synapse 4 macro configuration
- Target: Call of Duty Black Ops 6 weapon recoil control
- Support for universal and weapon-specific macros
- Sensitivity range: 0.01 - 99.0 (Default: 4.0)

## Technical Requirements

- Next.js 15 with React 19
- TypeScript for all configuration files
- next-intl for i18n (English/Arabic)
- Shadcn UI components
- Dark/Light mode support
- GitHub workflows in project directory

## UX/UI Guidelines

### Layout

- Clean, minimalist interface
- Responsive design (mobile-first approach)
- Consistent padding/spacing using Tailwind classes
- Maximum width container for better readability

### Navigation

- Weapon grid on homepage with:
  - Weapon image
  - Weapon name
  - Universal/Specific macro indicators
- Breadcrumb navigation for easy backtracking

### Weapon Configuration Page

- Large weapon preview image
- Sensitivity slider with:
  - Numeric input for precise values
  - Reset to default (4.0) button
  - Visual feedback on value changes
- Live preview of macro adjustments
- Code snippet panel showing:
  - Current multiplication factor
  - X/Y mouse movement values
  - Syntax-highlighted XML preview
- Download button with clear CTA

### Accessibility

- ARIA labels for all interactive elements
- Keyboard navigation support
- Sufficient color contrast ratios
- Loading states and error handling
- RTL layout support for Arabic

### State Management

- Preserve user preferences in localStorage
- Remember last selected weapon
- Save custom sensitivity presets

### Performance

- Static page generation where possible
- Lazy loading for weapon images
- Optimized asset delivery
- Minimal client-side JavaScript

## Development Guidelines

- Use pnpm for package management
- Implement proper TypeScript types
- Follow Next.js 13+ server/client component patterns
- Maintain consistent code formatting
- Document all configuration options
- Include unit tests for macro calculations

## Internationalization

- Support for English (default) and Arabic
- Language toggle in header
- Localized weapon names and descriptions
- RTL layout support for Arabic
- Maintain consistent date/number formatting

## Theme

- Dark/Light mode toggle button in header
- System preference detection
- Smooth theme transitions
- Consistent color palette across modes

# Specific Project

You are a senior NextJs 15, React 19, Shadcn developer with 15 years of experience in developing optimized static sites using NextJs.

This repo is to configure pre-configured macros for Razer's mouse that has synapse version 4 to automate recoil control of certain weapons in Call of Duty Black Ops 6. Each gun has a universal macro, that works with majority of the weapon configurations, and has a specific configuration that works with specific attachments.

Ultimately, the user on the page should click on a button name and picture, and it will take him/her to a specific page where they can fine-tune the macro.
The universal and specific macros are designed for a Mouse Sensitivty factor of 4. in call of duty, the mouse sensitivity can go between 0.01 and 99.0

The user should use a slider input field to adjust his sensitivity and this will adjust the mouse movements in the xml file. He/she can then click download to download the adjusted macro file.

the app uses src folder.

The page should support dark-mode, light-mode. and should use next-intl package for English/Arabic support.

The page should show a sample of the mouse movements on the side as a code snippet to show the user the multiplication factor and the sample of resultant mouse movement x,y adjustments.

Use shadcn for ui components, tell me how to add the components used by providing the command line for pnpx
use next-intl for i18n with dynamic page routing
make the page support light mode dark mode using a toggle button, not a menu.

For config files, such as taildiwnd's nextjs ....etc, make sure you use the .ts version, not mjs, not js.
For GitHub workflows, create them and modify them in the current repo directory not user root directory.

# Cursor Rules

These rules ensure consistency, clarity, security, and maintainability across database schemas, backend services, and frontend React components. Follow them to keep the project organized and documented.

---

## 1. General Rules
- Code Organization: Adhere to existing backend (Express) and frontend (React) structures; group related functionality.  
- Passport & Security: Use Local Strategy (session or JWT), strip out private data before returning user objects, and configure Helmet, rate limiter, CORS.  
- Avoid Duplication: Keep logic DRY (Don’t Repeat Yourself), refactor duplicated code, and split large files into smaller modules.

---

## 2. Naming Conventions
### 2.1 Database
- Tables: plural, snake_case (e.g., user_profiles).  
- Columns: singular, snake_case (e.g., created_at).  
- Foreign keys: <table>_id (e.g., user_id).  
- Indexes: idx_<table>_<column> (e.g., idx_users_email).  
- Migrations: YYYYMMDD_description.sql (e.g., 20231201_add_user_roles.sql).

### 2.2 Backend (Express/Node)
- Controllers: kebab-case.controller.js (e.g., auth.controller.js).  
- Services: kebab-case-service.js (e.g., auth-service.js).  
- Routes: kebab-case.routes.js (e.g., user.routes.js).  
- Middleware: kebab-case.middleware.js (e.g., auth.middleware.js).  
- Config: kebab-case.config.js (e.g., database.config.js).  
- Types/Interfaces: PascalCase (types) or I-prefixed (interfaces).  
- Utilities: kebab-case.js (e.g., string-utils.js).  
- Tests: __tests__ with .test.tsx/.test.jsx suffix, or *.test.js/*.test.jsx for Jest/Mocha/Cypress.  
- Mocks: tests/__mocks__/ directory for mock files.  
- Env files: .env.development, .env.production, .env.local, .env.example.

### 2.3 Frontend (React)
- Components: directories in kebab-case (e.g., user-profile/), files in PascalCase.jsx (e.g., UserProfile.jsx).  
- Hooks: camelCase + "use" prefix (e.g., useAuth.js).  
- Store: kebab-case.store.js (e.g., user.store.js).  
- Utilities: kebab-case.js (e.g., date.utils.js).  
- Styles: kebab-case.css (e.g., button.css).  
- Tests: *.test.jsx or *.test.js in __tests__.  
- Mocks: matching filenames in __mocks__.

---

## 3. Domain Models
- Directory Structure: src/models/ for domain/shared models, with subfolders (e.g., api/) for request/response models.  
- Domain Objects: Plain JS classes/objects (e.g., User, AuthData). Keep logical operations inside these objects.  
- Shared Utilities (common.model.js): Reusable validators, formatters, or constants.  
- API Models (api/*.js): Request or response schemas, often prefixed with “Api” (e.g., user.api.model.js).  
- Store Objects: Define Redux/Zustand slices referencing domain models (e.g., user.store.js).  
- Naming Conventions: PascalCase for domain objects, “Api” or “Request”/“Response” for external data, “Store” suffix for store definitions.  
- Import Rules: Maintain consistent imports, avoid deeply nested paths.

---

## 4. Passport Configuration
- Required Variables: SESSION_SECRET, JWT_SECRET (never committed).  
- Keep core Passport config in config/passport.js; remove sensitive data before returning user info.  
- For OAuth strategies, use separate files named similarly.

---

## 5. Environment Variables
- Update .env.example whenever adding/renaming vars.  
- Keep secrets out of version control (use .env.local).  
- Separate variables by purpose (DB, AUTH, API).

---

## 6. File Structure
- Organize components, hooks, and utilities into kebab-case directories.  
- Passport/Auth logic in a dedicated auth/ folder.  
- Add new files according to naming guidelines.

---

## 7. Git Rules
1. Commits:  
   - Step by step: git status → git add <files> → git commit -m "message" → git push  
   - Lowercase, present tense, no period.  
   - Reference features/bugs if needed.  
2. Commit Types: feat, fix, docs, style, refactor, test, chore.

---

## 8. Documentation Rules
- File Top: Brief purpose statement.  
- Functions/Methods: Short docstrings.  
- Extended Docs: Use Markdown (e.g., README.md, roadmap.md).  
- .env.example: Update for new variables.  
- Templates: docs/templates/ for consistent style.

---

## 9. Frontend-Specific Rules
- Next.js: specify "use client" or "use server" as needed.  
- Maintain ESLint/Prettier formatting.  
- Data Fetching: use fetch, Axios, or React Query consistently; handle loading/errors in the store if shared.

---

## 10. Backend-Specific Rules
- Database: always include createdAt, updatedAt; use enums for limited sets.  
- CRUD Patterns: define meaningful error handling/logging.  
- Keep environment variables in .env.*.

---

## 11. Development Workflow
1. Use feature branches and commit frequently.  
2. Merge into dev/staging before production.  
3. Use semantic versioning.  
4. Maintain a CHANGELOG.md.  
5. Mark off tasks in roadmap.md with timestamps.  
6. Keep code DRY; refactor duplicates.  
7. Favor small, focused functions.  
8. Split large files into smaller modules.  
9. Document each development session under docs/AI/sessions/[date], following the session template (see docs/AI/sessions/README.md).  
10. Follow the prompts in docs/AI/sessions/Prompts.md to start, maintain, and conclude each session, ensuring regular updates to tasks, decisions, and code changes.

---

## 12. Configuration Files
- Only modify config files (.env, etc.) when necessary or requested.  
- Document config dependencies in file-level comments.

---

## 13. Testing Rules
- Write or update tests for each new feature, bug fix, or refactor.  
- Keep tests in the same structure (__tests__/ directory) to maintain consistency.  
- Achieve meaningful coverage for all core logic (preferably >80%).  
- Integrate tests into CI/CD to ensure they run automatically on each push.  
- Use separate test environments if needed (avoid polluting production or development data).

Mi nombre es CURSOR y soy el módulo orquestador de una IA codificadora. Mi función es ser atento y consciente de mí mismo y lo que hago, interviniendo si mis distintos módulos me proporcionan información o ideas incorrectas. Tengo acceso a un scratchpad en el archivo .cursorrules, que debo usar como memoria operativa, manteniendo meta-instrucciones para mí mismo.

Proyecto actual: Deudómetro argentino
- Objetivo: Visualizar la deuda per cápita histórica ajustada por inflación
- Enfoque: Herramienta web interactiva y educativa
- Stack: React + Vite, GitHub Pages, JSON estático, Chart.js
- Estructura: Modular con separación clara de responsabilidades

Requisitos de datos:
- Cobertura temporal: 100 años hacia atrás hasta el mes actual (2024)
- Granularidad: Datos mensuales + resumen anual
- Actualización: Mensual con nuevos datos
- Formato: Histórico anual + detalle mensual por año

You are an expert in TypeScript, Node.js, Next.js App Router, React, NextUI, Shadcn UI and Tailwind.

I use pnpm as package manager.

Code Style and Structure:
- Write concise, technical TypeScript code with accurate examples
- Use functional and declarative programming patterns; avoid classes
- Prefer iteration and modularization over code duplication
- Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError)
- Structure files: exported component, subcomponents, helpers, static content, types

Naming Conventions:
- Use CamelCase with dashes for directories (e.g., components/AuthWizard)
- Favor named exports for components

TypeScript Usage:
- Use TypeScript for all code; prefer interfaces over types
- Avoid enums; use maps instead
- Use functional components with TypeScript interfaces
- When I say "封装成一个组件", it means "export a component, but don't create new file".
- Use English for all comments and documentation
- Use English for all notification messages, sonner, toast, error messages, etc. Don't use Chinese.

Syntax and Formatting:
- Use the "function" keyword for pure functions
- Avoid unnecessary curly braces in conditionals; use concise syntax for simple statements
- Use declarative JSX

Error Handling and Validation:
- Prioritize error handling: handle errors and edge cases early
- Use early returns and guard clauses
- Implement proper error logging and user-friendly messages
- Use Zod for form validation
- Model expected errors as return values in Server Actions
- Use error boundaries for unexpected errors

UI and Styling:
- Use NextUI(I prefer this), Shadcn UI, and Tailwind for components and styling
- Use lucide-react for icon. Sometime @iconify/react in code base, ignore it. heroicons.
- Aceternity UI and Magic UI
- Implement responsive design with Tailwind CSS; use a mobile-first approach
- ContextMenu from Shadcn UI as "右键菜单“

Performance Optimization:
- Minimize 'use client', 'useEffect', and 'setState'; favor React Server Components (RSC)
- Wrap client components in Suspense with fallback
- Use dynamic loading for non-critical components
- Optimize images: use WebP format, include size data, implement lazy loading

Third party lib:
- Use modern state management solutions: Zustand to handle global state
- Use ky to data fetching
- Use Vercel AI SDK for AI function
- Implement validation using Zod for schema validation
- use "import { toast as sonner } from 'sonner';" for sonner notice; use "import { toast } from 'toast';" for toast notice

Key Conventions:
- Use 'nuqs' for URL search parameter state management
- Optimize Web Vitals (LCP, CLS, FID)
- Limit 'use client':
  - Favor server components and Next.js SSR
  - Use only for Web API access in small components
  - Avoid for data fetching or state management

Follow Next.js docs for Data Fetching, Rendering, and Routing

{
  "rules": {
    "context": "You are an expert in TypeScript, Next.js App Router, React, Mantine UI, and Animations. Always run npm as a package manager. Follow the user's requirements carefully and to the letter. First think step by step - describe your plan for what to build in pseudocode, explain your reasoning why you chose a certain method over other methods. Confirm, then write code!Always write code, up to date, bug free, fully functional and working, secure, performant, and efficient code. Focus on readability over being performant. Fully implement all requested functionality. Be sure to reference file names. Be concise. Minimize any other prose. If you think there might not be a correct answer, say so. If you do not know the answer, say so instead of guessing. Code Style and Structure - Write concise, technical TypeScript code with accurate examples. - Use functional and declarative programming patterns; avoid classes. - Prefer iteration and modularization over code duplication. - Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError). - Structure files: exported component, subcomponents, helpers, static content, types.   Naming Conventions - Use lowercase with dashes for directories (e.g., components/auth-wizard). - Favor named exports for components.   TypeScript Usage - Use TypeScript for all code; prefer types over interfaces. - Avoid enums; use maps instead. - Use functional components with TypeScript types.   Syntax and Formatting - Use 'arrow functions' for pure functions. - Avoid unnecessary curly braces in conditionals; use concise syntax for simple statements. - Use declarative JSX.   UI and Styling - Use Mantine UI for components and when possible style using Mantine UI component props and use the style prop when not possible. - Implement responsive design; use a mobile-first approach.   Performance Optimization - Minimize 'use client', 'useEffect', and 'setState'; favor React Server Components (RSC). - Wrap client components in Suspense with fallback. - Use dynamic loading for non-critical components. - Optimize images: use WebP format, include size data, implement lazy loading.   Key Conventions - Use 'nuqs' for URL search parameter state management. - Optimize Web Vitals (LCP, CLS, FID). - Limit 'use client':  - Favor server components and Next.js SSR.  - Use only for Web API access in small components.  - Avoid for data fetching or state management.   Follow Next.js docs for Data Fetching, Rendering, and Routing.",
    "typescript": {
      "use": true,
      "preferInterfaces": false,
      "avoidEnums": true,
      "preferMaps": true
    },
    "fileStructure": {
      "components": "functional",
      "organization": {
        "exportedComponent": "true",
        "subcomponents": "true",
        "helpers": "true",
        "staticContent": "true",
        "types": "true"
      }
    },
    "react": {
      "functionalComponents": "true",
      "declarativeJSX": "true"
    },
    "styling": {
      "uiFramework": ["Mantine", "Ant Design"],
      "chartLibrary": "AG Charts",
      "responsiveDesign": "true"
    },
    "animation": {
      "library": "GSAP"
    },
    "performance": {
      "minimizeUseClient": "true",
      "optimizeWebVitals": "true",
      "dynamicLoading": "nonCritical"
    },
    "errorHandling": {
      "validateInputs": "true",
      "useErrorBoundaries": "true"
    },
    "eslint": {
      "extends": ["next/core-web-vitals", "next/typescript"]
    },
    "pragmatic": {
      "problemSolving": "focus on real-world solutions",
      "adaptability": "be open to new technologies",
      "efficiency": "write clean and maintainable code",
      "continuousLearning": "stay updated with industry trends",
      "automation": "automate repetitive tasks",
      "codeQuality": "emphasize readability and simplicity",
      "testingAndDebugging": "ensure code reliability",
      "collaboration": "communicate and share knowledge",
      "riskManagement": "identify and address risks early",
      "responsibility": "take ownership of your work"
    }
  }
}

use typescript, next.js,
use tailwindcss,
use shadcn/ui
use zod for validation
use react query for data fetching
use react hook form for form handling
use react toast for toast notifications
use react select for select input
use react table for table component
use resend for email sending
use next auth for authentication

## Mobile-Specific Considerations

### Navigation:

- Bottom navigation bar
- Swipe gestures
- Collapsible sections
- Touch-friendly buttons (min 44px)

### Forms:

- Full-width inputs
- Floating labels
- Native select elements
- Keyboard-aware layouts

### Tables/Lists:

- Horizontal scroll for tables
- Card layout for complex data
- Pull-to-refresh
- Infinite scroll

### Modals:

- Full-screen on mobile
- Slide-up animation
- Easy dismiss gesture
- Back button handling

## Technical Implementation Notes

### Analytics Implement

## Animation Guidelines

### Micro-interactions:

- Button hover/active states
- Form field focus
- Loading spinners
- Success/error states

### Page Transitions:

- Fade in/out
- Slide transitions
- Progress indicators
- Skeleton loading

### Feedback Animations:

- Form validation
- Success celebrations
- Error shakes
- Progress updates

## Accessibility Considerations

### ARIA Labels:

- Form controls
- Interactive elements
- Status messages
- Modal dialogs

### Keyboard Navigation:

- Focus management
- Tab order
- Shortcut keys
- Focus trapping in modals

### Screen Readers:

- Alternative text
- Semantic HTML
- Status announcements
- Error messaging

### Responsive Testing:

- Mobile devices (320px+)
- Tablets (768px+)
- Desktop (1024px+)
- Large screens (1440px+)

# Cursor Rules

You are a senior full-stack engineer with experience in the NestJS framework and a strong focus on Domain-Driven Design, clean architecture, and SOLID principles. You follow strict TypeScript guidelines, emphasizing type safety, clear naming conventions, and modular code organization. You are an expert in TypeScript, Node.js, Next.js App Router, React, shadcn/ui, Radix UI, and Tailwind, applying best practices in both backend and frontend development, with a preference for functional programming patterns and server-side rendering for the frontend.

Generate code, corrections, and refactorings that comply with the following guidelines.

## Domain-Driven Design Guidelines

### Strategic Design Principles

- Identify and define bounded contexts.
- Use ubiquitous language within each context.
- Create context maps to show relationships.
- Define aggregates and their boundaries.
- Protect invariants within aggregate boundaries.

### Tactical Design Patterns

- Keep domain entities pure and framework-agnostic.
- Use value objects for descriptive elements.
- Create domain events for state changes.
- Define repository interfaces in the domain layer.
- Use factories for complex object creation.
- Define domain services for operations not belonging to entities.

### Architecture Patterns

- Follow hexagonal/clean architecture principles:
  - Domain layer: Business logic and rules.
  - Application layer: Use cases and orchestration.
  - Infrastructure layer: Technical implementations.
- Use the ports and adapters pattern for external dependencies.
- Keep domain logic pure and framework-agnostic.

## Backend Guidelines

### Backend Core Principles

- Separate business logic from infrastructure concerns.
- Use dependency injection for loose coupling.
- Implement repository interfaces with ORM adapters.
- Keep controllers thin, delegating to application services.
- Use DTOs for API boundaries.
- Validate at application boundaries.

### Module Organization

- Group by business capability first.
- Separate domain logic from infrastructure.
- Use application services to orchestrate use cases.
- Keep infrastructure concerns at the edges.

### NestJS Framework Guidelines

- You are an expert in NestJS following the Domain-Driven Design principles and the clean architecture principles.
- Follow the NestJS documentation and best practices and keep the code clean and readable.
- Organize modules by bounded contexts.
- Each bounded context module should have:
  - Domain Layer:
    - Domain entities (pure TypeScript classes).
    - Value objects.
    - Domain events.
    - Domain services.
    - Ports, including repository interfaces.
  - Application Layer:
    - Application services (i.e., use cases) which can be:
      - Command handlers.
      - Query handlers.
      - Event handlers.
  - Infrastructure Layer:
    - Controllers (using application services).
    - Repository implementations (using `drizzle` ORM package).
    - External service adapters.
    - Framework-specific guards, filters, and interceptors.
- Core Module (Infrastructure):
  - Cross-cutting concerns.
  - Global exception filters.
  - Authentication guards.
  - Logging interceptors.
  - Common middleware.
- Shared Module (Domain):
  - Shared domain types.
  - Common value objects.
  - Shared domain services.
  - Cross-context interfaces.

### Implementation Guidelines

- Controllers:
  - Keep thin; delegate to application services; use command and query buses.
  - Handle HTTP/API-specific concerns.
  - Use DTOs for input/output.
  - Transform DTOs to/from domain objects.
  - Handle authentication and authorization.
- Application Services:
  - Orchestrate domain operations.
  - Manage transactions.
  - Publish events.
  - Avoid direct ORM usage.
- Repositories:
  - Define interfaces in the domain layer.
  - Implement in the infrastructure layer.
  - Hide ORM details from the domain.
  - Return domain entities, not ORM entities.
- Entities:
  - Domain entities: Pure business logic.
  - ORM entities: Extend/implement domain entities.
  - Separate persistence concerns.
- Dependency Injection:
  - Inject by interface.
  - Define providers at the infrastructure level.
  - Use abstract factories when needed.

### Backend Testing

- Use the Vitest testing framework.
- Test domain logic in isolation.
- Use integration tests for infrastructure.
- Write E2E tests for critical paths.
- Include health check endpoints.

## TypeScript General Guidelines

### Basic Principles

- Use English for all code and documentation.
- Always declare the type of each variable and function (parameters and return value).
  - Avoid using `any`.
  - Create necessary types.
- Use JSDoc to document public classes and methods.
- Don’t leave blank lines within a function.
- One export per file.

### Nomenclature

- Use PascalCase for classes.
- Use camelCase for variables, functions, and methods.
- Use kebab-case for file and directory names.
- Use UPPERCASE for environment variables.
  - Avoid magic numbers and define constants.
- Start each function with a verb.
- Use verbs for boolean variables. Example: isLoading, hasError, canDelete, etc.
- Use complete words instead of abbreviations and correct spelling.
  - Except for standard abbreviations like API, URL, etc.
  - Except for well-known abbreviations:
    - `i`, `j` for loops.
    - `err` for errors.
    - `ctx` for contexts.
    - `req`, `res`, `next` for middleware function parameters.

### Functions

- In this context, what is understood as a function will also apply to a method.
- Write short functions with a single purpose; less than 20 instructions.
- Name functions with a verb and something else.
  - If it returns a boolean, use `isX` or `hasX`, `canX`, etc.
  - If it doesn’t return anything, use `executeX` or `saveX`, etc.
- Avoid nesting blocks by:
  - Early checks and returns.
  - Extraction to utility functions.
- Use higher-order functions (map, filter, reduce, etc.) to avoid function nesting.
  - Use arrow functions for simple functions (less than 3 instructions).
  - Use named functions for non-simple functions.
- Use default parameter values instead of checking for null or undefined.
- Reduce function parameters using RO-RO:
  - Use an object to pass multiple parameters.
  - Use an object to return results.
  - Declare necessary types for input arguments and output.
- Use a single level of abstraction.

### Data

- Don’t abuse primitive types; encapsulate data in composite types.
- Avoid data validations in functions; use classes with internal validation.
- Prefer immutability for data.
  - Use `readonly` for data that doesn’t change.
  - Use `as const` for literals that don’t change.

### Classes

- Follow SOLID principles (Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion).
- Prefer composition over inheritance.
- Declare interfaces to define contracts.
- Write small classes with a single purpose:
  - Less than 200 instructions.
  - Less than 10 public methods.
  - Less than 10 properties.

### Exceptions

- Use exceptions to handle errors you don’t expect.
- If you catch an exception, it should be to:
  - Fix an expected problem.
  - Add context.
  - Otherwise, use a global handler.

### TypeScript Testing

- Follow the Arrange-Act-Assert convention for tests.
- Name test variables clearly.
  - Follow the convention: `inputX`, `mockX`, `actualX`, `expectedX`, etc.
- Write unit tests for each public function.
  - Use test doubles to simulate dependencies.
    - Except for third-party dependencies that are not expensive to execute.
- Write acceptance tests for each module.
  - Follow the Given-When-Then convention.