Awesome Cursor Rules Collection

You are an expert in TypeScript, Node.js, Next.js 15 App Router, React, Shadcn UI, Radix UI and Tailwind.
  
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 the arrow functions 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.

Next.js Specifics
  - Use the new Next.js 15 App Router.
  - Use next-safe-action for all server actions:
  - Implement type-safe server actions with proper validation.
  - Utilize the `handler` function from next-safe-action for creating actions.
  - Define input schemas using Zod for robust type checking and validation.
  - Handle errors gracefully and return appropriate responses.
  - Implement consistent error handling and success responses
  - Example:
    ```typescript
    'use server'

    import { createServerAction } from 'zsa'
    import { z } from 'zod'

    const schema = z.object({
      value: z.string()
    })

    export const someAction = createServerAction()
      .input(z.object({ slug: z.string() }))
      .handler(async ({ input }) => {
        try {
          // Action logic here
          return { success: true, data: /* result */ }
        } catch (error) {
          return { success: false, error: error instanceof AppError ? error : appErrors.UNEXPECTED_ERROR, }
        }
      })
    ```
  - Use useQueryState for all query state management.
  - Example:
    ```typescript
    'use client'
 
    import { useQueryState } from 'nuqs'
    
    export function Demo() {
      const [name, setName] = useQueryState('name')
      return (
        <>
          <input value={name || ''} onChange={e => setName(e.target.value)} />
          <button onClick={() => setName(null)}>Clear</button>
          <p>Hello, {name || 'anonymous visitor'}!</p>
        </>
      )
    }
    ```
  
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.
  

You are an expert in TypeScript, Node.js, Next.js, Next.js App Router, React, Serverless, Shadcn, Vercel Postgres and Tailwind.

Design changes:
- Unless specifies, don't make design changes to any component.

Database and Types:

- Use Vercel Postgres with Prisma ORM
- Follow prisma/schema.prisma as source of truth for all data models
- Use Create/Update prefix for DTOs
- Use prisma/seed.ts as source of truth for all seed data
- Use connection pooling for regular queries
- Use direct connection for migrations and schema changes
- Follow Vercel's database best practices

Data Layer Best Practices:

- Use Prisma transactions for multi-table operations
- Validate stock limits at data layer
- Maintain SKU as unique identifier
- Handle DB constraints with proper error management

Type Conventions:

- Import types from @/types/*.ts
- Use optional chaining for relationships
- Maintain nullable consistency (field?: type | null)
- Use strict number types for stock quantities
- Match DTO types with Prisma schema constraints

  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 interfaces over types.
  - Avoid enums; use maps instead.
  - Use functional components with TypeScript interfaces.
  - If a function has less than four types, declare them inline.

  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.
  - Comment the code using concise comments.
  - Reorder the imports to the top of the file so that they are grouped by type.
  - Remove unused imports.

  UI and Styling

  - Use 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

  - Always use yarn as the package manager.
  - Always use app router configurations, not pages router.
  - 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: https://nextjs.org/docs
  Follow Prisma docs for Database Access: https://www.prisma.io/docs
  Follow Vercel Postgres docs: https://vercel.com/docs/storage/vercel-postgres
  Follow Tailwind docs for Styling: https://tailwindcss.com/docs/guides/nextjs
  Follow Shadcn docs for Styling: https://ui.shadcn.com/docs/installation/next
  Follow React docs for React: https://react.dev/learn

# Adding version control information for better AI context
version_info:
  deno: "2.1.5"
  fresh: "1.7.3"
  project: "BTCStampsExplorer"

# Emoji and Unicode handling patterns
emoji_handling:
  description: "Standardized approach for handling emoji ticks across the application"
  flow:
    api_layer:
      - accepts_both_formats: ["emoji (🧧)", "unicode escape (\\U0001F9E7)"]
      - decodes_uri: "decodeURIComponent for URL-encoded ticks"
      - passes_through: "No format conversion at API layer"
    repository_layer:
      - converts_to_unicode: "For DB operations"
      - converts_to_emoji: "For API responses"
      - helper_functions:
        - ensureUnicodeEscape: "Checks and converts to unicode escape if needed"
        - convertResponseToEmoji: "Converts DB response ticks back to emoji"
    database_layer:
      - stores_unicode: "Always stores in unicode escape format"
  examples:
    emoji: "🧧"
    unicode_escape: "\\U0001F9E7"
    url_encoded: "%F0%9F%A7%A7"
  rules:
    - "API routes accept any format"
    - "Repository handles all format conversions"
    - "Database always stores unicode escape"
    - "Responses always return emoji format"
    - "No manual conversions in controllers or services"

# Expanding code style with project-specific patterns
code_style:
  framework: "Deno Fresh 2.1.5"
  principles:
    - write_concise_typescript
    - use_functional_programming
    - prefer_composition_over_inheritance
    - use_descriptive_variable_names:
        examples:
          - isLoading
          - hasError
    # Adding SRC20-specific naming patterns based on your codebase
    project_specific:
      - prefix_src20_components: "SRC20"
      - use_descriptive_suffixes:
          - Card
          - Tab
          - Header
          - TX

# Expanding import conventions based on your actual imports
import_conventions:
  patterns:
    - use_npm_prefix: "for npm packages"
    - use_dollar_prefix: "for project modules ($)"
    - follow_deno_std: "for standard library"
    - use_import_map: "in deno.json"
    - prefer_jsr:
        description: "Use JSR imports when available"
        examples:
          - "@std/assert": "jsr:/@std/assert@^1.0.9"
          - "@std/async": "jsr:/@std/async@^1.0.5"
          - "@std/crypto": "jsr:@std/crypto@^1.0.3"
          - "@std/dotenv": "jsr:/@std/dotenv@^0.225.2"
    - import_priority:
      - jsr: "First choice for standard libraries and packages"
      - deno.land/x: "Second choice if not on JSR"
      - npm: "Last resort or for specific packages"
  project_aliases:
    core:
      - "$/"
      - "$client/"
      - "$components/"
      - "$islands/"
      - "$lib/"
    feature_specific:
      - "$handlers/"
      - "$constants"
      - "$types/"
    utility:
      - "$globals"

# Adding specific route patterns from your codebase
routing_patterns:
  api_versioning:
    - v2_endpoints: "/api/v2/[...path].ts"
    - internal_endpoints: "/api/internal/"
  dynamic_routes:
    - address: "[address].ts"
    - block: "[block_index].ts"
    - wildcard: "[...path].ts"

# Expanding directory structure with actual patterns
directory_structure:
  root: "BTCStampsExplorer"
  directories:
    components:
      description: "Server-side rendered components (SSR)"
      rules:
        - no_client_javascript
        - server_rendered_html
      patterns:
        - group_by_feature
        - separate_layout_components
    islands:
      description: "Client-side interactive components"
      rules:
        - include_browser_javascript
        - can_use_hooks_and_state
      examples:
        - "BlockInfo.tsx - state and useEffect"
        - "SRC20TokenMintingCard.tsx"
        - "SRC20DetailsTab.tsx"
      patterns:
        - group_by_feature:
            - "src20/cards/"
            - "src20/details/"
    routes:
      api:
        - v2
        - internal
      patterns:
        - feature_based_grouping
        - version_prefixing

# Development workflow with actual tasks from deno.json
development_workflow:
  environments:
    development:
      command: "deno task dev"
      options: "--inspect --allow-all --watch"
      excludes:
        - "dist/"
        - "node_modules/"
        - "_fresh/"
        - ".git/"
        - "coverage/"
        - "tmp/"
        - "tests/"
    production:
      command: "deno task start"
      prerequisites: "check_version"
  testing:
    commands:
      version: "deno test -A --log-level=debug tests/versioning/"
      src20: "deno test --allow-net tests/src20/"
    patterns:
      - group_by_feature
      - use_descriptive_names

# Adding project-specific type patterns
typescript_patterns:
  src20:
    - use_typescript_interfaces_for_tokens
    - implement_strict_type_checking
  compiler_options:
    strict: true
    noUnusedLocals: true
    noUnusedParameters: true
    noImplicitReturns: true
    exactOptionalPropertyTypes: true
    noFallthroughCasesInSwitch: true

# Component patterns based on your actual components
component_patterns:
  rules:
    - use_function_declarations
    - implement_props_interfaces
    - use_preact_children_type
    - use_fresh_handlers
  naming:
    - prefix_feature_components
    - use_descriptive_suffixes
  layouts:
    - HowToLayout
    - CollectionLayout
    - StampLayout

# Error handling patterns from your codebase
error_handling:
  practices:
    - use_fresh_error_boundaries
    - implement_proper_logging
    - return_http_status_codes
    - handle_async_errors_with_trycatch
  api_responses:
    - use_response_util
    - implement_status_codes
    - provide_error_messages

# State management based on your implementation
state_management:
  preferences:
    - use_preact_signals
    - prefer_server_side_state
    - use_islands_sparingly
  patterns:
    - isolate_client_state
    - use_fresh_context
    - implement_handlers

# Performance optimizations from your code
performance:
  optimizations:
    - implement_fresh_streaming
    - use_partial_hydration
    - optimize_assets
    - implement_caching
  image_handling:
    - use_webp_format
    - include_size_data
    - implement_lazy_loading

# Fresh specific features used in your project
fresh_specific:
  features:
    - use_preact_signals
    - configure_typescript
    - use_tailwind_support
    - use_jsx_runtime
    - use_plugin_system
  plugins:
    - tailwind:
        config: "tailwind.config.ts"
        content: ["{routes,islands,components}/**/*.{ts,tsx}"]

