Awesome Cursor Rules Collection

# Cursor Rules

## Framework
Next.js

## Language
TypeScript

## Principles

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

### File Structure
- Structure files in the following order: exported component, subcomponents, helpers, static content, types.
- Use lowercase with dashes for directories (e.g., components/auth-wizard).
- Favor named exports for components.

### TypeScript
- Use TypeScript for all code; prefer interfaces over types.
- Avoid enums; use maps instead.
- Use functional components with TypeScript interfaces.

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

### UI and Styling
- Use Shadcn UI, Radix, and Tailwind for components and styling.
- Implement responsive design with Tailwind CSS; 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.

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

# Umo Editor Configuration

Umo Editor is an open-source rich-text document editor built using:

- **Vue** (>=v3.x)
- **Tiptap** (>=v2.6)
- **TypeScript** (>=v5.5)
- **Vite** (>=v4.x)

You are an expert in all of these technologies

## Coding Style & Practices

- Prefer functional programming where appropriate
- Use OOP for complex service abstractions, otherwise prefer functional
- Ensure the code is strongly typed
- Follow these Prettier rules:

  ```json
  {
    "semi": false,
    "singleQuote": true,
    "tabWidth": 2
  }
  ```

- Use strict typing and assume the code maintainers are experienced TypeScript and VueJS developers.
- Import type predicate functions (isString, isRecord, isAsyncFunction etc.) from `@tool-belt/type-predicates`, it includes everything included in the node:util module and more, and is available in the browser.
- Use typescript path aliases as configured: `@/` which equals the workspace `src/*` directory, and `::testing/`, which equals the workspace `testing/` directory.
  Note: `::testing` should only be imported in test files.
- Test files are written next to the code file, inside the src folder, and they follow the `*.spec.ts` naming scheme.
- The VueMacroes and Reactivity transform libraries are configured in the vite config.

### Testing Guidelines

When writing tests:

- Use `vitest` for writing test with the `@testing-library/vue` and installed.
- Use `@faker-js/faker` where appropriate in tests to generate mock data.
- Use `it` rather than `test` and follow BDD test message practices.
- Use `describe.each` and `it.each` if parameterized tests are appropriate for the testing scenario.
- Use nested describes if testing multiple functions or classes in the same file.
- Use `vi.mocked(<value>)` to type cast values as mocks.

You are an expert full-stack web developer focused on producing clear, readable TypeScript code.

You always use the latest stable versions of everything, Tailwind CSS, and TypeScript, and you are familiar with the latest features and best practices.

You carefully provide accurate, factual, thoughtful answers, and are a genius at reasoning.

Technical preferences:

- Use semantic HTML elements where possible
- Always use kebab-case for component names (e.g. my-component.tsx)
- Follow docs from the official TypeScript, React, Remix, Next.js for Data Fetching, Rendering, and Routing
- Favour using React Server Components features where possible
- Minimize the usage of client components ('use client') to small, isolated components
- Always add loading and error states to data fetching components
- Implement error handling and error logging

General preferences:

- Follow the user's requirements carefully & to the letter.
- Always write correct, 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.
- Leave NO todo's, placeholders or missing pieces in the code.
- Be sure to reference file names.
- Be concise. Minimize any other prose.
- If you think there might not be a correct answer, you 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/awesome-button)
- 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

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 Shadcn UI, Radix, and Tailwind CSS for components and styling
- Implement responsive design with Tailwind CSS, 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

**Project Name**: Avalon Real Estate Website (Авалон Недвижими Имоти)

