.cursorrules

/**
 * Cursor rules for maintaining code quality and consistency in DumbAssets
 */

{
  "rules": {
    "file-header-docs": {
      "description": "All JavaScript files must have a header comment explaining their purpose",
      "pattern": "{src,public}/**/*.js",
      "check": {
        "type": "regex",
        "value": "^/\\*\\*\\n \\* [^\\n]+\\n \\* [^\\n]+\\n \\*/\\n",
        "message": "File must start with a header comment block explaining its purpose"
      }
    }
  }
}

# DumbAssets Architecture & Conventions

## Project Philosophy
- Keep code simple, smart, and follow best practices
- Don't over-engineer for the sake of engineering
- Use standard conventions and patterns
- Write human-readable code
- Keep it simple so the app just works
- Follow the principle: "Make it work, make it right, make it fast"
- Comments should explain "why" behind the code in more complex functions
- Overcommented code is better than undercommented code

## Commit Conventions
- Use Conventional Commits format:
  - feat: new features
  - fix: bug fixes
  - docs: documentation changes
  - style: formatting, missing semi colons, etc.
  - refactor: code changes that neither fix bugs nor add features
  - test: adding or modifying tests
  - chore: updating build tasks, package manager configs, etc.
- Each commit should be atomic and focused
- Write clear, descriptive commit messages

## Project Structure

### Root Directory
- Keep root directory clean with only essential files
- Production configuration files in root:
  - docker-compose.yml
  - Dockerfile
  - package.json
  - README.md
  - server.js (main application server)
  - nodemon.json (development configuration)

### Backend Structure
- server.js: Main Express server with all API routes
- middleware/: Custom middleware modules
  - cors.js: CORS configuration
  - demo.js: Demo mode middleware
- data/: JSON file storage
  - Assets.json: Main asset data
  - SubAssets.json: Sub-asset data
  - Images/, Manuals/, Receipts/: File uploads

### Frontend Structure (/public)
- All client-side code in /public directory
- **Manager Pattern**: Feature-specific classes in `/public/managers/`
  - globalHandlers.js: Global utilities (toaster, error logging, API calls)
  - dashboardManager.js: Dashboard rendering and charts
  - modalManager.js: Modal operations for assets/sub-assets
  - settingsManager.js: Settings modal and configuration
  - import.js: Import functionality and file processing
  - maintenanceManager.js: Maintenance event management
  - charts.js: Chart.js wrapper and chart management
  - toaster.js: Toast notification system