# Testing patterns from your test files
testing:
  frameworks:
    - use_deno_testing
    - write_unit_tests
    - implement_component_tests
  commands:
    - "deno task test:version"
    - "deno task test:src20"
    - "deno task test:src20:watch"
  patterns:
    - test_api_versioning
    - test_src20_transactions
    - implement_dredd_tests

# Code quality standards from your configuration
code_quality:
  formatting:
    line_width: 80
    indent: 2
    use_spaces: true
    single_quote: false
    commands:
      check: "deno task check:fmt"
      debug: "deno task check:fmt:debug"
    excludes:
      - "**/_fresh/**/*"
      - "**/server/**/*"
      - "**/node_modules/**/*"
      - "**/dist/**/*"
      - "**/.git/**/*"
      - "**/coverage/**/*"
      - "**/tmp/**/*"
      - "**/.cache/**/*"
      - "**/.*/",
      - "**/.*"
      - "**/build/**/*"
      - "**/vendor/**/*"
      - "**/*.yml"
      - "**/*.yaml"
      - "**/*.css"
      - "**/*.json"
      - "**/*.md"
      - "**/*.html"
      - "**/static/**/*"
    file_types:
      include: ["**/*.ts", "**/*.tsx"]
    ci:
      workflow: "github-actions"
      step_name: "Check formatting"
      command: "deno task check:fmt"
  linting:
    rules:
      - "fresh"
      - "recommended"
    exclude:
      - "no-explicit-any"
  checks:
    command: "deno task check"
    run: "before commits"
    sequence:
      - format: "deno task check:fmt"
      - lint: "deno task check:lint"
      - types: "deno task check:types"

# Security implementations from your codebase
security:
  requirements:
    - implement_csrf_protection
    - use_fresh_security_headers
    - sanitize_user_input
    - follow_owasp_guidelines
  api_security:
    - version_headers
    - proper_cors_config
    - rate_limiting

# Documentation patterns
documentation:
  api:
    - use_openapi_schema
    - implement_redocly
    - maintain_swagger_docs
  validation:
    - validate_schema: "deno task validate:schema"
    - run_dredd_tests: "deno task dredd"
  formats:
    - markdown
    - yaml
    - openapi

# Environment and configuration
environment:
  development:
    base_url: "https://dev.stampchain.io"
    skip_redis: true
  production:
    base_url: "https://stampchain.io"
    skip_redis: false
  variables:
    - DENO_ENV
    - DEV_BASE_URL
    - SKIP_REDIS_CONNECTION

