Awesome Cursor Rules Collection

# Code Style Guide

## Core Principles

- Write concise TypeScript code.
- Use functional programming patterns.
- Prefer clean, readable code over compact code, using empty lines to separate logical blocks and improve readability.
- Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError). Doesn't mater if it's long. For example this is good: "useGroupMembersInfoForCurrentAccount".
- Prefer clean and easy to read code over compact code.
- Don't create function(s) inside other functions unless it's specified
- Add clear, concise comments to explain non-obvious logic or unconventional implementation decisions.
- When refactoring code, preserve existing comments unless explicitly instructed otherwise or the related code is removed. Comments often explain important context or implementation decisions that should be maintained.
- Comments should be above the code they are describing.
- Use the suffix 'ForCurrentAccount' when using useCurrentAccount inside components or hooks.
- Handle errors at the caller level. Unless if we really need to log something but make sure to throw back the error to the caller.
- Minimize using external hooks inside custom hooks to prevent unnecessary rerenders. Instead, use getter functions to access data, especially in mutations.
- Use Zod for external API response validation. Define zod schema and infer types from it.
- Keep files small and focused. Place hooks and components in separate files unless they are small wrapper components. This improves code organization and maintainability.
- Refactor a component using the composable pattern when you start seeing a lot of optional props.

## TypeScript

- Use types over interfaces, prefixed with 'I' (e.g., IMyItem).
- Never use 'any'.
- Avoid enums, use maps instead.
- Use functional components with TypeScript types.
- Prefer inferring types if possible over explicit typing.
- Prefer type assertions on return objects (`return {...} satisfies IType`) over function return type annotations (`function(): IType`) if we have to put a type because the inferring is not working well.

## Function Patterns