**Architecture**: Monorepo Structure using Turborepo
1. **Apps/**
   - `web/`: React frontend application
   - `api/`: Node.js/Express backend

2. **Packages/**
   - `shared-ui/`: Reusable UI components (including the recently updated Pagination component)
   - `shared-types/`: Common TypeScript type definitions

**Database Structure**:
- ORM: Prisma with SQLite
- ERD Location: `apps/api/prisma/ERD.svg`
- Key Models:
  1. User (auth & authorization)
  2. Property (main listing entity)
  3. Region/Neighborhood (location hierarchy)
  4. Feature/PropertyFeature (amenities, m2m)
  5. Image (property photos)
  6. ContactInfo (property contact)
  7. ContactMessage (inquiries)
- Schema: `apps/api/prisma/schema.prisma`
- ERD Generation: `npx prisma-uml ./prisma/schema.prisma --output svg --file ./prisma/ERD.svg`

**Tech Stack**:
- Frontend:
  - React + TypeScript
  - Tailwind CSS (with dark mode support)
  - React Router
  - TanStack Query
  - Zod for validation

- Backend:
  - Node.js + TypeScript
  - Express
  - Prisma ORM
  - SQLite/MongoDB
  - JWT Authentication

**Key Features**:
1. Responsive design with light/dark mode support
2. Property search and filtering
3. Admin panel with CRUD operations
4. Contact form with reCAPTCHA
5. Google Analytics integration
6. Interactive map integration

**Development Tools**:
- Package Manager: pnpm (v8.14.1+)
- Node Version: v20.12.2 (specified in .nvmrc)
- Code Quality: ESLint and Prettier
- Build System: Turborepo

**Current Development Status**:
Based on the roadmap, there are two main items being worked on:
1. Fixing property edit functionality (addressing validation errors for property types and contact info)
2. Implementing toast notifications for CRUD operations in the admin panel

**Recent Updates**:
The most recent changes involve improvements to the pagination component:
- Added dark mode support using CSS variables
- Implemented custom labels and translations
- Enhanced cache management in the pagination hook
- Improved test coverage and reliability

**Development Environment**:
- Local development servers:
  - Frontend: http://localhost:5173
  - Backend: http://localhost:3000

**Project Setup**:
```bash
pnpm install    # Install dependencies
pnpm dev        # Start development servers
```

This appears to be a professional real estate website project with a strong focus on type safety, component reusability, and modern development practices. The monorepo structure allows for good code organization and sharing of common components and types across different parts of the application.

Advanced Principles Applied to Frappe Framework

	•	Stateless Design: Similar to FastAPI, Frappe apps can also be designed to be stateless. Use Redis for caching, session management, or external databases for state persistence. For workflows, avoid storing state within the service layer and use backend databases for transactions.
	•	API Gateway & Traffic Management:
	•	Use NGINX or Traefik in front of Frappe to handle routing, load balancing, and SSL termination. For enterprise setups, an API Gateway (such as AWS API Gateway or Kong) can be integrated for rate limiting, request transformation, and authentication (OAuth2).
	•	Frappe’s built-in REST API can be exposed via these gateways for microservices-like communication with other services.
	•	Resilient Communication:
	•	Implement retries and circuit breakers in external services that integrate with Frappe. Consider using a message broker (RabbitMQ, Kafka) for event-driven communication, as Frappe supports Webhooks and background jobs.

Microservices and API Gateway Integration

	•	Integration of Frappe and API Gateway:
	•	Use Frappe’s built-in REST framework to expose APIs that can be routed through Kong or AWS API Gateway.
	•	Manage rate limiting and DDoS protection at the API Gateway level.
	•	You can configure NGINX in front of Frappe to handle reverse proxy for microservices, where Frappe is one of many services.
	•	Message Broker for Inter-Service Communication:
	•	For communication between Frappe microservices, leverage Celery (which is well-supported by Frappe) with RabbitMQ to handle task queues and background processing, ensuring asynchronous inter-service communication.

Serverless and Cloud-Native Patterns for Frappe

	•	Frappe in Serverless Environments:
	•	While Frappe isn’t natively designed for serverless, you can containerize Frappe with Docker and deploy it in FaaS environments like AWS Lambda (using EFS for file storage). Be mindful of cold start times, though you can optimize these by using container-based serverless services like AWS Fargate.
	•	Database Scaling:
	•	Frappe’s reliance on relational databases like MariaDB or PostgreSQL can be supplemented with cloud-native managed databases like AWS RDS or Google Cloud SQL. DynamoDB or CosmosDB could be used for high-scale, NoSQL scenarios (though this requires custom integration).

Advanced Middleware and Security for Frappe

	•	Custom Middleware for Logging & Security:
	•	Implement custom Frappe hooks and middleware for detailed logging, error handling, and tracing using OpenTelemetry. These can provide distributed tracing across Frappe apps within a microservices architecture.
	•	OAuth2 & Security Practices:
	•	Frappe’s OAuth2 integration allows secure API access, which can be enhanced using API Gateways to manage OAuth tokens, rate limiting, and request validation.
	•	Leverage CORS, CSP, and security headers through NGINX configuration or directly within Frappe’s REST API middleware.

Performance and Scalability Enhancements in Frappe

	•	Leverage Frappe’s Background Jobs:
	•	Use Frappe’s background jobs to handle long-running tasks asynchronously, similar to Celery. Redis serves as the broker, and this can be extended for handling large volumes of tasks in parallel.
	•	Caching Layers:
	•	Integrate Redis with Frappe for caching frequently accessed data (e.g., heavy reports or user sessions), reducing the load on the backend database and improving response times.
	•	Load Balancing and Scaling:
	•	Deploy Frappe in a containerized environment using Kubernetes with Istio or Linkerd to enable service mesh functionality. This helps in scaling services dynamically, ensuring high throughput and service-to-service communication without bottlenecks.

Monitoring and Logging

	•	Distributed Logging and Monitoring:
	•	Integrate Prometheus for monitoring Frappe’s performance and resource utilization. Use Grafana to visualize metrics like request counts, response times, and errors.
	•	Implement structured logging using Elasticsearch (via ELK stack) for better analysis of Frappe’s logs, especially when running in distributed environments.

Key Frappe Conventions for Scalability

	1.	Microservices and Cloud-Native:
	•	Treat Frappe modules as microservices where possible, especially when integrating with external services.
	•	Deploy in containerized environments (e.g., Kubernetes) to achieve high availability and scalability.
	2.	Security & Performance:
	•	Follow advanced security practices (OAuth2, SSL termination, API Gateways).
	•	Focus on reducing latency and improving request handling through caching and efficient database usage.
	3.	Serverless Considerations:
	•	While not a traditional serverless framework, Frappe can be optimized for cloud environments, with functions, event-driven architecture, and managed services.


You are an expert in TypeScript, Node.js, NuxtJS, Vue 3, Shadcn Vue, Radix Vue, VueUse, and Tailwind.
	
	Code Style and Structure
	- Write concise, technical TypeScript code with accurate examples.
	- Use composition API and declarative programming patterns; avoid options API.
	- Prefer iteration and modularization over code duplication.
	- Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError).
	- Structure files: exported component, composables, helpers, static content, types.
	
	Naming Conventions
	- Use lowercase with dashes for directories (e.g., components/auth-wizard).
	- Use PascalCase for component names (e.g., AuthWizard.vue).
	- Use camelCase for composables (e.g., useAuthState.ts).
	
	TypeScript Usage
	- Use TypeScript for all code; prefer types over interfaces.
	- Avoid enums; use const objects instead.
	- Use Vue 3 with TypeScript, leveraging defineComponent and PropType.
	
	Syntax and Formatting
	- Use arrow functions for methods and computed properties.
	- Avoid unnecessary curly braces in conditionals; use concise syntax for simple statements.
	- Use template syntax for declarative rendering.
	
	UI and Styling
	- Use Shadcn Vue, Radix Vue, and Tailwind for components and styling.
	- Implement responsive design with Tailwind CSS; use a mobile-first approach.
	
	Performance Optimization
	- Leverage Nuxt's built-in performance optimizations.
	- Use Suspense for asynchronous components.
	- Implement lazy loading for routes and components.
	- Optimize images: use WebP format, include size data, implement lazy loading.
	
	Key Conventions
	- Use VueUse for common composables and utility functions.
	- Use Pinia for state management.
	- Optimize Web Vitals (LCP, CLS, FID).
	- Utilize Nuxt's auto-imports feature for components and composables.
	
	Nuxt-specific Guidelines
	- Follow Nuxt 3 directory structure (e.g., pages/, components/, composables/).
	- Use Nuxt's built-in features:
	- Auto-imports for components and composables.
	- File-based routing in the pages/ directory.
	- Server routes in the server/ directory.
	- Leverage Nuxt plugins for global functionality.
	- Use useFetch and useAsyncData for data fetching.
	- Implement SEO best practices using Nuxt's useHead and useSeoMeta.
	
	Vue 3 and Composition API Best Practices
	- Use <script setup> syntax for concise component definitions.
	- Leverage ref, reactive, and computed for reactive state management.
	- Use provide/inject for dependency injection when appropriate.
	- Implement custom composables for reusable logic.
	
	Follow the official Nuxt.js and Vue.js documentation for up-to-date best practices on Data Fetching, Rendering, and Routing.
	

# LMS MVP Project Rules
# This file defines the rules and processes for our Learning Management System project

# Template Preservation Guidelines
template_preservation:
  holy_files:
    - payload.config.ts:
        rules:
          - 'Maintain original import structure and order'
          - 'Keep original comments and placeholders'
          - 'Use defaultLexical from fields directory'
          - 'Preserve getServerSideURL utility'
          - 'No type annotations in this file'
          - 'No plugin configurations (move to plugins.ts)'
          - 'No direct editor configurations'
          - 'Minimal comments, only from original template'
          - 'Use standard Node.js imports (no node: prefix)'
          - 'Keep file-type imports compatible with Payload version'
        import_structure:
          order:
            1: 'Database adapter (mongooseAdapter)'
            2: 'Core dependencies (sharp, path, payload, url)'
            3: 'Collections'
            4: 'Globals'
            5: 'Plugins and utilities'
            6: 'Spaces module imports (last)'
        modifications:
          allowed:
            - 'Adding Spaces collections to collections array'
            - 'Adding Settings to globals array'
            - 'Adding Spaces imports at the end'
          forbidden:
            - 'Adding type imports'
            - 'Adding generateTitle/URL functions'
            - 'Modifying original template comments'
            - 'Adding new plugin configurations'
            - 'Using node: protocol imports'

    - plugins.ts:
        rules:
          - 'Keep all plugin configurations here'
          - 'Maintain original plugin order'
          - 'Keep type annotations for plugin configs'
          - 'Preserve SEO title/URL generation'
        structure:
          - 'Import all plugins first'
          - 'Import types for configurations'
          - 'Define helper functions'
          - 'Export plugins array'

  spaces_integration:
    collections_integration:
      - 'Add Spaces collections after template collections'
      - 'Maintain original collection order'
      - 'No collection configuration in payload.config.ts'

    globals_integration:
      - 'Add Settings global last in globals array'
      - 'Keep original globals order (Header, Footer)'

    imports_organization:
      - 'Group Spaces imports separately'
      - 'Place Spaces imports after template imports'
      - 'Use consistent import style'

# Technology Stack Requirements
technologies:
  frontend:
    - framework: 'Next.js@15.0.0'
    - styling: 'tailwindcss@latest'
    - ui:
        - 'shadcn-ui@latest'
        - 'aceternity-ui@latest'
        - 'magic-ui@latest'
        - 'vaul@latest'
        - 'sonner@latest'
        - 'cmdk@latest'
    - state: 'nuqs@latest'
    - forms: '@hookform/resolvers@latest'
    - validation: 'zod@latest'
    - animation:
        - 'framer-motion@latest'
        - '@legendapp/motion@latest'
        - '@formkit/auto-animate@latest'

  backend:
    - cms: 'payload@3.0.0'
    - orm: 'drizzle-orm@latest'
    - database: 'neon@latest'
    - auth:
        current: 'payload-auth@3.0.0'
        future: 'clerk@latest'
    - ai: '@vercel/ai@latest'
    - payments: 'stripe@latest'
    - uploads: 'uploadthing@latest'
    - email: 'resend@latest'
    - realtime: 'pusher@latest'

  deployment:
    - platform: 'vercel@latest'
    - monitoring:
        - 'sentry@latest'
        - '@google-cloud/logging@latest'
        - '@google-cloud/opentelemetry-cloud-monitoring-exporter@latest'
        - '@google-cloud/opentelemetry-cloud-trace-exporter@latest'
    - analytics: 'vercel-analytics@latest'

  compatibility:
    notes:
      - 'Payload CMS 3.0 requires Next.js 15 for optimal performance'
      - 'Server Actions are fully supported in Next.js 15'
      - 'App Router is the recommended approach'
      - 'React Server Components are fully utilized'
      - 'nuqs provides URL-based state management compatible with RSC'

# State Management Guidelines
state:
  principles:
    - 'Prefer server-side state management over client-side'
    - 'Use URL state for shareable and bookmarkable UI states'
    - 'Leverage React Server Components for data fetching'
    - 'Minimize client-side JavaScript'

  urlState:
    usage:
      - 'Search parameters and filters'
      - 'Pagination state'
      - 'Tab selections'
      - 'Modal states'
      - 'Sort orders'
      - 'View preferences'

    implementation:
      - 'Use nuqs for type-safe URL state management'
      - 'Define searchParams types with Zod schemas'
      - 'Implement default values for all URL parameters'
      - 'Handle URL parameter validation'

    benefits:
      - 'SEO-friendly state management'
      - 'Shareable URLs with complete state'
      - 'Reduced client-side JavaScript'
      - 'Better caching capabilities'
      - 'Native browser history support'

  serverState:
    patterns:
      - 'Use Server Components for data fetching'
      - 'Implement server actions for mutations'
      - 'Cache responses appropriately'
      - 'Handle loading and error states'

  clientState:
    limitations:
      - 'Restrict to ephemeral UI state only'
      - 'Use React.useState for temporary form state'
      - 'Avoid redundant client-side state'
      - 'Prefer URL state when possible'

# Collections Structure
collections:
  core:
    - Tenants
    - Users
    - Courses
    - Modules
    - Lessons
    - Quizzes
    - Assignments
    - Submissions

  gamification:
    - Points
    - Badges
    - Achievements
    - Streaks
    - Leaderboard

  communication:
    - Notifications
    - Collaborations
    - Announcements
    - SupportTickets

  settings:
    - TenantSettings
    - StudentSettings
    - LearningPaths

# File Structure
structure:
  app:
    - '(auth): Authentication routes'
    - '(dashboard): Protected dashboard routes'
    - 'api: API routes when necessary'
    - 'public: Static assets'

  components:
    - 'ui: Reusable UI components'
    - 'forms: Form components'
    - 'layouts: Layout components'

  lib:
    - 'db: Database configuration'
    - 'utils: Utility functions'
    - 'validation: Schema validation'

  types:
    - 'Global type definitions'

# Code Standards
standards:
  general:
    - 'Use TypeScript strict mode'
    - 'Implement proper error handling'
    - 'Add comprehensive logging'
    - 'Document all public APIs'
    - 'Follow SOLID principles'

  nextjs:
    - 'Use server components by default'
    - 'Implement proper data fetching patterns'
    - 'Optimize for performance'
    - 'Follow app router best practices'

  database:
    - 'Use Drizzle migrations'
    - 'Implement proper indexing'
    - 'Handle database errors gracefully'
    - 'Use transactions where needed'

  security:
    - 'Implement proper authentication'
    - 'Use role-based access control'
    - 'Sanitize all inputs'
    - 'Protect sensitive data'

  testing:
    - 'Write tests for critical paths'
    - 'Maintain good test coverage'
    - 'Use proper test isolation'
    - 'Mock external dependencies'

# Multi-Agent Development Process
agents:
  architect:
    role: 'System Design & Architecture'
    responsibilities:
      - 'Review and approve architectural decisions'
      - 'Ensure scalability and performance'
      - 'Maintain system consistency'
      - 'Plan data structures and relationships'
    triggers:
      - 'New feature proposal'
      - 'Architecture changes'
      - 'Performance optimization requests'
      - 'Database schema updates'

  developer:
    role: 'Code Implementation'
    responsibilities:
      - 'Write clean, maintainable code'
      - 'Implement features according to specs'
      - 'Handle error cases and edge conditions'
      - 'Optimize database queries'
    triggers:
      - 'New feature request'
      - 'Bug fix needed'
      - 'Code optimization required'
      - 'Performance issues'

  reviewer:
    role: 'Code Review & Quality'
    responsibilities:
      - 'Review code for best practices'
      - 'Check for security vulnerabilities'
      - 'Ensure code style consistency'
      - 'Verify state management patterns'
    checks:
      - 'Code style compliance'
      - 'Security best practices'
      - 'Performance implications'
      - 'Test coverage'
      - 'URL state management'

  tester:
    role: 'Testing & Validation'
    responsibilities:
      - 'Write and maintain tests'
      - 'Verify feature functionality'
      - 'Regression testing'
      - 'Load testing'
    testTypes:
      - 'Unit tests'
      - 'Integration tests'
      - 'E2E tests'
      - 'Performance tests'
      - 'Load tests'

  security:
    role: 'Security Compliance'
    responsibilities:
      - 'Review security implications'
      - 'Ensure data protection'
      - 'Audit authentication/authorization'
      - 'Monitor security events'
    checks:
      - 'Authentication flows'
      - 'Data encryption'
      - 'API security'
      - 'Input validation'
      - 'Rate limiting'

# Development Workflow
workflow:
  featureImplementation:
    steps:
      1:
        agent: 'architect'
        action: 'Review feature proposal'
        output: 'Architecture decision document'
        stateConsiderations:
          - 'Determine if state should be URL-based'
          - 'Plan server component structure'
          - 'Identify client/server state boundaries'
          - 'Consider data persistence needs'

      2:
        agent: 'developer'
        action: 'Implement feature'
        requirements:
          - 'Follow Next.js 15 app router patterns'
          - 'Use server actions over API routes'
          - 'Implement URL state management with nuqs'
          - 'Add proper loading and error states'
          - 'Implement proper error handling'
          - 'Add logging and monitoring'

      3:
        agent: 'reviewer'
        action: 'Code review'
        checks:
          - 'Code quality'
          - 'Performance'
          - 'Security'
          - 'Documentation'
          - 'State management'

      4:
        agent: 'tester'
        action: 'Testing'
        requirements:
          - 'Unit tests for utilities'
          - 'Integration tests for API'
          - 'E2E tests for critical flows'
          - 'Load testing for scalability'

      5:
        agent: 'security'
        action: 'Security review'
        focus:
          - 'Data protection'
          - 'Authentication'
          - 'Authorization'
          - 'Rate limiting'

  bugFix:
    steps:
      1:
        agent: 'developer'
        action: 'Reproduce and fix'
        requirements:
          - 'Document reproduction steps'
          - 'Add regression test'

      2:
        agent: 'reviewer'
        action: 'Review fix'
        checks:
          - 'Fix completeness'
          - 'No new issues introduced'

      3:
        agent: 'tester'
        action: 'Verify fix'
        requirements:
          - 'Test fix effectiveness'
          - 'Run regression tests'

# Error Handling
errors:
  levels:
    - 'fatal: System crash level'
    - 'error: Operation failure'
    - 'warn: Potential issues'
    - 'info: General information'
    - 'debug: Debug information'

  handling:
    - 'Use custom error classes'
    - 'Implement proper error boundaries'
    - 'Log errors with context'
    - 'Provide user-friendly messages'

# Deployment Guidelines
deployment:
  vercel:
    configuration:
      - 'Use Edge Functions where appropriate'
      - 'Configure proper caching strategies'
      - 'Set up proper environment variables'
      - 'Configure deployment regions'
    monitoring:
      - 'Set up error tracking with Sentry'
      - 'Configure OpenTelemetry for tracing'
      - 'Implement custom logging'
      - 'Monitor Core Web Vitals'

  database:
    neon:
      - 'Configure connection pooling'
      - 'Set up read replicas'
      - 'Implement query optimization'
      - 'Configure automated backups'

  security:
    measures:
      - 'Implement rate limiting'
      - 'Set up CORS policies'
      - 'Configure CSP headers'
      - 'Enable WAF protection'

# Performance Requirements
performance:
  metrics:
    - 'Time to First Byte (TTFB) < 100ms'
    - 'First Contentful Paint (FCP) < 1.5s'
    - 'Largest Contentful Paint (LCP) < 2.5s'
    - 'First Input Delay (FID) < 100ms'
    - 'Cumulative Layout Shift (CLS) < 0.1'

  optimization:
    - 'Implement proper code splitting'
    - 'Use React Suspense boundaries'
    - 'Optimize images and assets'
    - 'Minimize client-side JavaScript'
    - 'Utilize edge caching'

# Commit Guidelines
commits:
  format: 'type(scope): description'
  types:
    - 'feat: New feature'
    - 'fix: Bug fix'
    - 'docs: Documentation'
    - 'style: Code style'
    - 'refactor: Code refactor'
    - 'test: Testing'
    - 'chore: Maintenance'

# Backup and Recovery
backup:
  database:
    - 'Automated daily backups'
    - 'Point-in-time recovery'
    - 'Cross-region replication'
    - 'Backup retention policy'

  assets:
    - 'Media file backups'
    - 'Document versioning'
    - 'Metadata backup'
    - 'Recovery procedures'

  monitoring:
    - 'Backup success monitoring'
    - 'Recovery testing schedule'
    - 'Audit logging'
    - 'Alert configuration'

# Authentication Strategy
auth:
  phase1:
    provider: 'Payload Built-in Auth'
    features:
      - 'Email/password authentication'
      - 'Role-based access control'
      - 'Session management'
      - 'Password reset flow'
      - 'Email verification'
    implementation:
      - "Use Payload's built-in auth system"
      - 'Implement custom auth endpoints in Next.js'
      - 'Set up proper session handling'
      - 'Configure secure password policies'
      - 'Set up email templates for auth flows'

  phase2:
    provider: 'Clerk'
    features:
      - 'Social authentication'
      - 'Multi-factor authentication'
      - 'User management dashboard'
      - 'Advanced security features'
      - 'Authentication analytics'
    migration:
      - 'Plan user data migration strategy'
      - 'Set up Clerk webhooks'
      - 'Update auth middleware'
      - 'Migrate existing users'
      - 'Update frontend components'

  security:
    - 'Implement CSRF protection'
    - 'Set secure cookie policies'
    - 'Configure rate limiting'
    - 'Set up proper session timeouts'
    - 'Implement audit logging'

# UI and Animation Patterns
ui_patterns:
  floating:
    description: 'Elements that float and respond to user interaction'
    implementations:
      - 'Floating navigation with Framer Motion'
      - 'Hover cards using shadcn/ui + Aceternity'
      - 'Animated tooltips with Magic UI'
      - 'Context menus with radix-ui animations'
    libraries:
      - 'framer-motion'
      - 'aceternity-ui'
      - 'magic-ui'
      - 'vaul'

  morphing:
    description: 'Elements that transform and change shape'
    implementations:
      - 'Shape-shifting buttons with Framer Motion'
      - 'Expanding cards using Aceternity UI'
      - 'Transitioning layouts with Motion One'
      - 'Fluid backgrounds with Magic UI'
    libraries:
      - 'framer-motion'
      - 'aceternity-ui'
      - 'motion-one'
      - 'magic-ui'

  micro_interactions:
    description: 'Small, subtle animations that provide feedback'
    implementations:
      - 'Button click effects with tailwindcss-animate'
      - 'Input focus states with shadcn/ui'
      - 'Loading spinners with Lucide icons'
      - 'Progress indicators with Sonner'
    libraries:
      - 'tailwindcss-animate'
      - 'shadcn-ui'
      - 'lucide-react'
      - 'sonner'

  scroll_animations:
    description: 'Animations triggered by scroll events'
    implementations:
      - 'Parallax effects with Framer Motion'
      - 'Scroll-triggered reveals with Aceternity'
      - 'Smooth transitions with Motion One'
      - 'Intersection animations with Magic UI'
    libraries:
      - 'framer-motion'
      - 'aceternity-ui'
      - 'motion-one'
      - 'magic-ui'

animation_patterns:
  layout:
    description: 'Page and layout transition animations'
    implementations:
      - 'Page transitions with Framer Motion'
      - 'Route changes using Next.js + Motion One'
      - 'Modal animations with Vaul'
      - 'List reordering with Auto Animate'
    libraries:
      - 'framer-motion'
      - 'motion-one'
      - 'vaul'
      - '@formkit/auto-animate'

  feedback:
    description: 'User feedback animations'
    implementations:
      - 'Loading states with Lucide'
      - 'Success/error animations with Sonner'
      - 'Progress indicators with shadcn/ui'
      - 'Notification toasts with Magic UI'
    libraries:
      - 'lucide-react'
      - 'sonner'
      - 'shadcn-ui'
      - 'magic-ui'

  interaction:
    description: 'User interaction animations'
    implementations:
      - 'Hover effects with tailwindcss-animate'
      - 'Click responses with Framer Motion'
      - 'Drag and drop with Motion One'
      - 'Gesture animations with Magic UI'
    libraries:
      - 'tailwindcss-animate'
      - 'framer-motion'
      - 'motion-one'
      - 'magic-ui'

# Component Animation Guidelines
component_animations:
  principles:
    - 'Use subtle animations by default'
    - 'Ensure animations are accessible (respect reduced-motion)'
    - 'Keep animations under 300ms for micro-interactions'
    - 'Use spring animations for natural feel'
    - 'Maintain consistent animation patterns'

  performance:
    - 'Use CSS transforms over position properties'
    - 'Animate on compositor-only properties'
    - 'Implement proper will-change hints'
    - 'Use requestAnimationFrame for JS animations'
    - 'Lazy load heavy animation libraries'

  accessibility:
    - 'Respect prefers-reduced-motion'
    - "Ensure animations don't cause vestibular issues"
    - 'Provide alternative static states'
    - 'Keep animations subtle and purposeful'
    - 'Allow animation opt-out'
# Spaces Module Integration
spaces:
  changes:
    - 'Update collections structure'
    - 'Add real-time specific requirements'
    - 'All Payload Specific Types are found in /src/spaces/types exceptions are found in /src/spaces/types/'
    - 'Minimize changes to the existing Payload CMS official Website Template'
    - 'Use modals found in /src/spaces/modals for UX CRUD operations'
    - 'Update state management for real-time features'
    - 'Add Socket.IO specific configurations'

  theme:
    colors:
      background:
        primary: 'bg-gradient-to-br from-[#7364c0] to-[#02264a]'
        dark: 'dark:from-[#000C2F] dark:to-[#003666]'
      input:
        background: 'bg-[#383A40] dark:bg-[#383A40]'
        text: 'text-zinc-200'
      text:
        primary: 'text-white'
        secondary: 'text-zinc-200'
        muted: 'text-zinc-400'
      accent:
        primary: 'bg-[#7364c0]'
        secondary: 'bg-[#02264a]'

    components:
      chat:
        messages:
          container: 'bg-gradient-to-br from-[#7364c0] to-[#02264a] dark:from-[#000C2F] dark:to-[#003666]'
          welcome:
            icon: 'bg-zinc-700'
            text: 'text-white'
        input:
          container: 'bg-gradient-to-br from-[#7364c0] to-[#02264a] dark:from-[#000C2F] dark:to-[#003666]'
          box: 'bg-[#383A40] dark:bg-[#383A40] text-zinc-200'
      header:
        container: 'bg-gradient-to-br from-[#7364c0] to-[#02264a] dark:from-[#000C2F] dark:to-[#003666]'
      sidebar:
        container: 'bg-gradient-to-br from-[#7364c0] to-[#02264a] dark:from-[#000C2F] dark:to-[#003666]'
      modals:
        container: 'bg-gradient-to-br from-[#7364c0] to-[#02264a] dark:from-[#000C2F] dark:to-[#003666]'

    rules:
      - 'All Spaces components should use the defined gradient backgrounds'
      - 'Keep Payload admin UI using default Payload styling'
      - 'Use dark mode variants for better accessibility'
      - 'Maintain consistent blue gradient theme across all Spaces components'
      - 'Input elements should use darker solid backgrounds for contrast'
      - 'Text should be properly contrasted against gradient backgrounds'

    scope:
      included:
        - 'All components under /src/spaces/*'
        - 'All pages under /src/app/(spaces)/*'
        - 'All Spaces-specific modals and overlays'
      excluded:
        - 'Payload admin dashboard'
        - 'Payload collection views'
        - 'Default Payload components'
        - 'Core CMS functionality'

# Troubleshooting Guidelines
troubleshooting:
  path_resolution:
    common_issues:
      - issue: 'Module not found errors'
        fix:
          - 'Use @/ prefix instead of src/ for imports'
          - 'Ensure path exists in tsconfig.json paths'
          - 'Check case sensitivity of file paths'
          - 'Verify file extensions match'

      - issue: 'Import path inconsistencies'
        fix:
          - 'Standardize on @/ prefix for all internal imports'
          - 'Use relative paths only for same-directory imports'
          - 'Update all src/ prefixes to @/'
          - 'Check tsconfig.json path mappings'

    import_standards:
      paths:
        - '@/*: Absolute imports from src directory'
        - './: Relative imports from same directory'
        - '../: Relative imports from parent directory'
        - '@/components/: UI components'
        - '@/utilities/: Utility functions'
        - '@/types/: Type definitions'
        - '@/spaces/: Spaces module'

      conventions:
        - 'Always use @/ prefix for src directory imports'
        - 'Keep relative imports to minimum'
        - 'Group imports by type/source'
        - 'Maintain consistent order'

    tsconfig_paths:
      required:
        - '@/*: ["./src/*"]'
        - 'payload/types: ["./node_modules/payload/types", "./src/types/payload-custom"]'
        - 'payload/config: ["./node_modules/payload/dist/config"]'
        - '@payload-config: ["./src/payload.config.ts"]'

  webpack:
    node_imports:
      issue: 'UnhandledSchemeError with node: protocol imports'
      fix:
        - 'Use standard import paths (e.g., fs instead of node:fs)'
        - 'Update webpack configuration to handle node: imports if needed'
        - 'Add node polyfills in next.config.js if required'

    file_type:
      issue: 'fileTypeFromFile import error from file-type package'
      fix:
        - 'Use compatible version of file-type package'
        - 'Update import statement to match exported members'
        - 'Add proper webpack resolution for file-type package'

  next_js:
    cache:
      issue: 'Webpack cache errors and pack file strategy failures'
      fix:
        - 'Clear .next/cache directory'
        - 'Run with clean cache: NEXT_SKIP_CACHE=1'
        - 'Ensure proper file permissions'

    hot_reload:
      issue: 'Fast Refresh errors requiring full reload'
      fix:
        - 'Check for circular dependencies'
        - 'Verify export/import consistency'
        - 'Ensure proper module boundaries'

  payload:
    type_generation:
      issue: 'Payload type generation errors'
      fix:
        - 'Run payload generate:types after collection changes'
        - 'Ensure proper TypeScript configuration'
        - 'Check for circular type dependencies'

    cors:
      issue: '500 errors on API routes'
      fix:
        - 'Verify CORS configuration matches environment'
        - 'Check serverURL configuration'
        - 'Validate authentication setup'

# Authentication Path Guidelines
auth_paths:
  standardization:
    routes:
      - path: '/login'
        purpose: 'Main authentication entry point'
        handling:
          - 'All auth-related redirects should point here'
          - 'Maintain single source of truth for auth flow'
          - 'Handle both /sign-in and /login redirects'

      - path: '/sign-in'
        purpose: 'Clerk authentication route'
        handling:
          - 'Should redirect to /login'
          - 'Update middleware to handle redirect'
          - 'Maintain Clerk integration compatibility'

    redirects:
      rules:
        - 'All authentication redirects go to /login'
        - 'Maintain redirect chain in middleware'
        - 'Handle both relative and absolute paths'
        - 'Preserve query parameters'

      implementation:
        middleware:
          - 'Add redirect mapping in middleware'
          - 'Handle auth state consistently'
          - 'Preserve return URLs'
          - 'Log redirect chains'

  error_handling:
    auth_failures:
      - issue: '500 errors on auth routes'
        fix:
          - 'Check auth provider configuration'
          - 'Verify environment variables'
          - 'Ensure consistent redirect paths'
          - 'Log auth flow errors'

      - issue: 'Redirect loops'
        fix:
          - 'Map all auth paths to /login'
          - 'Update middleware redirect logic'
          - 'Clear auth state if needed'
          - 'Add maximum redirect count'

    session:
      - issue: 'Session validation failures'
        fix:
          - 'Check session cookie configuration'
          - 'Verify auth provider setup'
          - 'Ensure proper CORS settings'
          - 'Validate session middleware'

# Middleware Guidelines
middleware:
  auth:
    rules:
      - 'Handle all auth-related paths'
      - 'Maintain consistent redirect chain'
      - 'Preserve query parameters'
      - 'Log redirect decisions'

    implementation:
      - pattern: |
          export async function middleware(request: NextRequest) {
            // Auth path standardization
            if (request.nextUrl.pathname === '/sign-in') {
              return NextResponse.redirect(new URL('/login', request.url))
            }

            // Other auth checks
            if (request.nextUrl.pathname.startsWith('/spaces')) {
              const { user } = await checkSession()
              if (!user) {
                return NextResponse.redirect(new URL('/login', request.url))
              }
            }
          }

  paths:
    protected:
      - '/spaces/*'
      - '/dashboard/*'
      - '/settings/*'

    auth:
      - '/login'
      - '/sign-in'
      - '/sign-up'
      - '/forgot-password'

    public:
      - '/'
      - '/about'
      - '/contact'

# Development Environment
environment:
  next_config:
    webpack:
      - 'Configure proper node polyfills'
      - 'Handle node: protocol imports'
      - 'Set up proper module resolution'
      - 'Configure file-type package resolution'

    experimental:
      - 'Enable necessary experimental features'
      - 'Configure proper serverActions'
      - 'Set up proper middleware handling'

  dependencies:
    payload:
      version: '3.0.0'
      peer_dependencies:
        - 'next@15.0.0'
        - 'react@18.2.0'
        - 'react-dom@18.2.0'

    critical:
      - 'file-type: Use compatible version'
      - 'sharp: Required for image processing'
      - 'mongodb: Required for database'

  typescript:
    config:
      - 'Enable strict mode'
      - 'Configure proper module resolution'
      - 'Set up proper path aliases'
      - 'Handle node module types'

# Real-time Communication Patterns
realtime:
  sse:
    principles:
      - 'Use Server-Sent Events (SSE) for real-time updates'
      - 'Prefer SSE over WebSockets for unidirectional data flow'
      - 'Maintain consistent authentication via cookies'
      - 'Implement proper cleanup and reconnection logic'
      - 'Messages belong to channels, channels belong to spaces'
      - 'Space membership is enforced at channel level'

    implementation:
      auth:
        - 'Use withCredentials: true for cookie-based auth'
        - 'Rely on Payload built-in cookie authentication'
        - 'No manual token handling in SSE connections'
        - 'Let Next.js/Payload handle cookie management'

      data_relationships:
        - 'Messages are linked to channels directly'
        - 'Channels are linked to spaces'
        - 'Space membership check happens at channel level'
        - 'No direct space check needed for messages'

      connection:
        - 'Implement proper connection cleanup'
        - 'Handle reconnection with exponential backoff'
        - 'Maximum 3 retry attempts'
        - 'Maximum 5 second delay between retries'

      state:
        - 'Use Set for message deduplication'
        - 'Maintain message order with timestamps'
        - 'Track last message ID for pagination'
        - 'Clear message state on cleanup'

      error_handling:
        - 'Provide clear error messages to users'
        - 'Log connection errors for debugging'
        - 'Handle unmounted component cleanup'
        - 'Reset retry count on successful messages'

    endpoints:
      - path: '/api/messages/sse'
        auth: 'Required'
        params:
          - 'channelId or conversationId'
          - 'spaceId'
          - 'lastMessageId (optional)'
        features:
          - 'Keep-alive ping every 30 seconds'
          - 'Initial message load on connect'
          - 'Real-time message updates'
          - 'Proper error responses'

    components:
      hooks:
        - name: 'useMessages'
          params:
            - 'chatId: string'
            - 'type: channel | conversation'
            - 'spaceId: string'
          state:
            - 'messages: MessageType[]'
            - 'error: string | null'
          refs:
            - 'messageSet: Set<string>'
            - 'eventSource: EventSource'
            - 'retryTimeout: NodeJS.Timeout'
            - 'retryCount: number'
            - 'mounted: boolean'
            - 'lastMessageId: string'

      chat:
        - name: 'ChatMessages'
          props:
            - 'name: string'
            - 'member: ExtendedMember'
            - 'chatId: string'
            - 'type: channel | conversation'
            - 'socketQuery: { spaceId, channelId?, conversationId? }'
          features:
            - 'Real-time message updates'
            - 'Message deduplication'
            - 'Error handling'
            - 'Proper cleanup'

    best_practices:
      - 'Keep SSE connection logic in custom hooks'
      - 'Handle component unmounting properly'
      - 'Implement proper error boundaries'
      - 'Use proper TypeScript types'
      - 'Maintain consistent error messages'
      - 'Log connection events for debugging'
      - 'Clean up resources on unmount'
      - 'Handle reconnection gracefully'

# Error Handling Standards
error_handling:
  file_structure:
    root_level:
      - file: 'src/app/error.tsx'
        rules:
          - 'Must be client component (use client)'
          - 'No HTML structure'
          - 'Use h2 for headings'
          - 'Include error logging in useEffect'
          - 'Provide reset functionality'

      - file: 'src/app/not-found.tsx'
        rules:
          - 'Server component by default'
          - 'No HTML structure'
          - 'Use h2 for headings'
          - 'Match error.tsx styling'
          - 'Include home navigation'

      - file: 'src/app/global-error.tsx'
        rules:
          - 'Must be client component (use client)'
          - 'No HTML structure'
          - 'Use h1 for headings'
          - 'Include error logging'
          - 'Provide reset functionality'

  styling:
    components:
      container: 'flex flex-col items-center gap-4'
      heading: 'text-4xl font-bold'
      message: 'text-lg text-muted-foreground'
      button: 'variant="default"'

  logging:
    principles:
      - 'Log all errors in useEffect'
      - 'Include error message and stack trace'
      - 'Add error context when available'
      - 'Use consistent error format'

  best_practices:
    - 'Keep HTML structure in global-error.tsx only'
    - 'Use consistent styling across error pages'
    - 'Maintain proper heading hierarchy'
    - 'Provide clear error messages'
    - 'Include recovery actions'
    - 'Log errors with context'

  testing:
    requirements:
      - 'Test error boundary functionality'
      - 'Verify error message display'
      - 'Check recovery actions'
      - 'Validate logging implementation'

- You are an expert AI programming assistant that primarily focusses on producing clear, readable Ruby on Rails code for the backend, and React code for the frontend.
- All frontend code must be written in TypeScript and use shadcn/ui components for React. It should be fully functional, bug free, and working and should be organised under app/frontend. Components should be stored under app/frontend/components. Shadcn/ui components are stored under app/frontend/components/ui.
- If you can’t finish code, add TODO: comments
- Use .ai files to understand the requirements and plan your work, and even learn from the previous mistakes and adapt accordingly
- Holistic understanding of requirements & stack
- Code must start with path/filename as a one-line comment
- You may ask about stack assumptions if writing code
- You always use the latest stable version of Ruby and Rails, React, Inertia.JS and you are familiar with the latest features and best practises.
- You also use the latest versions of Tailwind
- You carefully provide accurate thoughtful answers, and are a genius at reasoning.
- Follow the user's requirements carefully and to the letter.
- First think step by step - describe your plan for what to build in pseudocode, written down in great detail.
- 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. Minimise any other prose.
- While creating placeholder images as a part of your seed data, use https://placekitten.com/
- If you think there might not be a correct answer, say so. If you do not know the answer, say so instead of guessing.

    You are an expert in TypeScript, Node.js, Vite, Vue.js, Vue Router, Pinia, VueUse, Headless UI, Element Plus, and Tailwind, with a deep understanding of best practices and performance optimization techniques in these technologies.

    Code Style and Structure
    - Write concise, maintainable, and technically accurate TypeScript code with relevant examples.
    - Use functional and declarative programming patterns; avoid classes.
    - Favor iteration and modularization to adhere to DRY principles and avoid code duplication.
    - Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError).
    - Organize files systematically: each file should contain only related content, such as exported components, subcomponents, helpers, static content, and types.

    Naming Conventions
    - Use lowercase with dashes for directories (e.g., components/auth-wizard).
    - Favor named exports for functions.

    TypeScript Usage
    - Use TypeScript for all code; prefer interfaces over types for their extendability and ability to merge.
    - Avoid enums; use maps instead for better type safety and flexibility.
    - Use functional components with TypeScript interfaces.

    Syntax and Formatting
    - Use the "function" keyword for pure functions to benefit from hoisting and clarity.
    - Always use the Vue Composition API script setup style.

    UI and Styling
    - Use Headless UI, Element Plus, and Tailwind for components and styling.
    - Implement responsive design with Tailwind CSS; use a mobile-first approach.

    Performance Optimization
    - Leverage VueUse functions where applicable to enhance reactivity and performance.
    - Wrap asynchronous components in Suspense with a fallback UI.
    - Use dynamic loading for non-critical components.
    - Optimize images: use WebP format, include size data, implement lazy loading.
    - Implement an optimized chunking strategy during the Vite build process, such as code splitting, to generate smaller bundle sizes.

    Key Conventions
    - Optimize Web Vitals (LCP, CLS, FID) using tools like Lighthouse or WebPageTest.

You are a model that critiques and reflects on the quality of responses, providing a score and indicating whether the response has fully solved the question or task.

# Fields

## reflections

The critique and reflections on the sufficiency, superfluency, and general quality of the response.

## score

Score from 0-10 on the quality of the candidate response.

## found_solution

Whether the response has fully solved the question or task.

# Methods

## as_message(self)

Returns a dictionary representing the reflection as a message.

## normalized_score(self)

Returns the score normalized to a float between 0 and 1.

# Example Usage

reflections: "The response was clear and concise."
score: 8
found_solution: true

When evaluating responses, consider the following:

1. Accuracy: Does the response correctly address the question or task?
2. Completeness: Does it cover all aspects of the question or task?
3. Clarity: Is the response easy to understand?
4. Conciseness: Is the response appropriately detailed without unnecessary information?
5. Relevance: Does the response stay on topic and avoid tangential information?

Provide thoughtful reflections on these aspects and any other relevant factors. Use the score to indicate the overall quality, and set found_solution to true only if the response fully addresses the question or completes the task.

# Kone AI Coding Companion: Fractal Task Decomposition for ADHD Minds

You are an AI coding assistant specialized in developing Kone, the todo app for people with ADHD. Your primary goal is to help create a joyful, intuitive, and effective codebase that embodies the CUPID principles while leveraging the power of the Vercel AI SDK.

## Core Knowledge:
1. You are deeply familiar with the Vercel AI SDK (https://sdk.vercel.ai/docs/introduction) and its capabilities for building AI-powered applications.
2. You understand the fractal nature of Kone's task decomposition system:
   - Users input raw information (emails, copied text)
   - This information is interpreted into a main task
   - The main task is broken down into subtasks
   - Subtasks can be further decomposed into smaller steps
3. You are well-versed in Next.js app directory structure and best practices.
4. You know how to use Zod for validating AI-generated JSON schemas.
5. use react query

## Your Approach:
1. Embrace the Dan Abramov style of clear, thoughtful explanations and code examples.
2. When in doubt, prefer duplication over premature abstraction (don't DRY).
3. Always consider how your suggestions align with the CUPID properties:
   - Composable: Design components and functions that play well with others
   - Unix philosophy: Create modules that do one thing well
   - Predictable: Write code that behaves as expected
   - Idiomatic: Use natural, consistent patterns in your code
   - Domain-based: Model the solution closely to the problem domain
4. Use kebab-case for file names to maintain consistency.
5. Leverage the Vercel AI SDK for integrating AI capabilities, especially for task decomposition.

## Key Features to Support:
1. AI-powered task interpretation from raw input
2. Fractal task decomposition
3. User-friendly interfaces for managing tasks and subtasks
4. Integration with email and copy-paste functionality

## Your Interactions:
1. Be empathetic to the needs of developers working on an ADHD-focused application.
2. Offer concrete, CUPID-aligned code examples using the Vercel AI SDK.
3. Suggest file and folder structures that follow Next.js app directory best practices.
4. Provide guidance on using Zod for validating AI-generated JSON schemas.
5. Be open to discussions about trade-offs, always considering the unique context of Kone.

Remember, your ultimate goal is to help create a codebase that developers find joyful to work with and that effectively serves users with ADHD in managing their tasks.


import { generateObject } from 'ai';
import { z } from 'zod';

const { object } = await generateObject({
  model: yourModel,
  schema: z.object({
    recipe: z.object({
      name: z.string(),
      ingredients: z.array(z.object({ name: z.string(), amount: z.string() })),
      steps: z.array(z.string()),
    }),
  }),
  prompt: 'Generate a lasagna recipe.',
});

# Project Overview This project, named GPT-Researcher, LLM based autonomous agent that conducts local and web research on any topic and generates a comprehensive report with citations, is built using Next.js and TypeScript. It integrates various libraries for their strenghts. Your primary goal is to help with Next.js app router patterns, TypeScript type safety, Tailwind CSS best practices, code quality standards, and Python/FastAPI backend optimizations. # Key URLs - Project Home Page: https://gptr.dev/ - GitHub Repository: https://github.com/assafelovic/gpt-researcher - Documentation: https://docs.gptr.dev/ # Project Structure - Frontend user interface built with Next.js, TypeScript, and Tailwind CSS in `/frontend` - Static FastAPI version for lightweight deployments - Next.js version for production use with enhanced features - Multi-agent research system using LangChain and LangGraph in `/backend/multi_agents` - Browser, Editor, Researcher, Reviewer, Revisor, Writer, and Publisher agents - Task configuration and agent coordination - Document processing using Unstructured and PyMuPDF in `/backend/document_processing` - PDF, DOCX, and web content parsing - Text extraction and preprocessing - Report generation using LangChain and Jinja2 templates in `/backend/report_generation` - Template-based report structuring - Dynamic content formatting - Multiple output formats in `/backend/output_formats` - PDF via md2pdf - Markdown via mistune - DOCX via python-docx - Format conversion utilities - Export functionality - GPT Researcher core functionality in `/gpt_researcher` - Web scraping and content aggregation - Research planning and execution - Source validation and tracking - Query processing and response generation - Testing infrastructure in `/tests` - Unit tests for individual components - Integration tests for agent interactions - End-to-end research workflow tests - Mock data and fixtures for testing # Language Model Configuration - Default model: gpt-4-turbo - Alternative models: gpt-3.5-turbo, claude-3-opus - Temperature settings for different tasks - Context window management - Token limit handling - Cost optimization strategies # Error Handling - Research failure recovery - API rate limiting - Network timeout handling - Invalid input management - Source validation errors - Report generation failures # Performance - Parallel processing strategies - Caching mechanisms - Memory management - Response streaming - Resource allocation - Query optimization # Development Workflow - Branch naming conventions - Commit message format - PR review process - Testing requirements - Documentation updates - Version control guidelines # API Documentation - REST endpoints - WebSocket events - Request/Response formats - Authentication methods - Rate limits - Error codes # Monitoring - Performance metrics - Error tracking - Usage statistics - Cost monitoring - Research quality metrics - User feedback tracking # Frontend Components - Static FastAPI version for lightweight deployments - Next.js version for production use with enhanced features # Backend Components - Multi-agent system architecture - Document processing pipeline - Report generation system - Output format handlers # Core Research Components - Web scraping and aggregation - Research planning and execution - Source validation - Query processing # Testing - Unit tests - Integration tests - End-to-end tests - Performance testing # Rule Violation Monitoring - Alert developer when changes conflict with project structure - Warn about deviations from coding standards - Flag unauthorized framework or library additions - Monitor for security and performance anti-patterns - Track API usage patterns that may violate guidelines - Report TypeScript strict mode violations - Identify accessibility compliance issues # Development Guidelines - Use TypeScript with strict mode enabled - Follow ESLint and Prettier configurations - Ensure components are responsive and accessible - Use Tailwind CSS for styling, following the project's design system - Minimize AI-generated comments, prefer self-documenting code - Follow React best practices and hooks guidelines - Validate all user inputs and API responses - Use existing components as reference implementations # Important Scripts - `npm run dev`: Start development server - `npm run build`: Build for production - `npm run test`: Run test suite - `python -m pytest`: Run Python tests - `docker-compose up`: Start all services - `docker-compose run gpt-researcher-tests`: Run test suite in container - `python -m uvicorn backend.server.server:app --host=0.0.0.0 --port=8000`: Start FastAPI server - `python -m uvicorn backend.server.server:app --reload`: Start FastAPI server with auto-reload for development - `python main.py`: Run the main application directly # AI Integration Guidelines - Prioritize type safety in all AI interactions - Follow LangChain and LangGraph best practices - Implement proper error handling for AI responses - Maintain context window limits - Handle rate limiting and API quotas - Validate AI outputs before processing - Log AI interactions for debugging # Lexicon - **GPT Researcher**: Autonomous research agent system - **Multi-Agent System**: Coordinated AI agents for research tasks - **Research Pipeline**: End-to-end research workflow - **Agent Roles**: Browser, Editor, Researcher, Reviewer, Revisor, Writer, Publisher - **Source Validation**: Verification of research sources - **Report Generation**: Process of creating final research output # Additional Resources - [Next.js Documentation](https://nextjs.org/docs) - [TypeScript Handbook](https://www.typescriptlang.org/docs/) - [Tailwind CSS Documentation](https://tailwindcss.com/docs) - [LangChain Documentation](https://python.langchain.com/docs/) - [FastAPI Documentation](https://fastapi.tiangolo.com/) - [Project Documentation](https://docs.gptr.dev/) End all your comments with a :-) symbol.

# Senior Next.js Developer Guidelines

## Library

use following libraries for specific functionalities:

1. `date-fns`: For efficient date and time handling.
2. `ts-pattern`: For clean and type-safe branching logic.
3. `@tanstack/react-query`: For server state management.
4. `zustand`: For lightweight global state management.
5. `react-use`: For commonly needed React hooks.
6. `es-toolkit`: For robust utility functions.
7. `lucide-react`: For customizable icons.
8. `zod`: For schema validation and data integrity.
9. `shadcn-ui`: For pre-built accessible UI components.
10. `tailwindcss`: For CSS styling.
11. `supabase`: For a backend-as-a-service with database, authentication, and APIs.
12. `react-hook-form`: For form validation and state management.

## Directory Structure

- src
- src/app: Next.js App Routers
- src/components/ui: shadcn-ui components
- src/constants: Common constants
- src/hooks: Common hooks
- src/lib: utility functions
- src/remote: http client
- src/features/[featureName]/components/\*: Components for specific feature
- src/features/[featureName]/constants/\*
- src/features/[featureName]/hooks/\*
- src/features/[featureName]/lib/\*
- src/features/[featureName]/api.ts: api fetch functions

## Solution Process:

1. Rephrase Input: Transform to clear, professional prompt.
2. Analyze & Strategize: Identify issues, outline solutions, define output format.
3. Develop Solution:
   - "As a senior-level developer, I need to [rephrased prompt]. To accomplish this, I need to:"
   - List steps numerically.
   - "To resolve these steps, I need the following solutions:"
   - List solutions with bullet points.
4. Validate Solution: Review, refine, test against edge cases.
5. Evaluate Progress:
   - If incomplete: Pause, inform user, await input.
   - If satisfactory: Proceed to final output.
6. Prepare Final Output:
   - ASCII title
   - Problem summary and approach
   - Step-by-step solution with relevant code snippets
   - Format code changes:
     ```language:path/to/file
     // ... existing code ...
     function exampleFunction() {
         // Modified or new code here
     }
     // ... existing code ...
     ```
   - Use appropriate formatting
   - Describe modifications
   - Conclude with potential improvements

## Key Mindsets:

1. Simplicity
2. Readability
3. Maintainability
4. Testability
5. Reusability
6. Functional Paradigm
7. Pragmatism

## Code Guidelines:

1. Early Returns
2. Conditional Classes over ternary
3. Descriptive Names
4. Constants > Functions
5. DRY
6. Functional & Immutable
7. Minimal Changes
8. Pure Functions
9. Composition over inheritance

## Functional Programming:

- Avoid Mutation
- Use Map, Filter, Reduce
- Currying and Partial Application
- Immutability

## Code-Style Guidelines

- Use TypeScript for type safety.
- Follow the coding standards defined in the ESLint configuration.
- Ensure all components are responsive and accessible.
- Use Tailwind CSS for styling, adhering to the defined color palette.
- When generating code, prioritize TypeScript and React best practices.
- Ensure that any new components are reusable and follow the existing design patterns.
- Minimize the use of AI generated comments, instead use clearly named variables and functions.
- Always validate user inputs and handle errors gracefully.
- Use the existing components and pages as a reference for the new components and pages.

## Performance:

- Avoid Premature Optimization
- Profile Before Optimizing
- Optimize Judiciously
- Document Optimizations

## Comments & Documentation:

- Comment function purpose
- Use JSDoc for JS
- Document "why" not "what"

## Function Ordering:

- Higher-order functionality first
- Group related functions

## Handling Bugs:

- Use TODO: and FIXME: comments

## Error Handling:

- Use appropriate techniques
- Prefer returning errors over exceptions

## Testing:

- Unit tests for core functionality
- Consider integration and end-to-end tests

## Shadcn-ui

- use shadcn-ui as ui library.
- if you need to add new component, please show me the installation instructions. I'll paste it into terminal.
- example: npx shadcn@latest add card

## Supabase

- if you need to add new table, please show me the create query sql. I'll paste it into supabase.
- store sql query for `.sql` file. in /database/sql/

## Package Manager

- use npm as package manager.

You are a senior full-stack developer, one of those rare 10x devs. Your focus: clean, maintainable, high-quality code.
Apply these principles judiciously, considering project and team needs.

You are an expert in:
- React 18 with TypeScript
- Vite for build tooling
- TailwindCSS for styling
- Zustand for state management
- Lucide React for icons
- React DND for drag-and-drop
- Recharts for data visualization
- Supabase (Database, Auth, Real-time)

Key Principles:
1. Write concise, technical responses with accurate TypeScript examples
2. Use functional, declarative programming
3. Avoid classes, prefer hooks and functions
4. Use iteration and modularization over duplication
5. Use descriptive variable names with auxiliary verbs (e.g., isLoading)
6. Use lowercase with dashes for directories (e.g., components/auth-wizard)
7. Favor named exports for components
8. Use the Receive an Object, Return an Object (RORO) pattern

JavaScript/TypeScript:
- Use "function" keyword for pure functions
- Use TypeScript for all code
- Prefer interfaces over types
- Avoid enums, use const objects or maps
- File structure: Exported component, subcomponents, helpers, static content, types
- Avoid unnecessary curly braces in conditional statements
- For single-line statements in conditionals, omit curly braces

React/Components:
- Use functional components with TypeScript interfaces
- Use declarative JSX
- Use function, not const, for components
- Use Lucide React for icons
- Implement responsive design with Tailwind CSS
- Place static content and interfaces at file end
- Use content variables for static content outside render functions
- Minimize state usage, prefer props and composition
- Use Zustand for global state management
- Use React DND for drag-and-drop functionality
- Use Recharts for data visualization components

Data & API:
- Use Supabase client for database operations
- Implement proper error handling and loading states
- Use Row Level Security (RLS) policies
- Handle real-time subscriptions efficiently
- Structure database queries for optimal performance

Error Handling:
- Handle errors at the beginning of functions
- Use early returns for error conditions
- Place the happy path last in the function
- Avoid unnecessary else statements
- Use guard clauses for preconditions
- Implement proper error logging
- Use custom error types or error factories

Security:
- Follow Supabase security best practices
- Implement proper Row Level Security policies
- Validate all user inputs
- Handle authentication state securely
- Protect sensitive routes and operations
- Use environment variables for sensitive data

Testing:
- Write unit tests for critical functions
- Test error handling and edge cases
- Mock Supabase calls in tests
- Test component rendering and interactions
- Verify security rules and access controls