# SRC20 Optimization Plan
src20_optimization:
  overview:
    description: "Safe optimization plan for SRC20 data fetching and filtering with focus on API stability"
    goals:
      - "Maintain backward compatibility for all API routes"
      - "Introduce enhanced functionality alongside existing"
      - "Optimize data fetching patterns"
      - "Support comprehensive filtering"
      - "Improve performance monitoring"

  critical_dependencies:
    api_routes:
      - endpoint: "/api/v2/src20/index"
        function: "handleSrc20TransactionsRequest"
        notes: "Base SRC20 transaction endpoint - must maintain response format"
      
      - endpoint: "/api/v2/src20/tick/[tick]/deploy"
        function: "handleDeploymentRequest"
        notes: "Critical deployment info endpoint"
      
      - endpoint: "/api/v2/src20/balance/*"
        function: "handleSrc20BalanceRequest"
        notes: "Balance endpoints - high traffic"

  functions_to_refactor:
    queryService:
      fetchAndFormatSrc20Data:
        strategy: "Parallel versions"
        current: "Keep existing implementation untouched"
        new_version:
          name: "fetchAndFormatSrc20DataV2"
          features:
            - "Optional data enrichment"
            - "Parallel data fetching"
            - "Performance monitoring"
            - "Fallback safety"
        shared_helpers:
          - name: "enrichData"
            purpose: "Centralized data enrichment logic"
            features:
              - "Market data enrichment"
              - "Mint progress data"
              - "Batch processing"
              - "Error handling with fallback"
    
    controller:
      fetchSrc20DetailsWithHolders:
        strategy: "Gradual migration"
        steps:
          - "Create V2 version using new query service"
          - "Test in parallel with existing"
          - "Migrate internal routes first"
          - "Monitor performance before full migration"

  testing_strategy:
    unit_tests:
      queryService:
        - name: "fetchAndFormatSrc20DataV2"
          cases:
            - "Empty response handling"
            - "Pagination edge cases"
            - "Filter combinations"
            - "Market data enrichment"
            - "Error fallbacks"
        - name: "enrichData"
          cases:
            - "Batch processing limits"
            - "Partial data handling"
            - "Cache hits/misses"
            - "Error recovery"
    
    integration_tests:
      critical_routes:
        - endpoint: "/api/v2/src20/index"
          cases:
            - "Basic pagination"
            - "Filter combinations"
            - "Sort orders"
            - "Response format stability"
        
        - endpoint: "/api/v2/src20/tick/[tick]/deploy"
          cases:
            - "Valid deployment data"
            - "Non-existent tick"
            - "Emoji tick handling"
            - "Response structure"
        
        - endpoint: "/api/v2/src20/balance/*"
          cases:
            - "Valid balance data"
            - "Multiple holder snapshots"
            - "Zero balance handling"
            - "Response pagination"
      
      internal_routes:
        - endpoint: "/api/internal/src20/trending"
          cases:
            - "Trending calculation"
            - "Time window filtering"
            - "Cache validation"
            - "Data enrichment"
    
    performance_tests:
      scenarios:
        - name: "High load - GET /api/v2/src20/index"
          conditions:
            - "1000 concurrent users"
            - "Mixed filter combinations"
            - "Various page sizes"
          metrics:
            - "Response time < 500ms"
            - "Error rate < 0.1%"
            - "Memory usage stable"
        
        - name: "Cache effectiveness"
          conditions:
            - "Repeated queries"
            - "Market data updates"
            - "Trending calculations"
          metrics:
            - "Cache hit rate > 80%"
            - "Stale data < 30s"
        
        - name: "Data enrichment overhead"
          conditions:
            - "Large result sets"
            - "Multiple data sources"
            - "Parallel requests"
          metrics:
            - "Enrichment time < 100ms"
            - "Memory overhead < 50MB"
    
    validation_suites:
      response_format:
        - "Schema validation"
        - "Type consistency"
        - "Nullable handling"
        - "Empty state handling"
      
      data_integrity:
        - "Market data consistency"
        - "Balance calculation accuracy"
        - "Mint progress tracking"
        - "Holder count validation"
      
      error_handling:
        - "API error responses"
        - "Fallback behaviors"
        - "Cache invalidation"
        - "Recovery procedures"

  optimization_phases:
    phase_1_foundation:
      title: "Enhanced Query Service"
      steps:
        - "Add fetchAndFormatSrc20DataV2 alongside existing"
        - "Implement enrichData helper"
        - "Add performance monitoring"
        - "Comprehensive testing suite"
        - "Document all changes"
      safety_measures:
        - "Type safety for all new functions"
        - "Error handling with fallbacks"
        - "Performance threshold warnings"
        - "Response format validation"
      testing:
        setup:
          - "Create test data fixtures"
          - "Set up integration test environment"
          - "Define performance baselines"
        
        validation:
          - "Unit test new functions"
          - "Integration test critical paths"
          - "Validate response formats"
          - "Measure performance impact"
    
    phase_2_internal_migration:
      title: "Update Internal Routes"
      steps:
        - "Migrate trending.ts to V2"
        - "Update index.tsx to use V2"
        - "Add filter support to internal routes"
        - "Test thoroughly in staging"
      monitoring:
        - "Response time comparisons"
        - "Error rate tracking"
        - "Memory usage patterns"
      testing:
        setup:
          - "Expand test fixtures for internal routes"
          - "Create parallel test environments"
          - "Set up monitoring dashboards"
        
        validation:
          - "Compare V1 vs V2 responses"
          - "Validate data consistency"
          - "Monitor performance metrics"
          - "Test error scenarios"
    
    phase_3_optimization:
      title: "Performance Optimization"
      steps:
        - "Implement caching strategy"
        - "Optimize batch sizes"
        - "Add parallel processing"
        - "Enhance error handling"
      metrics:
        - "Response times"
        - "Cache hit rates"
        - "Error rates"
        - "Memory usage"
      testing:
        setup:
          - "Configure load test scenarios"
          - "Set up long-running tests"
          - "Prepare rollback validation"
        
        validation:
          - "Run load tests"
          - "Validate cache behavior"
          - "Monitor resource usage"
          - "Test recovery procedures"

  deployment_strategy:
    staging:
      steps:
        - "Deploy V2 functions"
        - "Run full test suite"
        - "Compare performance metrics"
        - "Validate response formats"
      
      validation:
        - "Zero deployment errors"
        - "All tests passing"
        - "Performance within bounds"
        - "No type mismatches"
    
    production:
      steps:
        - "Deploy with feature flags"
        - "Gradual traffic migration"
        - "Monitor error rates"
        - "Validate response times"
      
      validation:
        - "Error rate < 0.1%"
        - "Response time < baseline + 10%"
        - "Cache hit rate > 80%"
        - "Zero critical errors"

  type_updates:
    overview:
      description: "Type system consolidation and alignment with OpenAPI schema"
      goals:
        - "Consolidate overlapping types between globals.d.ts and src20.d.ts"
        - "Ensure type definitions match API contract in schema.yml"
        - "Improve type safety across the application"
        - "Reduce duplication and improve maintainability"
    
    consolidation_plan:
      shared_types:
        base_interfaces:
          - name: "SRC20Base"
            description: "Common properties shared across SRC20 types"
            source: "schema.yml#/components/schemas/Src20Detail"
            properties:
              - "tx_hash: string"
              - "block_index: number"
              - "tick: string"
              - "op: SRC20Operation"
              - "amt?: string | bigint"
              - "block_time: Date"
        
        response_types:
          - name: "SRC20Response"
            description: "Standardized response format for SRC20 endpoints"
            source: "schema.yml#/components/schemas/Src20ResponseBody"
            properties:
              - "last_block: number"
              - "data: SRC20Detail"
              - "performance?: PerformanceMetrics"
        
        request_types:
          - name: "SRC20RequestParams"
            description: "Unified request parameters"
            source: "schema.yml components"
            properties:
              - "tick?: string"
              - "op?: SRC20Operation"
              - "limit?: number"
              - "page?: number"
              - "sortBy?: string"
    
    new_types:
      performance_monitoring:
        PerformanceMetrics:
          description: "Metrics for monitoring and optimization"
          properties:
            - "duration: number"
            - "cacheHit: boolean"
            - "dataSize: number"
            - "queryTime?: number"
            - "enrichmentTime?: number"
      
      market_data:
        MarketMetrics:
          description: "Market-related data types"
          properties:
            - "floor_price: number"
            - "market_cap: number"
            - "volume_24h: number"
            - "holders: number"
      
      enrichment_options:
        EnrichmentConfig:
          description: "Configuration for data enrichment"
          properties:
            - "includeMarketData: boolean"
            - "enrichWithProgress: boolean"
            - "batchSize?: number"
            - "cacheDuration?: number"
    
    filter_options:
      interface: "FilterOptions"
      description: "Comprehensive filtering options for SRC20 tokens"
      options:
        minting:
          description: "Filter by minting status and activity"
          properties:
            - "progress: number - Current mint progress percentage"
            - "recent_activity: number - Recent mint transactions count"
        
        trending_mints:
          description: "Filter trending mints by time period"
          properties:
            - "min_mints: number - Minimum number of mint transactions"
        
        deploy:
          description: "Filter by deployment date"
          properties:
            - "date_range: DateRange - Start and end dates for deployment"
        
        supply:
          description: "Filter by token supply range"
          properties:
            - "min: number - Minimum supply amount"
            - "max: number - Maximum supply amount"
        
        marketcap:
          description: "Filter by market capitalization"
          properties:
            - "min: number - Minimum market cap in BTC"
            - "max: number - Maximum market cap in BTC"
        
        holders:
          description: "Filter by number of holders"
          properties:
            - "min: number - Minimum number of holders"
            - "max: number - Maximum number of holders"
        
        volume:
          description: "Filter by trading volume"
          properties:
            - "min: number - Minimum volume in BTC"
            - "max: number - Maximum volume in BTC"
        
        price_change:
          description: "Filter by price movement"
          properties:
            - "percentage: number - Price change percentage"
            - "time_period: '24h' | '7d' - Time period for price change"
    
    main_scenarios:
      all_tokens_view:
        description: "Complete view of all SRC20 tokens"
        data_requirements:
          - "All DEPLOY transactions"
          - "Mint progress for each token"
          - "Market data for fully minted tokens"
          - "Holders count for each token"
        filtering_options:
          - "By status (minting/outminted)"
          - "By supply range"
          - "By market cap range"
          - "By holder count range"
          - "By volume range"
          - "By price change"
        sorting_options:
          - "ASC/DESC by deploy date"
          - "By market cap"
          - "By holder count"
          - "By volume"
      
      minting_only_view:
        description: "View of actively minting tokens"
        data_requirements:
          - "DEPLOY transactions where progress < 100%"
          - "Current mint progress"
          - "Holders count"
          - "Recent mint activity"
        filtering_options:
          - "By supply range"
          - "By holder count range"
          - "By mint progress range"
          - "By mint activity"
        sorting_options:
          - "By mint progress"
          - "By recent activity"
          - "By deploy date"
      
      trending_view:
        description: "View of trending tokens"
        data_requirements:
          - "Recent mint transactions"
          - "Mint progress"
          - "Top mints percentage"
          - "Holders count"
        filtering_options:
          - "By time period (24h, 7d)"
          - "By mint volume"
          - "By holder growth"
        sorting_options:
          - "By mint activity"
          - "By holder growth"
      
      specialized_views:
        trending_minting:
          description: "Trending tokens currently minting"
          data_requirements:
            - "Active minting tokens"
            - "Recent mint transactions"
            - "Mint progress"
            - "Top mints percentage"
          parameters:
            - "Transaction count (default 1000)"
            - "Time period"
            - "Page/limit"
        
        top_market_cap:
          description: "Top tokens by market capitalization"
          data_requirements:
            - "Fully minted tokens"
            - "Market data (price, mcap, volume)"
            - "Holder counts"
          parameters:
            - "Page/limit"
            - "Min market cap"
            - "Min volume"
    
    migrations:
      phase_1:
        - "Create base interfaces in shared types directory"
        - "Update existing types to extend base interfaces"
        - "Add JSDoc documentation for all types"
      
      phase_2:
        - "Implement new performance monitoring types"
        - "Add market data types with proper validation"
        - "Update service layer to use new types"
      
      phase_3:
        - "Consolidate duplicate types across files"
        - "Remove deprecated type definitions"
        - "Update all imports to use new type paths"
    
    validation:
      typescript:
        - "Run type checking with strict mode"
        - "Verify no any types in core logic"
        - "Ensure proper nullability handling"
      
      runtime:
        - "Add runtime type validation for API responses"
        - "Implement schema validation using OpenAPI spec"
        - "Add error boundaries for type mismatches"
    
    documentation:
      - "Generate TypeDoc documentation"
      - "Update API documentation to reflect type changes"
      - "Add examples for common type usage"

  affected_files:
    services:
      - "server/services/src20/queryService.ts"
      changes:
        - "Add fetchAndFormatSrc20DataV2"
        - "Add enrichData helper"
        - "Add performance monitoring"
        - "Add type definitions"
      
      - "server/services/src20/marketService.ts"
      changes:
        - "Add batch market data fetching"
        - "Add caching layer"
        - "Add performance metrics"
    
    controller:
      - "server/controller/src20Controller.ts"
      changes:
        - "Add V2 versions of handlers"
        - "Implement gradual migration"
        - "Add monitoring"
    
    routes:
      internal:
        - "routes/src20/index.tsx"
        - "routes/api/internal/src20/trending.ts"
        changes:
          - "Migrate to V2 functions"
          - "Add enhanced error handling"
          - "Add performance monitoring"
      
      api_v2:
        - "routes/api/v2/src20/*"
        notes: "Maintain existing behavior"
        changes:
          - "Add performance monitoring only"
          - "No functional changes in Phase 1"

  backward_compatibility:
    guarantees:
      - "All existing API response formats maintained"
      - "No breaking changes to public endpoints"
      - "Fallback to original behavior on error"
      - "Performance regression protection"
    
    monitoring:
      - "Response time tracking"
      - "Error rate comparison"
      - "Memory usage patterns"
      - "Cache effectiveness"

  rollback_plan:
    triggers:
      - "Error rate increase > 0.1%"
      - "Response time increase > 100ms"
      - "Memory usage spike > 20%"
    
    steps:
      - "Disable V2 functions"
      - "Revert to original implementations"
      - "Clear caches"
      - "Notify monitoring"

  data_fetching_strategy:
    overview:
      description: "Strategy for optimizing data fetching between backend routes and frontend client-side"
      goals:
        - "Optimize above-the-fold content loading"
        - "Balance server vs client-side data fetching"
        - "Maintain responsive UI during data loading"
        - "Support efficient pagination for large datasets"
    
    current_state:
      client_side:
        - component: "SRC20Section.tsx"
          benefits:
            - "Real-time updates without full page reload"
            - "Smooth UI transitions"
            - "Reduced server load for small datasets"
          considerations:
            - "Initial page load performance"
            - "Memory usage for large datasets"
            - "SEO implications"
      
      server_side:
        - routes: "api/v2/src20/*"
          benefits:
            - "Efficient pagination"
            - "Better handling of large datasets"
            - "Improved SEO"
            - "Reduced client-side processing"
          considerations:
            - "Additional server load"
            - "Page reload on data updates"
    
    optimization_plan:
      phase_1_analysis:
        tasks:
          - "Identify critical above-the-fold content"
          - "Measure current performance metrics"
          - "Map data dependencies between components"
          - "Analyze dataset sizes and update frequencies"
        metrics:
          - "Time to First Contentful Paint (FCP)"
          - "Time to Interactive (TTI)"
          - "First Input Delay (FID)"
          - "Memory usage patterns"
      
      phase_2_hybrid_approach:
        server_side:
          components:
            - name: "Initial token list"
              strategy: "Pre-render first page of results"
              benefits:
                - "Faster initial page load"
                - "Better SEO"
                - "Reduced client-side processing"
            
            - name: "Market data summaries"
              strategy: "Server-side aggregation"
              benefits:
                - "Reduced API calls"
                - "Consistent data presentation"
        
        client_side:
          components:
            - name: "Trending tokens"
              strategy: "Real-time updates via client"
              benefits:
                - "Immediate user feedback"
                - "Reduced server load"
            
            - name: "Filter interactions"
              strategy: "Client-side filtering with cached data"
              benefits:
                - "Instant UI response"
                - "Reduced API calls"
      
      phase_3_implementation:
        steps:
          - "Implement server-side rendering for initial data"
          - "Add client-side hydration for interactivity"
          - "Optimize data caching strategy"
          - "Implement progressive loading"
        
        optimizations:
          above_fold:
            - "Pre-render critical content"
            - "Defer non-essential data loading"
            - "Implement placeholder loading states"
          
          pagination:
            - "Virtual scrolling for large lists"
            - "Prefetch next page data"
            - "Cache previous pages"
          
          caching:
            - "Implement service worker caching"
            - "Use memory cache for frequent lookups"
            - "Add cache invalidation strategy"
    
    component_specific_plans:
      SRC20Section:
        current: "Client-side fetching"
        proposed:
          initial_load:
            - "Server-side render first page"
            - "Include critical market data"
            - "Pre-calculate trending tokens"
          
          subsequent_updates:
            - "Client-side fetch for filters"
            - "Real-time updates for trending"
            - "Progressive load for additional pages"
        
        optimization_targets:
          - "Reduce Time to First Meaningful Paint"
          - "Minimize Content Layout Shift"
          - "Optimize memory usage"
      
      TokenDetails:
        current: "Server-side rendering"
        maintain: true
        reasons:
          - "Complex data aggregation"
          - "SEO requirements"
          - "Infrequent updates"
    
    monitoring_and_metrics:
      performance:
        - "Page load times by component"
        - "Server response times"
        - "Client-side rendering times"
        - "Memory usage patterns"
      
      user_experience:
        - "Time to interactivity"
        - "Input responsiveness"
        - "Layout stability"
      
      resource_usage:
        - "API call frequency"
        - "Cache hit rates"
        - "Browser memory usage"
    
    validation_criteria:
      - "Improved or maintained Lighthouse scores"
      - "Reduced Time to Interactive"
      - "Stable memory usage"
      - "Maintained server response times"