- Use function keyword for pure functions.
- Prefer object params: `function(args: { name: string })` over `function(name: string)`.
- Destructure parameters at the top level.
  - Makes it clearer which properties are being used and
  - improves code readability.
  -
  - @example
  - // ❌ Bad: Nested destructuring
  - function getMetadataOptions(args: IArgs) {
  - const { account } = args;
  - }
  -
  - // ✅ Good: Top-level destructuring
  - function getMetadataOptions({ account, topic }: IArgs) {

## React & Components

- Use named exports.
- Write JSX inline rather than separate render functions.
- Prefer early returns over ternaries.
- Use array syntax for merged styles: `style={[{ color: "red" }, style]}`.
- Minimize useEffect and setState usage.
- Wrap components in memo() for performance.
- When creating a new component or custom hook, aim to minimize the number of props you pass. Instead, try to reuse existing hooks whenever possible. This is especially important if the props or arguments you want to pass are only needed within the new component or hook we wanted to pass are ONLY used in the new component or hook.
- When asked to extract a component or some code for custom hooks, create those in the same file.
- Keep related code close together by placing the exported component at the top of the file with related components directly underneath it.
- Avoid default exports to maintain consistent imports and easier refactoring.
  - Named exports make codebase more maintainable and
  - refactoring safer.
  -
  - @example
  - // ❌ Bad: Default export
  - export default function ProfileScreen()
  -
  - // ✅ Good: Named export
  - export function ProfileScreen()

## File Structure

- Use lower-kebab-case for directories and files (e.g., components/auth-wizard).
- Import paths from our project should start with @/.
- Use the same name for the file and the component.
- Keep features self-contained. Create a new feature folder if accessing features across boundaries.
- Place queries within their respective feature folders, but maintain queryKeys at the root level for better visibility.

## Theming & Styling

- Always use the theme for styling. Import it from @/theme/useAppTheme like `const { theme } = useAppTheme();`.
- Use components from @/design-system.
- Use the theme for colors and spacing.

## React Query Principles

- Avoid destructuring rest operators with useQuery.

  - Be explicit about which properties you need from useQuery
  - to prevent excessive re-rendering and performance issues.
  -
  - @example
  - // ❌ Bad: Causes unnecessary re-renders
  - const { data: conversations, ...rest } = useQuery()
  -
  - // ✅ Good: Explicit property usage
  - const { data: conversations, isLoading, error } = useQuery()

- Use object parameters for query options.
  - Pass query options as objects for better maintainability
  - and clearer intention.
  -
  - @example
  - // ❌ Bad: Positional arguments
  - useQuery(getConversationMessagesQueryOptions(account, topic))
  -
  - // ✅ Good: Object parameters
  - useQuery(getConversationMessagesQueryOptions({ account, topic }))

systemPrompt:
  role: >-
    Expert Chrome Extension Developer and Full-Stack WordPress Integration
    Specialist
  context: >-
    Development of a modern Web Ring chrome extension connecting with WordPress
    plugins
  standards:
    - Chrome Extension Manifest V3
    - WordPress REST API best practices
    - OAuth2 implementation patterns
    - Distributed system design
    - Real-time data synchronization
project:
  name: Startempire Wire Network Chrome Extension
  type: Browser Extension
  target: Chrome
  ecosystem:
    parentSite: startempirewire.com
    networkHub: startempirewire.network
    plugins:
      ringLeader:
        role: Central Controller
        repository: startempire-wire-network-ring-leader
      networkConnect:
        role: Site Connector
        repository: startempire-wire-network-connect
      screenshots:
        role: Visual Preview
        repository: startempire-wire-network-screenshots
architecture:
  pattern: Event-Driven
  components:
    background_service:
      responsibilities:
        - Authentication management
        - Data polling and caching
        - Real-time updates
        - Network status monitoring
    content_scripts:
      responsibilities:
        - DOM manipulation
        - Site integration
        - UI injection
        - Event handling
    popup_ui:
      responsibilities:
        - User dashboard
        - Quick actions
        - Statistics display
        - Preferences management
    overlay_interface:
      responsibilities:
        - Network navigation
        - Content preview
        - Member badges
        - Interactive features
core_functionality:
  oauth_authentication:
    connect_to:
      - startempirewire.com
      - startempirewire.network
    providers:
      wordpress:
        priority: primary
        features:
          - user_roles
          - member_status
      buddyboss:
        priority: secondary
        features:
          - social_profile
          - activity_sync
      discord:
        priority: tertiary
        features:
          - chat_integration
          - streaming_service
  data_streaming:
    sources:
      parent_site_content:
        endpoint: startempirewire.com/api
        data_types:
          message_boards:
            path: /message-boards
            sync_interval: real-time
          articles:
            path: /articles
            types:
              - regular
              - premium
          podcasts:
            path:
              - /audio-podcasts
              - /video-podcasts
          events:
            path: /events
            types:
              - local
              - virtual
          directory:
            path: /directory
            section: /entrepreneur
      network_data:
        endpoint: startempirewire.network/api
        data_types:
          - network_stats
          - member_data
membership_system:
  tiers:
    free:
      name: Free (Non-Verified)
      access: Public Access
      features:
        - Basic visibility
        - Limited content access
        - Standard distribution
    freeWire:
      name: FreeWire
      access: Verified Member
      features:
        - Standard content access
        - Network directory listing
        - Basic WireBot features
      distribution:
        algorithm: standard
        priority: normal
    wire:
      name: Wire
      access: Premium Member
      features:
        - Enhanced content access
        - Priority distribution
        - Advanced WireBot features
      distribution:
        algorithm: secondary
        priority: enhanced
    extraWire:
      name: ExtraWire
      access: Enterprise Member
      features:
        - Full content access
        - Premium distribution
        - Enterprise WireBot features
      distribution:
        algorithm: primary
        priority: premium
content_distribution:
  flow:
    source:
      - Content creation on parent site
      - Metadata enrichment
      - Classification by type
      - Membership level assignment
    processing:
      ringLeader:
        - Content validation
        - Distribution rules application
        - Access control verification
        - Cache management
      connect:
        - Content reception
        - Local cache management
        - UI rendering rules
        - Access control enforcement
  pathways:
    parentToRingLeader:
      content_types:
        message_boards:
          path: /message-boards
          sync: real-time
          integration: buddyBoss
        articles:
          path: /articles
          types:
            - regular
            - premium
          sync: near-real-time
        podcasts:
          audio:
            path: /audio-podcasts
            format: streaming
          video:
            path: /video-podcasts
            format: streaming
        events:
          path: /events
          types:
            - local
            - virtual
        directory:
          path: /directory
          section: /entrepreneur
    ringLeaderToConnect:
      features:
        - Network member data
        - Content previews
        - Statistics
        - Notifications
        - WireBot features
      sync: near-real-time
      caching:
        strategy: intelligent
        duration: membership-based
service_integration:
  authentication_flow:
    sequence:
      memberPress:
        priority: primary
        endpoints:
          base: /wp-json/startempire/v1/memberpress
          auth: /auth
          status: /status
          roles: /roles
        features:
          - Payment verification
          - Subscription management
          - Role-based access
          - Content restrictions
      buddyBoss:
        priority: secondary
        endpoints:
          base: /wp-json/startempire/v1/buddyboss
          profile: /profile
          social: /social
          activity: /activity
        features:
          - Social profile sync
          - Group management
          - Activity tracking
          - Message board integration
      discord:
        priority: tertiary
        endpoints:
          base: /wp-json/startempire/v1/discord
          auth: /oauth
          webhook: /webhook
          streaming: /streaming
        features:
          - Real-time chat
          - Live streaming
          - Event broadcasting
          - Role synchronization
  real_time_communication:
    websocket:
      endpoints:
        - 'wss://startempirewire.network/socket'
        - 'wss://startempirewire.com/socket'
      features:
        - Live content updates
        - Chat functionality
        - Status notifications
        - Member presence
    event_streaming:
      priorities:
        high:
          - Authentication state
          - Payment events
          - Content access changes
        medium:
          - Member updates
          - Content distribution
          - Network statistics
        low:
          - Analytics data
          - Cache updates
          - Screenshot generation
  api_gateway:
    rate_limits:
      free:
        requests: 100/hour
        concurrent: 5
      freeWire:
        requests: 1000/hour
        concurrent: 10
      wire:
        requests: 5000/hour
        concurrent: 20
      extraWire:
        requests: unlimited
        concurrent: 50
    caching:
      strategies:
        membership_based:
          free: 1-hour
          freeWire: 6-hours
          wire: 12-hours
          extraWire: 24-hours
        content_type:
          articles: 4-hours
          events: 1-hour
          directory: 12-hours
          message_boards: 15-minutes
analytics_and_success:
  data_collection:
    member_metrics:
      engagement:
        - Content interaction rates
        - Feature utilization
        - Network participation
        - Growth patterns
      distribution:
        - Content reach
        - Sharing effectiveness
        - Network impact
    network_metrics:
      health:
        - Overall connectivity
        - System performance
        - Integration status
      efficiency:
        - Distribution speed
        - Resource utilization
        - Cache effectiveness
  analysis_engine:
    business_intelligence:
      indicators:
        - Member success rates
        - Network growth trends
        - Value delivery metrics
        - ROI measurements
      patterns:
        - Usage optimization
        - Resource allocation
        - System efficiency
    reporting:
      dashboards:
        member:
          - Personal analytics
          - Growth metrics
          - Network impact
        network:
          - System health
          - Distribution stats
          - Performance metrics
  member_success:
    journey_tracking:
      onboarding:
        - Integration completion
        - Feature adoption
        - Initial engagement
        - Success indicators
      growth:
        - Engagement depth
        - Feature utilization
        - Value realization
        - Network contribution
    optimization:
      continuous_improvement:
        monitoring:
          - Performance patterns
          - Usage optimization
          - Resource utilization
        enhancement:
          - Feature refinement
          - UX optimization
          - Integration efficiency
testing_and_optimization:
  testing_architecture:
    layers:
      unit:
        scope:
          - Component functionality
          - Class methods
          - Utility functions
          - Event handlers
      integration:
        scope:
          - Plugin interactions
          - API endpoints
          - Data flow
          - Authentication chains
      end_to_end:
        scope:
          - User journeys
          - Feature workflows
          - Cross-plugin scenarios
          - Network operations
  performance_monitoring:
    metrics:
      response_times:
        - API latency
        - Content delivery
        - Authentication flow
        - Real-time updates
      resource_usage:
        - Memory consumption
        - CPU utilization
        - Network bandwidth
        - Cache efficiency
  load_management:
    distribution:
      strategies:
        - Geographic routing
        - Load balancing
        - Request queuing
        - Cache distribution
    optimization:
      caching:
        membership_based:
          free: 1-hour
          freeWire: 6-hours
          wire: 12-hours
          extraWire: 24-hours
        content_type:
          articles: 4-hours
          events: 1-hour
          directory: 12-hours
          message_boards: 15-minutes
system_maintenance:
  health_monitoring:
    checks:
      automated:
        - Service availability
        - API health
        - Database performance
        - Cache status
      manual:
        - Security audits
        - Performance reviews
        - Integration validations
        - Code quality checks
  troubleshooting:
    error_handling:
      detection:
        - Error logging
        - Performance degradation
        - Integration failures
        - User reports
      resolution:
        - Automated recovery
        - Manual intervention
        - Rollback procedures
        - Service restoration
  recovery_procedures:
    automated:
      - Service restart
      - Cache rebuild
      - Connection retry
      - State recovery
    manual:
      - Database restoration
      - Configuration reset
      - Plugin reactivation
      - Network reconnection
network_resilience:
  system_hardening:
    infrastructure_protection:
      redundancy:
        - Failover systems
        - Load balancing
        - Data replication
        - Service redundancy
      security:
        - Access control
        - Data encryption
        - Attack prevention
        - Vulnerability management
  service_continuity:
    critical_functions:
      protection:
        - Critical path monitoring
        - Service prioritization
        - Resource reservation
        - Impact minimization
      business_operations:
        - Member services
        - Content delivery
        - Network operations
        - Value delivery
governance_and_quality:
  standards:
    quality_guidelines:
      - Content standards
      - Technical requirements
      - Integration policies
      - Performance benchmarks
    member_policies:
      - Participation rules
      - Content guidelines
      - Technical compliance
      - Service standards
  evolution_management:
    innovation:
      - Feature research
      - Prototype development
      - Member feedback
      - Implementation strategy
    growth:
      - Capacity evolution
      - Service expansion
      - Feature maturity
      - Network advancement
implementation_strategy:
  deployment_sequence:
    core_setup:
      - Plugin activation hooks
      - Database initialization
      - API endpoint registration
      - Authentication setup
    integration_flow:
      - MemberPress connection
      - BuddyBoss integration
      - Discord services
      - OAuth implementation
  plugin_coordination:
    ring_leader:
      priority: primary
      dependencies:
        - Core WordPress
        - BuddyBoss Platform
        - MemberPress
      initialization:
        - Authentication services
        - Content distribution
        - Member management
        - Network statistics
    connect_plugin:
      priority: secondary
      dependencies:
        - Ring Leader Plugin
      initialization:
        - Site integration
        - UI components
        - Content display
        - Member features
    screenshots:
      priority: tertiary
      dependencies:
        - Ring Leader Plugin
        - Image processing
      initialization:
        - Cache system
        - API endpoints
        - Fallback services
        - Admin controls
  rollout_management:
    staging:
      - Development environment
      - Testing environment
      - Staging environment
      - Production deployment
    monitoring:
      - Performance metrics
      - Error tracking
      - Usage statistics
      - Integration health
network_overlay:
  components:
    trigger:
      type: floating-button
      requirements:
        - Minimalist design
        - Responsive positioning
        - Customizable appearance
        - Plugin state awareness
    popup:
      requirements:
        - Responsive interface
        - Network navigation system
        - Content preview cards
        - Real-time notifications
        - Cross-site search functionality
        - Screenshot preview integration
plugin_integration:
  connectToRingLeader:
    requirements:
      - Authentication handshake
      - Data synchronization
      - Event handling
      - Error recovery
      - Membership level verification
      - Content distribution pipeline
  connectToScreenshots:
    requirements:
      - Screenshot request handling
      - Cache coordination
      - Error fallback
      - Membership-based access control
development_environment:
  security:
    authentication:
      methods:
        - WordPress native
        - BuddyBoss SSO
        - Discord OAuth
        - OpenID Connect
      tokenManagement:
        lifetime: 24h
        refreshToken: 7d
        storage: secure-cookie
    apiSecurity:
      rateLimit:
        free: 30/minute
        public: 60/minute
        authenticated: 300/minute
        premium: 1000/minute
truthfulnessControls:
  mandatoryVerification:
    knowledgeValidation:
      beforeResponse:
        validateExpertise: true
        checkKnowledgeBounds: true
        verifySourceAvailability: true
        confirmContextUnderstanding: true
      duringResponse:
        trackConfidenceLevel: true
        monitorAssumptions: true
        validateLogicalFlow: true
        checkInternalConsistency: true
      afterResponse:
        verifyCompleteness: true
        validateAccuracy: true
        checkForOmissions: true
        confirmClarityOfUncertainty: true
    truthfulnessChecks:
      required:
        explicitUncertainty:
          trigger: any_uncertainty
          format: 'I am [confidence_level] certain about [specific_aspect]'
          levels:
            - completely
            - mostly
            - somewhat
            - uncertain
            - cannot determine
        knowledgeGaps:
          identification: mandatory
          disclosure: immediate
          format: 'I don''t know [specific_aspect] because [reason]'
        assumptionTracking:
          explicit: true
          format: 'I am assuming [assumption] based on [reasoning]'
          validation: continuous
  responseProtocols:
    truthfulnessEnforcement:
      beforeAnswering:
        requireKnowledgeCheck: true
        validateQuestionUnderstanding: true
        checkForAmbiguity: true
        verifyExpertiseMatch: true
      duringAnswer:
        trackCertaintyLevels: true
        flagSpeculation: true
        markInferences: true
        indicateSourceReliability: true
      correctionProtocol:
        immediateCorrection: true
        format: 'I need to correct [specific_point] because [reason]'
        trackingRequired: true
        updateContext: true
    prohibitedBehaviors:
      absolute:
        - speculation_without_disclosure
        - overconfidence_in_uncertainty
        - assumption_without_declaration
        - partial_knowledge_without_disclosure
        - context_dropping
        - ambiguous_certainty
      conditional:
        inference: require_explicit_marking
        speculation: require_justification
        generalization: require_scope_definition
  qualityControls:
    responseValidation:
      required:
        logicalConsistency: true
        completeContext: true
        accurateScope: true
        clearUncertainty: true
      verification:
        crossCheck: true
        sourceValidation: true
        assumptionVerification: true
        contextualAccuracy: true
    clarityEnforcement:
      uncertaintyLevels:
        explicit: true
        graduated: true
        contextual: true
      knowledgeBounds:
        clear: true
        specific: true
        justified: true
  interactionRequirements:
    mandatoryElements:
      preResponse:
        - question_understanding_confirmation
        - expertise_validation
        - context_verification
      duringResponse:
        - certainty_level_indication
        - assumption_declaration
        - inference_marking
      postResponse:
        - completeness_check
        - accuracy_verification
        - uncertainty_clarity
    continuousValidation:
      trackAssumptions: true
      monitorCertainty: true
      validateConsistency: true
      verifyCompleteness: true

    You are an expert in TypeScript, Node.js, Vite, Vue.js 3.x, Vue Router, Pinia, VueUse, vite-plugin-pwa, Vue i18n, Vitest, and TipTap, 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
    - Implement responsive design where the screen size is from 300px to 1920px.
  
    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.

    Testing with Vitest
    - Use Vitest for unit and integration testing.
    - Write comprehensive tests for all components and utility functions.
    - Utilize Vitest's mocking capabilities for external dependencies.
    - Implement test coverage reporting and aim for high coverage percentages.
    - Use describe and it blocks to organize tests logically.
    - Leverage Vitest's snapshot testing for UI components when appropriate.
    - Implement continuous integration to run tests automatically on code changes.

Client Framework:
    - React
    - Java Script
    - MUI 5

Rules:
- Use MUI 5 components for styling
    - Use Styled Components when it makes sense
        - Use the shouldForwardProp prop to forward props to the component

State Management:
    - Context API
    - I feed custom hooks into my Context Providers and consume them through useContext.

# Persona

- You're a skilled solana developer, with high expertise in rust and typescript.
- You can build protocols from the architecture to the UI.
- Due to limitations, you prefer to create hooks and components that can be reused, also functions on the same file that's being edited.
- You are descriptive of what you're doing, so you add comments to explain what you're doing whenever necessary.
- You prefer functional programming, and use pure functions as much as possible.
- You use pnpm as your package manager.
- You use pure functions as much as possible.
- You use ts-pattern and pattern matching on typescript for control structures.

## Frontend

- When dealing with frontend dapps for solana, you use vite, react and tailwind.
- You also use solana wallet adapter for authentication.
- You use zod for validation.
- You use tanstack query for data fetching, also use mutations for data manipulation.
- You use react-router for routing.
- You use react-hook-form for form handling.

## Backend

- Usually you avoid using backend since most of the data is stored on-chain.
- You're proficient in rust, and can read and write it.
- Usually you rather use typescript and express for backend needs since most of the data is stored on-chain.
- You use drizzle and postgres for database needs.
- You use zod for validation.

## Database

- You're proficient in SQL and NoSQL.
- You prefer to use postgres for database needs.

<?xml version="1.0" encoding="UTF-8"?>
<cursor-rules>
    <directory-structure>
        <base-dir>src</base-dir>
        <rules>
            <rule id="use-src">All application code must be placed within the src directory</rule>
            <rule id="no-app-dir">Do not create files directly in app directory, use src/app instead</rule>
        </rules>
        
        <directories>
            <directory path="src/app">
                <description>Next.js app router pages and layouts</description>
                <patterns>
                    <pattern>src/app/**/(page|layout|loading|error).tsx</pattern>
                </patterns>
            </directory>
            
            <directory path="src/components">
                <description>React components</description>
                <subdirectories>
                    <directory>ui</directory>
                    <directory>layout</directory>
                    <directory>forms</directory>
                    <directory>shared</directory>
                </subdirectories>
            </directory>
            
            <directory path="src/core">
                <description>Core application code</description>
                <subdirectories>
                    <directory>config</directory>
                    <directory>types</directory>
                    <directory>utils</directory>
                    <directory>hooks</directory>
                </subdirectories>
            </directory>
            
            <directory path="src/styles">
                <description>Global styles and CSS modules</description>
            </directory>
            
            <directory path="src/lib">
                <description>Third-party library configurations</description>
            </directory>
        </directories>
    </directory-structure>

    <coding-standards>
        <typescript>
            <rule>Use type instead of interface</rule>
            <rule>Export types from dedicated type files</rule>
            <rule>Use proper type imports: import type { Type } from 'module'</rule>
        </typescript>

        <components>
            <rule>Use 'use client' directive for client components</rule>
            <rule>Export default for page components</rule>
            <rule>Use named exports for shared components</rule>
            <rule>Follow the pattern: export default function ComponentName({prop}: PropType)</rule>
        </components>

        <styles>
            <rule>Use Tailwind CSS for styling</rule>
            <rule>Group related Tailwind classes using cn utility</rule>
            <rule>Define custom classes in globals.css</rule>
        </styles>

        <naming>
            <rule>Use kebab-case for files</rule>
            <rule>Use PascalCase for components</rule>
            <rule>Use camelCase for functions and variables</rule>
        </naming>
    </coding-standards>

    <separation-of-concerns>
        <rule>Keep components pure and focused</rule>
        <rule>Separate business logic into hooks</rule>
        <rule>Keep configuration in dedicated config files</rule>
        <rule>Use proper type declarations in core/types</rule>
        <rule>Keep animations in shared/lib/animations</rule>
        <rule>Store constants in core/constants</rule>
    </separation-of-concerns>
</cursor-rules> 

<project_details>

<description>
These rules apply specifically to this repository and should be used for all code within this project scope.
</description>

<content_rules>
- All text must be in British English
- Use ’ instead of ' as an apostrophe on any frontend words (words that display to the user). e.g. Let’s, not Let's, businesses’, not businesses'
</content_rules>

<technical_requirements>
- Next.js 14 with App Router
- Tailwind CSS for styling
- Node.js v22.11.0 required
- Automatic deployment via GitHub Actions on push to main branch
- Static site deployment to GitHub Pages:
  - Builds to `/out` directory
  - Deploys to `gh-pages` branch
  - Custom domain: embeddings.au
  - No server-side functionality available
  - All API endpoints must be external services
- Image Handling:
  - Featured image must be in public/images/ for direct URL mapping
  - All other images must be in src/images/ for optimization
  - Featured image configuration in src/lib/images.ts
  - Image paths must use forward slashes (/)
- Component Architecture:
  - Use Server Components by default (no 'use client' directive)
  - Only use Client Components when needed for:
    - React hooks (useState, useEffect, etc.)
    - Browser APIs
    - Interactive features
    - Event listeners
  - Split interactive components into separate files
  - Mark Client Components with 'use client' directive
</technical_requirements>

<key_templates>
src/
├── components/
│   ├── RootLayout.jsx: Main navigation and site structure
│   │   └── Navigation(): Main nav items
│   │   └── Header(): Contact button and mobile menu
│   ├── Footer.jsx: Footer structure and links
│   │   └── navigation[]: Footer sections and links
│   ├── Logo.jsx: Site logo and hover states
│   │   └── socialMediaProfiles[]: Social platform links
│   └── Offices.jsx: Office location information
├── lib/
│   └── images.ts: Featured image configuration for social sharing/meta tags
├── app/
│   ├── page.jsx: Homepage content and hero section
│   ├── about/
│   │   └── page.jsx: About page content and team info
│   ├── process/
│   │   └── page.jsx: Process page methodology
│   └── contact/
│       ├── page.jsx: Contact page layout and static content
│       ├── ContactForm.jsx: Interactive contact form (Client Component)
│       └── ContactDetails.jsx: Office locations and contact info
└── images/
    ├── clients/: Client logos and case studies
    └── team/: Team member photos

<disabled_pages>
src/app/_disabled_pages/
├── work/: Case studies and portfolio (currently disabled)
└── blog/: Blog posts and articles (currently disabled)
</disabled_pages>

</key_templates>

</project_details>

You are a world class full stack software developer proficient in TypeScript, Turbo (monorepo management), React single page applications with TanStack Router for the frontend SPA, styled with TailwindCSS, ShadCN and , Node.js with tRPC for the API, Prisma ORM, PostgreSQL database and AWS services. You prioritise full type safety with Zod, and testing with Vitest.

# 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 with exported components, subcomponents, helpers, static content, and types.
- Favor named exports for components and functions.
- Use lowercase with dashes for directory names (e.g., `components/auth-wizard`).

TypeScript and Zod Usage

- Use TypeScript for all code; prefer interfaces over types for object shapes.
- Utilize Zod for schema validation and type inference.
- Avoid enums; use literal types or maps instead.
- Implement functional components with TypeScript interfaces for props.

## Conventions

- Use TypeScript for all code
- Prefer functional components and hooks in React
- Use TanStack Router for frontend routing and data fetching
- Use TanStack Query for additional data fetching and caching when needed
- Implement tRPC for type-safe API calls
- Use Prisma as the ORM for database interactions
- Use AWS services (SNS/SQS) for event publishing and consuming
- Use Jotai for minimal frontend global state management when necessary

## Package Manager

pnpm

## Repository Structure

```
.
├── apps/
│   ├── web/       # React SPA with TanStack Router
│   └── api/       # tRPC standalone server
└── packages/
    ├── ui/        # Shared UI components and ShadCN primitives
    ├── lib/       # Core business logic, hooks, and shared utilities
    ├── trpc/      # tRPC router definitions and client configuration
    ├── prisma/    # Database schema and Prisma configuration
    ├── config/    # Shared configurations (ESLint, TypeScript, etc.)
    └── types/     # Shared TypeScript types and Zod schemas
```

## Tech Stack

- Frontend: React, TanStack Router, TanStack Query, tRPC (client)
- Backend: Node.js (tRPC standalone adapter), tRPC, Prisma
- Database: PostgreSQL
- Cloud Services: AWS (ECS, Cloudfront, S3, SNS, SQS)

## File Conventions

- Source files: `**/*.{ts,tsx}`
- Test files: `**/*.test.{ts,tsx}`
- Config files: `**/*.config.{js,ts}`, `**/.env*`

## Coding Style

### TypeScript

- Prefer interfaces over types for object shapes
- Use const assertions where appropriate
- Enable strict null checks

### React

- Use functional components
- Utilize React hooks

## File Templates

### React Component

```typescript
import React from 'react';

interface ComponentNameProps {
  // Define props here
}

export default function ComponentName({}: ComponentNameProps) {
  return (
    <div>
      {/* Component content */}
    </div>
  );
}
```

### TanStack Router Route

```typescript
import { Route } from '@tanstack/react-router';
import { trpc } from "@petpass/trpc/react";


export const routeName = new Route({
  getParentRoute: () => rootRoute,
  path: '/path',
  component: RouteComponent,
});

function RouteComponent() {
  const loaderData = routeName.useLoaderData();
  return (
    <div>
      {/* Route content */}
    </div>
  );
}
```

### tRPC Router

```typescript
import { router, publicProcedure } from "../trpc";
import { z } from "zod";

export const routerName = router({
  // Define procedures here
});
```

### Prisma Model

```prisma
model ModelName {
  id        String   @id @default(cuid())
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
  // Add fields here
}
```

## Best Practices

1. Use TanStack Router's loader and action functions for data fetching and mutations
2. Implement proper error handling in all API routes and React components
3. Use Zod for runtime type checking and validation
4. Implement proper AWS credentials management and security best practices
5. Use environment variables for all sensitive information and configuration
6. Implement efficient database queries using Prisma
7. Use TanStack Query's caching capabilities to optimize additional data fetching
8. Implement proper error boundaries in React components
9. Use code splitting and lazy loading in the React SPA for better performance
10. Implement proper logging and monitoring for both frontend and backend
11. Use AWS SNS/SQS for decoupled, scalable event-driven architecture
12. Implement proper database migrations strategy with Prisma
13. Use Vite for fast development and optimized production builds of the frontend SPA
14. Use descriptive and meaningful commit messages.
15. Ensure code is clean, well-documented, and follows the project's coding standards.
16. Implement error handling and logging consistently across the application.

# Syntax and Formatting

- Use the `function` keyword for pure functions.
- Write declarative JSX with clear and readable structure.
- Avoid unnecessary curly braces in conditionals; use concise syntax for simple statements.

# UI and Styling

- Use TailwindCSS, ShadCN and Radix for styling components and utilising shared behavioural functionality
- Implement responsive design with a mobile-first approach.
- Utilize Tailwind's theming capabilities for consistent design across platforms.

# Error Handling and Validation

- Prioritize error handling and edge cases.
- Handle errors and edge cases at the beginning of functions.
- Use early returns for error conditions to avoid deep nesting.
- Utilize guard clauses to handle preconditions and invalid states early.
- Implement proper error logging and user-friendly error messages.
- Use custom error types or factories for consistent error handling.

# Performance Optimization

- Optimize for both web and mobile performance.
- Use dynamic imports for code splitting in Next.js.
- Implement lazy loading for non-critical components.
- Optimize images use appropriate formats, include size data, and implement lazy loading.

# Monorepo Management

- Follow best practices using Turbo for monorepo setups.
- Ensure packages are properly isolated and dependencies are correctly managed.
- Use shared configurations and scripts where appropriate.
- Utilize the workspace structure as defined in the root `package.json`.

# Testing and Quality Assurance

- Write unit and integration tests for critical components.
- Use testing libraries compatible with React and Node.js.
- Ensure code coverage and quality metrics meet the project's requirements.

# Project-specific Cursor rules for a portfolio website using Astro & Three.JS on jayciretose.github.io

key_conventions:
  - Follow Astro's style guide for consistent code formatting.
  - Use TypeScript for enhanced type safety and developer experience.
  - Use functional, declarative programming. Avoid classes.
  - Use descriptive variable names with auxiliary verbs (e.g., isLoading).
  - Use lowercase with dashes for directories (e.g., components/image-gallery).
  - Favor named exports for components.
  - Implement proper error handling and logging.

project_structure:
  - Use the recommended Astro project structure:
    - src/
    - components/
    - layouts/
    - pages/
    - styles/
    - public/
    - astro.config.mjs

component_development:
  - Create .astro files for Astro components.
  - Use framework-specific components (React) when necessary.
  - Implement proper component composition and reusability.
  - Use Astro's component props for data passing.
  - Leverage Astro's built-in components like <Markdown /> when appropriate.

routing_and_pages:
  - Utilize Astro's file-based routing system in the src/pages/ directory.
  - Implement dynamic routes using [.slug].astro syntax.
  - Use getStaticPaths() for generating static pages with dynamic routes.
  - Implement proper 404 handling with a 404.astro page.

content_management:
  - Use Markdown (.md) or MDX (.mdx) files for content-heavy pages.
  - Leverage Astro's built-in support for frontmatter in Markdown files.
  - Implement content collections for organized content management.

styling:
  - Use Astro's scoped styling with <style> tags in .astro files.
  - Leverage global styles when necessary, importing them in layouts.
  - Utilize CSS preprocessing with Sass or Less if required.
  - Implement responsive design using CSS custom properties and media queries.
  - Integrate Tailwind CSS with Astro via @astrojs/tailwind.
  - Use Tailwind utility classes extensively in your Astro components.
  - Leverage Tailwind's responsive design utilities (sm:, md:, lg:, etc.).
  - Utilize Tailwind's color palette and spacing scale for consistency.
  - Implement custom theme extensions in tailwind.config.cjs when necessary.
  - Never use the @apply directive.

performance_optimization:
  - Minimize use of client-side JavaScript; leverage Astro's static generation.
  - Use the client:* directives judiciously for partial hydration:
    - client:load for immediately needed interactivity
    - client:idle for non-critical interactivity
    - client:visible for components that should hydrate when visible
  - Implement proper lazy loading for images and other assets.
  - Utilize Astro's built-in asset optimization features.

data_fetching:
  - Use Astro.props for passing data to components.
  - Implement getStaticPaths() for fetching data at build time.
  - Use Astro.glob() for working with local files efficiently.
  - Implement proper error handling for data fetching operations.

seo_and_meta_tags:
  - Use Astro's <head> tag for adding meta information.
  - Implement canonical URLs for proper SEO.
  - Use the <SEO> component pattern for reusable SEO setups.

integrations_and_plugins:
  - Utilize Astro integrations for extending functionality (e.g., @astrojs/image).
  - Implement proper configuration for integrations in astro.config.mjs.
  - Use Astro's official integrations when available for better compatibility.

build_and_deployment:
  - Optimize the build process using Astro's build command.
  - Implement proper environment variable handling for different environments.
  - Use static hosting platforms compatible with Astro (Netlify, Vercel, etc.).
  - Implement proper CI/CD pipelines for automated builds and deployments.

three_js_integration:
  - Set up Three.js using React three fiber in relevant components.
  - Use efficient rendering techniques to handle complex 3D scenes.
  - Optimize 3D object loading and management using Three.js best practices.
  - Leverage Three.js libraries for additional capabilities (e.g., animations, interactions).

testing:
  - Implement unit tests for utility functions and helpers.
  - Use end-to-end testing tools like Cypress for testing the built site.
  - Implement visual regression testing if applicable.

accessibility:
  - Ensure proper semantic HTML structure in Astro components.
  - Implement ARIA attributes where necessary.
  - Ensure keyboard navigation support for interactive elements.

performance_metrics:
  - Prioritize Core Web Vitals (LCP, FID, CLS) in development.
  - Use Lighthouse and WebPageTest for performance auditing.
  - Implement performance budgets and monitoring.

// React + MobX .cursorrules

// Prefer functional components with hooks
const preferFunctionalComponents = true;

// MobX best practices
const mobxBestPractices = [
  "Use MobX-react-lite for optimal performance with functional components",
  "Implement stores for managing application state",
  "Utilize computed values for derived state",
  "Use actions for modifying observable state",
  "Implement proper error handling in asynchronous actions",
];

// Folder structure
const folderStructure = `
src/
  components/
  stores/
  hooks/
  pages/
  utils/
`;

// Additional instructions
const additionalInstructions = `
1. Use TypeScript for type safety with MobX
2. Implement strict mode for MobX for better debugging
3. Use observer HOC or useObserver hook for reactive components
4. Implement proper dependency injection for stores
5. Use reaction for side-effects based on observable changes
6. Utilize MobX DevTools for debugging
7. Follow MobX best practices for scalable state management
`;

# Role Positioning

You are a senior front-end development expert, proficient in modern front-end technology stacks such as React, TypeScript, Next.js, and also an excellent technical article writer.

# Writing Guidelines

Follow these guidelines to ensure article quality and professionalism. Remember: Quality > Quantity.

# Core Principles

**1** **Clarity**: Clear article structure and hierarchy
**2** **Professionalism**: Ensure technical content accuracy and appropriate terminology
**3** **Practicality**: Focus on real development scenarios, provide implementable solutions
**4** **Readability**: Use easy-to-understand language, add appropriate analogies and examples
**5** **Completeness**: Complete knowledge points, coherent logic
**6** **Innovation**: Combine latest technology trends, provide unique insights

# Content Standards

**1** **Title Design**: Use clear and attractive titles, can use numerical titles
**2** **Paragraph Organization**: Reasonable paragraphing, each focusing on one topic
**3** **Code Display**: Provide clear code examples, add comments when necessary
**4** **Technical Terms**: Explain professional terms on first appearance
**5** **Text and Images**: Use charts and screenshots appropriately
**6** **Citation Standards**: Cite references and technical documentation sources
**7** **Format Consistency**: Maintain article format consistency

# Technical Focus

* **React Ecosystem**: React Hooks, Next.js, React Router, etc.
* **TypeScript**: Type definitions, generics, advanced features
* **Performance Optimization**: First screen loading, code splitting, caching strategies
* **Engineering**: Webpack, Vite, ESLint configuration
* **Best Practices**: Component design, state management, error handling

# Article Structure Suggestions

* **Introduction**: Brief introduction of article topic and target readers
* **Main Content**: Organize content by difficulty progression or logical relationships
* **Summary**: Review key points
* **Extension**: Provide resources and suggestions for further learning

# Common Issues Handling

* **Technical Updates**: Check technical versions, update outdated content timely
* **Controversial Issues**: Objectively analyze pros and cons of different solutions
* **Practical Suggestions**: Provide suggestions based on actual project experience

# Important Reminders

**Focus on front-end technical content**
**Ensure article professionalism and accuracy**
**Maintain writing fluency and readability**
**Add personal insights and practical experience appropriately**
**Pay attention to article layout and aesthetics**
**Keep updated with technology development**

Follow these guidelines to create high-quality technical articles. If you have any questions, feel free to discuss!

# Tab system

Every time you choose to apply a rule(s), explicitly state the rule(s) in the output. You can
abbreviate the rule description to a single word or phrase.

## Project context

Tab system to allow members of an organisation to keep track of their balance. The project will be ran in a local environment.

## Code style and structure

- Write concise, scalable Typescript code with a focus on readability and maintainability.
- Use well known patterns for each solution
- Structure repository files as follows
- For pages in Next app router, always have page.tsx be a server component. If we need client functionality, create page-client.tsx component.
- For more than 200 lines of code, always split code into multiple components. If they are not used on multiple pages, store it next to page.tsx.
- Always use .env for actual envs and update .env.sample with correct keys without values.

```
/app
/components # Shared React components between different pages
/db
/drizzle
/hooks
/lib
/public
/styles
/types
.env
.env.sample
```

## UI and Styling

- Use Shadcn UI and Radix for components
- use `pnpm dlx shadcn@latest add <component-name>` to add a new shadcn components (this is newest way)

## Security

- We use jose and zod for signing and verifying tokens
- We only have simple password authentication, no external authentication providers
- For admin functionality, always check permission in token

## Git Usage

Format Message prefixes:

- "feat:" for new features
- "fix:" for bug fixes
- "docs:" for documentation changes
- "style:" for formatting changes
- "refactor:" for code refactoring
- "perf:" for performance improvements
- "test:" for adding tests
- "chore:" for other changes that don't modify src or test files

Rules:

- Generally, always use 'git add .' to add all changes to the commit, unless we have a lot of changes in different files which we wanna split to different commits.
- Use lowercase for commit messages
- Keep the summary line short and concise, but descriptive.
- Include description for non-obvious changes
- Always suggest to commit a new change after big changes.
- Also if we then alter the previous changes, suggest to amend to the previous commit, to keep the commit history clean.

## Documentation

- Only add comments to critical code logic where it is not obvious what the code does.
- Maintain clear README with setup instructions
- Make the README be a good starting point for new developers to understand the project
- Document permission requirements

## Deployment

- This will be ran on a local old PC (ubuntu system)
- We will use docker to run the application
- Deployment should be as reliable as possible, even if there is power outage, internet issues or PC turns on/off, the application should be able to automatically start up again.