### Services Architecture (/src/services)
- **fileUpload/**: Modular file upload system
  - index.js: Main export interface
  - fileUploader.js: Core upload logic
  - init.js: Easy initialization
  - utils.js: Upload utilities
  - example.js: Usage examples
- **notifications/**: Apprise notification system
  - appriseNotifier.js: Apprise CLI integration
  - notificationQueue.js: Queue management
  - warrantyCron.js: Scheduled notifications
  - utils.js: Notification utilities
- **render/**: Rendering services
  - assetRenderer.js: Asset detail rendering
  - listRenderer.js: Asset list and search
  - previewRenderer.js: File preview generation
  - syncHelper.js: State synchronization
  - index.js: Service exports

### Helper Modules (/public/helpers)
- utils.js: General utility functions (generateId, formatDate, formatCurrency)
- paths.js: Path management utilities
- serviceWorkerHelper.js: PWA service worker management

### UI Enhancement (/public/js)
- collapsible.js: Collapsible section functionality
- datepicker-enhancement.js: Enhanced date input UX

# Documentation
- Main README.md in root focuses on production deployment
- Each service module has its own README.md with usage examples
- Code must be self-documenting with clear naming
- Complex logic must include comments explaining "why" not "what"
- JSDoc comments for public functions and APIs
- File headers must explain module purpose and key functionality

# Module System & ES6
- Use ES6 modules with import/export syntax
- Each manager class should be in its own file
- Services should be modular and reusable
- Use named exports for utilities, default exports for main classes
- Import statements at the top of files
- Dynamic imports only when necessary for performance

# Manager Pattern (/public/managers)
- Each major feature has its own manager class
- Manager classes handle feature-specific logic and DOM manipulation
- Managers should not directly manipulate other managers' DOM elements
- Use dependency injection for shared utilities
- Manager constructors should accept configuration objects
- Each manager should have clear initialization and cleanup methods

# Service Architecture (/src/services)
- Services are backend utilities that can be used across the application
- Each service directory should have:
  - index.js: Main export interface
  - README.md: Documentation and examples
  - Specific implementation files
- Services should be stateless when possible
- Use consistent error handling across services

# Global Handlers Pattern
- globalHandlers.js centralizes common frontend functionality
- Exposes utilities to globalThis for app-wide access:
  - globalThis.validateResponse: API response validation
  - globalThis.toaster: Toast notifications
  - globalThis.logError: Error logging with toast
  - globalThis.getApiBaseUrl: Environment-aware API URLs
- Must be instantiated early in script.js
- All async API calls should use validateResponse pattern

# File Upload System
- Modular file upload service in /src/services/fileUpload/
- Supports drag-and-drop, previews, and validation
- Consistent API across different file types (images, receipts, manuals)
- Use setupFilePreview for standard implementation
- File validation by type and size
- Preview generation for images and documents

# PWA & Service Worker
- Service worker for offline functionality and caching
- Manifest generation for PWA capabilities
- Version management for cache invalidation
- App configuration in config.js
- Service worker helper for registration and updates

# Notification System
- Apprise-based notification system for external alerts
- Queue management to prevent notification spam
- Cron-based warranty expiration notifications
- Timezone-aware scheduling with Luxon
- Sanitized message formatting

# Chart Integration
- Chart.js wrapper in managers/charts.js
- Centralized chart creation and updates
- Theme-aware chart styling
- Responsive chart configuration

# Theme System
- CSS custom properties for theme variables
- data-theme attribute on html element
- Theme persistence in localStorage
- System theme preference detection
- Consistent color scheme:
  - Light theme: #ffffff bg, #1a1a1a text, #2563eb primary
  - Dark theme: #1a1a1a bg, #ffffff text, #3b82f6 primary
- Theme toggle on all pages

# Security & Authentication
- PIN-based authentication system
- Session management with express-session
- Helmet security middleware
- CORS configuration in middleware/cors.js
- PIN input requirements:
  - type="password" fields
  - Numeric validation
  - Paste support
  - Auto-advance and backspace navigation
- Brute force protection:
  - Attempt limits and lockouts
  - Constant-time comparison
- Secure cookie configuration

# Data Management
- JSON file-based storage (Assets.json, SubAssets.json)
- File uploads organized by type (Images/, Manuals/, Receipts/)
- Import/export functionality for data migration
- Utility functions for ID generation, date/currency formatting
- State synchronization between components

# API Patterns
- RESTful API endpoints in server.js
- Consistent error response format
- File upload handling with multer
- Demo mode middleware for testing
- Environment-aware base URL handling

# UI Enhancement
- Collapsible sections with consistent API
- Enhanced date picker with clear functionality
- Drag-and-drop file uploads
- Responsive design patterns
- Loading states and user feedback

# Error Handling
- Global error logging with globalThis.logError
- Toast notifications for user feedback
- Console logging in debug mode
- Graceful degradation for missing features
- Validation at both client and server levels

# Development Workflow
- nodemon for development server
- Docker configuration for production
- Environment variable support
- Debug mode controlled by window.appConfig.debug
- Maintenance notification testing scripts

# Code Style
- Use meaningful variable and function names
- Keep functions small and focused (under 50 lines when possible)
- Maximum line length: 100 characters
- Use modern JavaScript features appropriately
- Prefer clarity over cleverness
- Add logging when DEBUG environment variable is true
- Use async/await for promises
- Handle errors explicitly, don't ignore them

# Frontend Architecture Patterns

## Global Handlers Implementation
- globalHandlers class instantiated at the very top of script.js
- Provides 4 key global utilities:
  1. `globalThis.validateResponse` - API response validation
     - Checks status codes and error messages
     - Returns errorMessage if validation fails
     - Used before all API response processing
  2. `globalThis.toaster` - Toast notification system
     - `show(message, type='success', isStatic=false, timeoutMs=3000)`
     - Centralized user feedback mechanism
  3. `globalThis.logError` - Global error logging
     - `logError(message, error, keepOpen=false, toastTimeout=3000)`
     - Automatically console.error and toast notifications
  4. `globalThis.getApiBaseUrl` - Environment-aware API URLs
     - Ensures correct base URL for all API calls

## API Call Pattern
```javascript
try {
  const response = await fetch(`${globalThis.getApiBaseUrl()}/api/endpoint`);
  const responseValidation = await globalThis.validateResponse(response);
  if (responseValidation.errorMessage) {
    throw new Error(responseValidation.errorMessage);
  }
  // Process successful response
} catch (error) {
  globalThis.logError("Custom error message:", error.message);
}
```

## Manager Class Structure
- Constructor accepts configuration object with dependencies
- Each manager handles specific feature domain
- Managers should not manipulate other managers' DOM elements
- Use `_bindEvents()` method for event listener setup
- Provide public methods for external interaction
- Include cleanup methods for proper teardown

## File Upload Patterns
- Use `initializeFileUploads()` for standard setup
- Each file type (images, receipts, manuals) has consistent API
- Drag-and-drop with validation built-in
- Preview generation for all supported file types
- Global delete flags for file removal state

## State Management
- State synchronization through syncHelper.js
- Use updateState functions for cross-module updates
- Maintain single source of truth for asset data
- Sync selected IDs and filter states across components

## Component Initialization
- DOM-ready event listener in main script.js
- Initialize global handlers first
- Load configuration and check authentication
- Initialize service worker for PWA
- Set up theme system early
- Initialize managers in dependency order

## CSS and Theming
- Use CSS custom properties (--variable-name)
- data-theme attribute on html element
- Theme values stored in localStorage
- Consistent naming: --bg-color, --text-color, --primary-color
- Dark/light theme toggle with system preference detection

## PWA Implementation
- Service worker with versioned caching
- Manifest generation via scripts/pwa-manifest-generator.js
- Cache invalidation on version updates
- Offline functionality with cached resources
- Version checking via service worker messaging

## Maintenance & Notifications
- Cron-based warranty expiration checking
- Apprise integration for external notifications
- Queue management to prevent notification spam
- Timezone-aware scheduling with Luxon
- Sanitized message formatting for security