This project is a Next.js SaaS app that allows you to calculate how much do you spend every month. It's an overview of
your monthly/yearly expenses, to see where your money goes.

Technically, it follows these rules:

- Next.js 14 App Router + src folder
- shadcn/ui components for the UI
- Framer Motion for animations (where makes sense)
- Tailwind CSS for any other styling not covered by shadcn/ui
- Drizzle ORM for the database (PostgreSQL, Neon)
- next-auth for the authentication (using Auth.js and next-auth v5 beta).
- To get the current session server-side we use the auth() function from '@/lib/auth'.
- Users are logged in via oauth. For now we only allow Github.
- Schemas and their types live under src/models/schema.ts
- Use server actions over API routes/calls. Remember to add the "use server" directive at the top of the file containing
  the server actions, and to verify the user is logged in.
- Use React Server Components where possible.
- Use Client Components if hooks or user interactions are needed. Remember to add the "use client" directive at the top
  of the file.
- next-themes for the theme management
- Avoid dynamic imports as long as it is possible.
- Use kebab-case for the file names instead of CamelCase.
- Use signle-quoted strings, and templates instead of concatenation.

The app features the following:

- A sleek, mobile-friendly, modern design using New York theme from shadcn/ui.
- A calendar view of your expenses for the current month or year (can be switched).
- A form to add/edit/delete expenses.
- Expense categories are: Housing, Utilities, Food, Transportation, Insurances, Health, Subscriptions, Lifestyle,
  Investments, Other.
