Skip to content

PROJECT_SUMMARY.md

Latest commit

 

History

History
executable file
·
170 lines (140 loc) · 3.44 KB

PROJECT_SUMMARY.md

File metadata and controls

executable file
·
170 lines (140 loc) · 3.44 KB

Project Summary (v1.0.0)

HyprRice is a comprehensive, modular ricing tool for the Hyprland Wayland compositor ecosystem. Built with Python and PyQt5, it provides a modern GUI, deep integration with Hyprland tools, theme management, plugin support, and robust configuration handling.

Architecture Overview

Core Components

  • src/hyprrice/

    • gui.py: Main application window

      • Event dispatch system
      • Tab management
      • Plugin integration
      • Configuration binding

    • gui/tabs.py: Configuration tabs

      • Hyprland core settings
      • Waybar customization
      • Rofi configuration
      • Notification settings
      • Clipboard management
      • Lockscreen setup
      • Theme management
      • Settings and plugins

    • gui/preview.py: Live preview system

      • Real-time updates
      • Theme visualization
      • Layout preview
      • Animation testing

    • gui/theme_manager.py: Theme handling

      • Theme loading/saving
      • Gallery management
      • Import/export
      • Validation

    • plugins.py: Plugin system

      • Plugin base class
      • Event hooks
      • Plugin manager
      • Hot-reload support

    • hyprland/: Hyprland modules

      • animations.py: Animation configuration
      • display.py: Monitor and workspace setup
      • input.py: Input device handling
      • windows.py: Window management
      • workspaces.py: Workspace configuration

Data Flow

  1. User interacts with GUI
  2. Changes trigger plugin events
  3. Validation occurs
  4. Preview updates
  5. Changes applied on confirmation
  6. Audit trail updated

Design Decisions

GUI Framework

  • PyQt5: Chosen for:
    • Native Wayland support
    • Rich widget set
    • Performance
    • Stability

Plugin Architecture

  • Event-based: Allows for:
    • Non-blocking operations
    • Clean separation
    • Easy extension
    • Safe integration

Theme System

  • YAML format: Provides:
    • Human readability
    • Easy validation
    • Version control friendly
    • Community sharing

Configuration Management

  • Versioned backups: Ensures:
    • Safe experimentation
    • Easy rollback
    • History tracking
    • Disaster recovery

Extensibility

Plugin System

  • Event hooks for key operations
  • UI extension capabilities
  • Configuration access
  • Theme integration
  • Preview manipulation

Theme Creation

  • Standard format
  • Component separation
  • Style inheritance
  • Custom properties
  • Export/sharing

Configuration Export

  • Multiple formats
  • Validation rules
  • Import safety
  • Version tracking

Performance Considerations

GUI Responsiveness

  • Async operations
  • Cached previews
  • Lazy loading
  • Event debouncing

Resource Usage

  • Minimal dependencies
  • Efficient preview
  • Smart validation
  • Optimized imports

Memory Management

  • Cache control
  • Resource cleanup
  • Plugin isolation
  • Preview optimization

Security

Configuration Safety

  • Backup system
  • Validation checks
  • Safe defaults
  • Error recovery

Plugin Isolation

  • Sandboxed execution
  • Resource limits
  • Error handling
  • Clean shutdown

Future Development

Planned Features

  • Additional tool integration
  • Enhanced preview system
  • More theme options
  • Extended plugin API

Compatibility

  • Maintain v1.x API
  • Support older configs
  • Plugin compatibility
  • Theme format stability

Documentation

  • User guide
  • API reference
  • Plugin examples
  • Theme tutorial
  • Troubleshooting

Testing

  • Unit tests
  • Integration tests
  • Plugin testing
  • Theme validation
  • Performance benchmarks