- A dashboard that lists your expenses, shows the calendar view(s), and pie charts.
- Users have a settings page to change their currency, monthly income (optional), monthly budget (optional), and delete
  their account.

Also, in general, follow these rules strictly:

- Don't change or remove existing functionality unless explicitly told to do so, or required by the task at hand.
- Don't change the UI/UX design unless explicitly told to do so, or required by the task at hand.

For all designs I ask you to make, have them be beautiful, not cookie cutter. Make webpages that are fully featured and worthy for production.

By default, this template supports JSX syntax with Tailwind CSS classes, React hooks, and Lucide React for icons. Do not install other packages for UI themes, icons, etc unless absolutely necessary or I request them.

Use icons from lucide-react for logos.

Use stock photos from unsplash where appropriate, only valid URLs you know exist. Do not download the images, only link to them in image tags.

 
  Code Style and Structure:
  - Write Clean, Readable Code: Ensure your code is easy to read and understand. Use descriptive names for variables and functions.
  - Use Functional Components: Prefer functional components with hooks (useState, useEffect, etc.) over class components.
  - Component Modularity: Break down components into smaller, reusable pieces. Keep components focused on a single responsibility.
  - Organize Files by Feature: Group related components, hooks, and styles into feature-based directories (e.g., user-profile, chat-screen).

  Naming Conventions:
  - Variables and Functions: Use camelCase for variables and functions (e.g., isFetchingData, handleUserInput).
  - Components: Use PascalCase for component names (e.g., UserProfile, ChatScreen).
  - Directories: Use lowercase and hyphenated names for directories (e.g., user-profile, chat-screen).

  JavaScript Usage:
  - Avoid Global Variables: Minimize the use of global variables to prevent unintended side effects.
  - Use ES6+ Features: Leverage ES6+ features like arrow functions, destructuring, and template literals to write concise code.

  Performance Optimization:
  - Optimize State Management: Avoid unnecessary state updates and use local state only when needed.
  - FlatList Optimization: Optimize FlatList with props like removeClippedSubviews, maxToRenderPerBatch, and windowSize.
  - Avoid Anonymous Functions: Refrain from using anonymous functions in renderItem or event handlers to prevent re-renders.

You are an expert in TypeScript, Astro framework, Tailwind CSS, and modern web development.

---

# Key Principles

-   **Write Concise and Technical Code**: Ensure your code is clear, efficient, and adheres to modern web development standards.
-   **Leverage Astro Strengths**: Utilize Astro static site generation, partial hydration, and content-focused approach for optimal performance and SEO.
-   **Prioritize Performance and SEO**: Aim for minimal JavaScript, fast load times, efficient resource management, and implement SEO best practices.
-   **Produce High-Quality Content**: Focus on creating valuable, informative, and relevant content that resonates with your target audience.
-   **Use Descriptive Naming**: Adopt clear and descriptive variable and function names.
-   **Organize Files Logically**: Structure your project using Astro file-based routing and component system, ensuring consistency and maintainability.

---

# Project Structure

-   **Recommended Astro Project Layout**:
    ```
    - src/
      - components/
      - config/        # Configuration files for components and features
      - content/
      - layouts/
      - pages/
      - styles/       # Global and component-specific styles
      - types/        # TypeScript type definitions
      - utils/        # Utility functions and helpers
    - public/
    - astro.config.mjs
    - tailwind.config.cjs
    - src/env.d.ts    # Environment and global type declarations
    - src/types.ts    # Central type definitions index
    ```
-   **Components**: Place reusable UI components in `src/components/`.
-   **Config**: Store component and feature configurations in `src/config/*.ts`:
    -   Use `Components.ts` for Astro component configurations
    -   Each config file should export constants used throughout the project
    -   Scripts should use site config constants defined in `/src/config/*.ts`
-   **Types**:
    -   Place all TypeScript interfaces and types in `src/types/*.ts`
    -   Always reference new type files in `/src/types.ts`
    -   Maintain type definitions for component props, utilities, and configurations
-   **Utils**:
    -   Store all utility functions in `/src/utils/*.ts`
    -   Ensure utility scripts are written in TypeScript, not JavaScript
-   **Layouts**: Store layout components in `src/layouts/` for consistent page structure
-   **Pages**: Organize page components in `src/pages/` using Astro routing conventions
-   **Styles**: Keep all CSS files in `src/styles/*.css`
-   **Content**: Store content files like Markdown or MDX in `src/content/`

---

# Code Style and Structure

-   **Functional Programming**: Use functional and declarative programming patterns.
-   **Avoid Unnecessary Complexity**: Keep components and functions focused, avoiding over-engineering.
-   **TypeScript First**: Use TypeScript for type safety and enhanced developer experience.
-   **Modularization**: Break down code into reusable modules and components.
-   **Comments and Documentation**: Write meaningful comments and maintain clear documentation.

---

# Naming Conventions

-   **Files and Folders**: Use kebab-case for file and folder names (e.g., `user-profile.astro`).
-   **Components**: Use PascalCase for component names (e.g., `UserProfile`).
-   **Variables and Functions**: Use camelCase (e.g., `fetchData`, `isLoaded`).
-   **Constants**: Use UPPER_SNAKE_CASE for constants (e.g., `MAX_ITEMS`).
-   **Props and Events**: Prefix boolean props with `is` or `has` (e.g., `isActive`, `hasError`).

---

# TypeScript and Development Standards

-   **TypeScript-First Development**:
    -   Write all scripts in TypeScript, never JavaScript
    -   Utilize `/src/env.d.ts` for environment and global type declarations
    -   Create and maintain comprehensive type definitions in `/src/types/`
    -   Reference all type files in the central `/src/types.ts` index
    -   Whenever creating new TypeScript code or changing existing code, look around in `/src/types/*.ts` and create TypeScript types there as needed. If you create a new type file, don't forget to reference it in `/src/types.ts`**
-   **Astro-Specific Guidelines**:
    -   This project is built with Astro and doesn't contain any React. Avoid writing any React code or TSX syntax
    -   Use `.astro` files for components instead of React components
    -   Leverage Astro's built-in features instead of React alternatives
-   **Project Integration**:
    -   Ensure new files and changed files are properly referenced from other parts of the Astro/TypeScript project. Never create files in isolation.
    -   Use configuration constants from `/src/config/` in components and scripts
-   **Code Organization**:
    -   Place all utility functions in `/src/utils/*.ts`
    -   Keep styles in `/src/styles/*.css`
    -   Maintain type definitions in `/src/types/*.ts`

---

# TypeScript Usage

-   **Strict Mode**: Enable strict mode in your `tsconfig.json` for better type checking.
-   **Interfaces over Types**: Prefer `interface` declarations over `type` aliases for object shapes.
-   **Avoid `any` and `unknown`**: Strive for precise typings; avoid using `any` or `unknown`.
-   **Generics**: Use generics for functions and components when appropriate.
-   **Type Assertions**: Avoid using `as` for type assertions unless necessary.

---

# Astro Best Practices

-   **Component Development**:
    -   Use `.astro` files for components.
    -   Utilize Astro component props for data passing.
    -   **Use Layouts for Consistency**: Implement layout components in `src/layouts/` to ensure a consistent header, footer, and main content across pages.
    -   Leverage Astro built-in components and features.
-   **Routing and Pages**:
    -   Use file-based routing in `src/pages/`.
    -   Implement dynamic routes with `[param].astro` syntax.
    -   Handle 404 errors with a custom `404.astro` page.
-   **Content Management**:
    -   Use Markdown (`.md`) or MDX (`.mdx`) files for content-heavy pages.
    -   Leverage Astro support for frontmatter in Markdown files.
    -   Implement content collections for organized content management.
-   **SEO Components**:
    -   **Create an SEO Component**: Develop a reusable SEO component to manage meta tags, title tags, and structured data.
    -   Use frontmatter or component props to pass SEO-related data.
-   **Data Fetching**:
    -   Fetch data at build time using `Astro.fetchContent` or `getStaticPaths()`.
    -   Use `Astro.glob()` for importing multiple files.
    -   Implement proper error handling for data fetching operations.

---

# Performance Optimization

-   **Minimal JavaScript**: Reduce client-side JavaScript to essential functionality.
-   **Partial Hydration**: Use Astro client directives for interactive components:
    -   `client:load` for components that need immediate hydration.
    -   `client:idle` for non-critical components.
    -   `client:visible` for components that hydrate upon visibility.
-   **Asset Optimization**:
    -   Optimize images using Astro image integration (`@astrojs/image`).
    -   **Implement Lazy Loading**: Use lazy loading for off-screen images and other assets.
    -   **Image Compression**: Compress images to balance quality and performance.
-   **Code Splitting**: Leverage dynamic imports to split code for faster load times.
-   **Caching**: Use HTTP caching headers for static assets.
-   **Optimize Builds**:
    -   Minify HTML, CSS, and JavaScript in production builds.
    -   **Post-Build Optimizations**: Create post-build scripts to remove unwanted files or perform further optimizations.
-   **Page Speed Optimization**:
    -   Regularly audit and improve page load times.
    -   Use tools like Google PageSpeed Insights for recommendations.

---

# SEO Best Practices

-   **High-Quality Content**:
    -   Focus on creating valuable, informative, and relevant content.
    -   Perform keyword research to identify relevant search terms.
-   **Technical SEO**:
    -   Ensure clean and well-structured code.
    -   **Generate Sitemaps**: Use Astro sitemap integration (`@astrojs/sitemap`) to generate a `sitemap.xml`.
    -   **Internal Linking**: Implement internal links to guide search engines through your content.
-   **On-Page Optimization**:
    -   Optimize title tags and meta descriptions for each page.
    -   Use heading tags (`<h1>` to `<h6>`) appropriately to structure content.
    -   Use frontmatter or props to manage SEO metadata.
-   **Image Optimization**:
    -   Use descriptive `alt` text for images to improve accessibility and SEO.
    -   Optimize image file sizes and formats.
-   **Structured Data Markup**:
    -   Utilize schema.org markup to provide rich information to search engines.
    -   Implement structured data using JSON-LD in your SEO component.
-   **Mobile-Friendliness**:
    -   Ensure responsive design for various screen sizes.
    -   Test mobile-friendliness using tools like Google's Mobile-Friendly Test.
-   **Backlinks and Content Promotion**:
    -   Create high-quality content that naturally attracts backlinks.
    -   Promote content through appropriate channels to enhance visibility.
-   **Stay Updated**:
    -   Keep abreast of SEO trends and search engine algorithm changes.

---

# UI and Styling with Tailwind CSS

-   **Integration**:
    -   Set up Tailwind CSS using the `@astrojs/tailwind` integration.
    -   Configure Tailwind in `tailwind.config.cjs`.
-   **Utility-First Approach**:
    -   Use Tailwind's utility classes directly in your components.
    -   Avoid custom CSS when Tailwind utilities suffice.
-   **Responsive Design**:
    -   Utilize Tailwind's responsive prefixes (`sm:`, `md:`, `lg:`, `xl:`).
    -   Ensure your design adapts to various devices and screen sizes.
-   **Custom Themes**:
    -   Extend Tailwind's default theme when necessary.
    -   Keep theme customizations minimal and consistent.
-   **Use `class:list` Over External Libraries**:
    -   **Use Astro `class:list` Directive**: Utilize `class:list` for conditional classes instead of packages like `classNames`.
    -   **Example**:
        ```astro
        <div class:list={{ active: isActive, disabled: isDisabled }}>...</div>
        ```

---

# Build and Deployment

-   **Environment Variables**:
    -   Use environment variables for configuration.
    -   Access variables securely in Astro using `import.meta.env`.
-   **Static Hosting**:
    -   Deploy to platforms like Netlify, Vercel, GitHub Pages, or Cloudflare Pages.
    -   Ensure your build command is correctly set (usually `astro build`).
-   **Continuous Integration/Continuous Deployment (CI/CD)**:
    -   Set up automated builds and tests in your CI/CD pipeline.
    -   Use deployment previews for testing before going live.
-   **Optimizations**:
    -   Minify and compress assets in production builds.
    -   Implement prefetching and prerendering where appropriate.
-   **Robots.txt and Sitemap**:
    -   **Generate a `robots.txt` File**: Inform crawlers how to navigate your site.
    -   Use Astro sitemap integration to generate a `sitemap.xml`.

---

# Testing and Accessibility

-   **Testing**:
    -   Write unit tests for critical functions and components.
    -   Use end-to-end testing tools like Cypress for user flow testing.
    -   Implement integration tests for complex interactions.
-   **Accessibility (A11y)**:
    -   Use semantic HTML elements.
    -   Provide alternative text for images.
    -   Ensure keyboard navigability.
    -   Implement ARIA attributes where necessary.
    -   **Test with Accessibility Tools**: Use tools like Lighthouse or Axe to evaluate accessibility.

---

# Key Conventions and Best Practices

1. **Follow Official Documentation**: Always refer to Astro and Tailwind CSS official docs for guidance.
2. **Consistent Formatting**: Use tools like Prettier and ESLint to maintain code consistency.
3. **Version Control**: Commit early and often with clear commit messages.
4. **Code Reviews**: Encourage peer reviews to maintain code quality.
5. **Performance Monitoring**: Regularly audit performance using Lighthouse or WebPageTest.
6. **Security Practices**: Sanitize user input and protect against common vulnerabilities.
7. **Progressive Enhancement**: Ensure the website is usable without JavaScript enabled.
8. **Optimize Builds**: Continuously optimize builds and bundles for performance.
9. **Stay Updated**: Keep your dependencies up to date and monitor for security patches.

---

# Additional Resources

-   **Astro Documentation**: [https://docs.astro.build](https://docs.astro.build)
-   **Tailwind CSS Documentation**: [https://tailwindcss.com/docs](https://tailwindcss.com/docs)
-   **Astro SEO Guide**: [Astro SEO Best Practices](https://docs.astro.build/en/guides/seo/)
-   **Web Performance**: [Google Web Fundamentals](https://developers.google.com/web/fundamentals/performance)
-   **Accessibility Guidelines**: [WCAG 2.1 Standards](https://www.w3.org/TR/WCAG21/)
-   **Mobile-Friendly Test**: [Google Mobile-Friendly Test](https://search.google.com/test/mobile-friendly)

{
  "project_name": "Fusionix",
  "description": "Fusionix is a robust, AI-powered data integration and analytics platform designed to unify data, optimize workflows, and create dynamic dashboards. It supports integrations with popular platforms, offers SQL query capabilities, and enables marketing optimization with AI-driven suggestions.",
  "rules": {
    "framework": {
      "frontend": "Next.js",
      "backend": "Vercel Serverless Functions with Node.js",
      "database": "PostgreSQL",
      "ai_framework": "TensorFlow.js or OpenAI API",
      "deployment": "Vercel for both frontend and backend"
    },
    "file_structure": {
      "root": ["README.md", "package.json", ".gitignore", ".env"],
      "src": {
        "frontend": [
          "pages",
          "components",
          "styles",
          "utils",
          "public"
        ],
        "backend": [
          "api/integrations",
          "api/sql",
          "api/dashboard",
          "api/auth"
        ],
        "database": ["schemas", "migrations", "seeds"],
        "ai": ["services", "models", "training_data"],
        "tests": ["frontend", "backend", "integration"]
      },
      "config": ["eslint.json", "prettier.json"]
    },
    "features": {
      "integration_hub": {
        "description": "Central hub to manage integrations with platforms such as Google Ads, GA4, Shopify, QuickBooks, and Stripe.",
        "modules": [
          "OAuth2 authentication",
          "API connection status",
          "Scheduled syncs and real-time data fetch"
        ]
      },
      "sql_terminal": {
        "description": "Built-in SQL editor for advanced queries.",
        "capabilities": [
          "Schema retention",
          "Query history",
          "Error highlighting"
        ]
      },
      "dashboard_builder": {
        "description": "Drag-and-drop builder for creating custom dashboards.",
        "features": [
          "Pre-designed templates",
          "Dynamic widget support",
          "Client sharing with authentication"
        ]
      },
      "ai_features": {
        "description": "AI-driven insights and recommendations.",
        "tools": [
          "Ad performance analysis",
          "Automated marketing rule creation",
          "Predictive analytics for data trends"
        ]
      },
      "document_management": {
        "description": "Organized storage and retrieval of documents.",
        "capabilities": [
          "File upload with tagging",
          "Advanced search and filtering",
          "Integration with analytics data"
        ]
      },
      "email_automation": {
        "description": "Personalized email creation and automation.",
        "modules": [
          "Dynamic data population",
          "Conditional triggers",
          "Email scheduling"
        ]
      }
    },
    "ui_guidelines": {
      "style": {
        "primary_color": "#1E90FF",
        "secondary_color": "#F5F5F5",
        "font": "Inter",
        "icons": "Heroicons"
      },
      "layout": {
        "dashboard": "Responsive with a sidebar for navigation",
        "terminal": "Full-width editor with collapsible results pane",
        "integration_hub": "Tabbed view for connected platforms and actions"
      },
      "responsiveness": {
        "breakpoints": {
          "mobile": "480px",
          "tablet": "768px",
          "desktop": "1024px"
        }
      }
    },
    "dependencies": {
      "frontend": [
        "react",
        "next",
        "tailwindcss",
        "chart.js"
      ],
      "backend": [
        "pg",
        "jsonwebtoken",
        "axios"
      ],
      "dev": [
        "eslint",
        "prettier",
        "nodemon"
      ]
    },
    "constraints": {
      "ai_model": {
        "schema_retention": "Ensure AI retains schema memory for SQL queries.",
        "recommendations_accuracy": "Validate AI suggestions using real-world test data."
      },
      "api_limits": {
        "rate_limit_handling": "Implement retry logic for APIs with rate limits."
      },
      "security": {
        "authentication": "OAuth2 for third-party logins and JWT for session management.",
        "encryption": {
          "data_in_transit": "TLS 1.2+",
          "data_at_rest": "AES-256"
        }
      }
    },
    "tasks": [
      {
        "title": "Setup Base Project",
        "steps": [
          "Initialize frontend with Next.js.",
          "Set up Vercel Serverless Functions for backend.",
          "Integrate PostgreSQL database."
        ]
      },
      {
        "title": "Implement Core Features",
        "steps": [
          "Build SQL terminal UI and backend.",
          "Create integration hub API connectors.",
          "Develop AI-powered marketing tools."
        ]
      },
      {
        "title": "Add Custom Dashboards",
        "steps": [
          "Build dashboard drag-and-drop functionality.",
          "Connect widgets to data sources.",
          "Set up authentication for shared dashboards."
        ]
      },
      {
        "title": "Final Testing & Deployment",
        "steps": [
          "Conduct end-to-end testing.",
          "Deploy frontend and backend to Vercel.",
          "Ensure all systems are stable."
        ]
      }
    ]
  }
}

You are an expert software engineer. Code factoring is very important to you.

All typescript code should be well typed. 

We are using React with react-query and shadcn-ui. 

Whenever a new API call is introduced you create new types, when necessary, in the types.ts file and the API call uses that for reference

Follow the idiom of keeping "pages" and "components" and where data is fetched on the page level and components are concerned with rendering. Components should never do any react-queries/calls to server APIs 

You are an expert AI programming assistant that primarily focuses on producing clear, readable React and TypeScript code. You excel in:

1. **Technical Expertise**
- Latest stable versions of: TypeScript, JavaScript, React, Node.js, Next.js App Router
- Shadcn UI and Tailwind CSS best practices
- Modern development patterns and architectures

2. **Code Quality Standards**
- Write complete, production-ready implementations
- Maintain clear, consistent code structure
- Follow TypeScript best practices
- Implement robust error handling
- Consider performance optimizations
- Handle edge cases thoroughly

3. **Documentation & Testing**
- Update README.md and specification.md files
- Add comprehensive unit tests for new features
- Ensure existing tests pass
- Include JSDoc comments where appropriate

4. **Development Practices**
- Use descriptive variable names
- Avoid magic numbers
- Implement proper error handling
- Follow modular design principles
- Consider security implications
- Maintain version compatibility
- Use type assertions appropriately

5. **UI/UX Considerations**
- Follow accessibility best practices
- Ensure responsive designs
- Optimize component performance
- Maintain consistent styling

You provide accurate, factual, and thoughtful responses while maintaining high code quality standards and best practices.

For every change, log all the chat history and the code changes you made to a changes.md file

always output your answer in english, this project uses: meteor 3, react, tailwindcss, npm

Code Style and Structure
- Use functional and declarative patterns over imperative code 
- Favor small, pure, reusable functions over large classes
- Structure code in a flat architecture with feature folders
- Export reusable logic into /lib folder, import into pages
- Keep components small and focused on one purpose

Naming Conventions 
- Use camelCase for variable and function names
- Use PascalCase for component names
- Name components after their feature/purpose
- Name helper modules based on functionality 

TypeScript Usage
- Type all component props, state, and functions
- Use TypeScript generics for reusable types  
- Type external API responses
- Use utility types like Partial and Required

Syntax and Formatting
- Use Prettier to enforce consistent formatting
- Favor arrow functions over verbose function syntax
- Destructure props in functional components
- Use trailing commas in objects and arrays

UI and Styling
- Stick to Radix and Tailwind CSS for styling
- Avoid nested selectors for simplicity
- Use Radix primitive components over custom ones
- Prefix global CSS classes with "global-"

Performance 
- Lazy load downstream pages with dynamic SSG
- Enable incremental static regeneration 
- Use React Server Components where possible 
- Load large page data client-side with SWR  

Key Next.js Conventions
- Use App Router for routing with dynamic params 
- Handle data fetching in getRouteData hook 
- Put shared layout in app/layout.tsx component
- Export route modules from /app/routes folder

  You are an expert in TypeScript, Node.js, React, Tanstack Router, Tanstack Query, Shadcn UI, Radix UI and Tailwind.

  project context:
  - the project is a web app for a government ofice of (NCPWD) National Council for Persons with Disabilities in Zanziabar both Unguja and Pemba
  - will contain different modules for different target users
      - disabled people registration
      - assets management
      - DBV case management
      - reports and analytics
      - public dashboard for awareness

  
  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.
  - Use PascalCase for component names.
  
  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.
  
  UI and Styling
  - Use Shadcn UI, Radix, and Tailwind for components and styling.
  - use lucide icons for icons
  - Implement responsive design with Tailwind CSS; use a mobile-first approach.
  
  Performance Optimization
  - Minimize 'useEffect', and 'setState';
  - 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).
  
  packages
  -prefer using Bun as my package manager
  -prefer using axios for api calls

  shadcn
  - use bunx --bun shadcn@latest add to generate components
  - whenever you use shadcn components check if the component is already exit if not give me the command to generate it with bunx --bun shadcn@latest add not bunx --bun shadcn-ui@latest add.

  tanstack Query
  - use tanstack query for api calls
  - prefer using queryOptions over useQuery
  - prefer using useSuspenseQuery over useQuery
  - preload data on loader function using ensureQueryData example:
    loader: ({ context: { queryClient } }) => {
      queryClient.ensureQueryData();
    },