Repository navigation
Design Principles
Noctis-Hypr is built on a set of core design principles that guide its development and functionality. These principles ensure the system remains robust, flexible, and user-friendly while maintaining its unique approach to desktop configuration.
Principle: Package sets are defined as data (TOML files) rather than hardcoded bash arrays.
Rationale: This approach makes configuration more maintainable, less error-prone, and easier to understand. Instead of complex shell scripting that can break or become unmaintainable, the system uses structured data that's easy to validate and modify.
Implementation: Profiles and layers are stored as TOML files that define package sets, which are then merged at runtime to create the final installation plan.
Principle: Profiles and layers can be combined freely without conflicts or code duplication.
Rationale: Users have diverse needs, and a monolithic approach would force them into rigid configurations. By making the system composable, users can build exactly what they need.
Implementation: The system uses a TOML merging process that deduplicates packages across profiles and layers, ensuring clean combinations without conflicts.
Principle: Every installation is snapshotted before changes are made, and re-runs detect existing configurations.
Rationale: Desktop environments can be complex, and mistakes during installation can be disruptive. This principle ensures users can experiment safely.
Implementation:
- Automatic backup creation before any changes
- Configuration reuse detection to avoid repeated prompts
- Safe rollback capabilities through the uninstall process
Principle: The --dry-run flag shows the full install plan before touching anything.
Rationale: Transparency is crucial for user trust and understanding. Users should know exactly what will happen before it happens.
Implementation:
- Comprehensive dry-run mode that shows all planned actions
- Clear output format showing what packages will be installed
- Visual indication of changes to configuration files
Principle: Easy uninstallation that restores the previous setup without leaving traces.
Rationale: Users should never feel locked in or afraid to try new configurations. A reversible system allows exploration without risk.
Implementation:
- Uninstall script that restores the most recent backup
- Clean removal of installed packages (with confirmation)
- No leftover configuration files or settings
Principle: The core system is lightweight while providing rich functionality.
Rationale: Desktop environments should be fast and responsive, not resource-heavy.
Implementation:
- Base profiles provide minimal functionality
- Layers add features as needed
- Performance optimization throughout the codebase
Principle: Configuration is managed in a way that's accessible and understandable to users.
Rationale: Complex systems are more likely to be abandoned or misused when they're not user-friendly.
Implementation:
- Clear documentation for all features
- Intuitive CLI commands (
noctistool) - Well-organized file structure with clear separation of concerns
Principle: The system handles errors gracefully and provides helpful feedback.
Rationale: Users should never be left confused by cryptic error messages or broken installations.
Implementation:
- Comprehensive error checking at all stages
- Clear, actionable error messages
- Graceful degradation when features aren't available
Principle: The system operates safely and minimizes potential security risks.
Rationale: Desktop environments have access to sensitive user data and system resources.
Implementation:
- Minimal privilege escalation where possible
- Secure handling of configuration files
- No external data collection or transmission
- Safe backup and restore mechanisms
Principle: The system is built with clear separation of concerns.
Rationale: Modular architecture makes the system easier to maintain, extend, and debug.
Implementation:
- Clear separation between installation logic and configuration management
- Independent components that can be tested separately
- Well-defined interfaces between modules
Principle: The system is designed to accommodate new features and capabilities.
Rationale: Desktop environments need to evolve with user needs and technology changes.
Implementation:
- Plugin-like architecture for optional features
- Clear extension points for custom functionality
- Flexible configuration schema that can be extended
Principle: The system is optimized for performance without sacrificing usability.
Rationale: Users expect responsive systems, especially during installation and updates.
Implementation:
- Efficient algorithms for package resolution and merging
- Optimized backup and restore operations
- Minimal overhead in runtime components
Principle: The installation and usage workflow is intuitive and straightforward.
Rationale: Complex systems are abandoned by users who find them confusing.
Implementation:
- Simple command-line interface with clear flags
- Interactive installer for first-time users
- Consistent behavior across different system states
Principle: Advanced features are available but not overwhelming for beginners.
Rationale: Users should be able to start simple and discover complexity as needed.
Implementation:
- Basic installation with minimal configuration options
- Advanced features accessible through explicit commands or flags
- Clear documentation for all levels of users
Principle: All components of the system present a consistent interface and experience.
Rationale: Inconsistent interfaces confuse users and make the system harder to learn.
Implementation:
- Uniform command naming and structure (
noctisCLI) - Consistent keybinding patterns
- Similar UI patterns across Quickshell components
Principle: All features are documented thoroughly and clearly.
Rationale: Users need to understand what's available and how to use it effectively.
Implementation:
- Wiki with detailed documentation for all features
- Inline comments in code
- Examples and usage patterns
Principle: Documentation includes practical examples and use cases.
Rationale: Abstract explanations are less helpful than concrete examples.
Implementation:
- Usage examples for every major feature
- Real-world scenario documentation
- Troubleshooting with specific solutions
Principle: The system is designed to evolve with changing needs and technologies.
Rationale: Desktop environments need to adapt to new hardware, software, and user expectations.
Implementation:
- Flexible architecture that can accommodate new features
- Clear upgrade paths for existing installations
- Regular updates to stay current with dependencies
Principle: The system is developed with community feedback and input in mind.
Rationale: Open source projects thrive when they serve their users' needs effectively.
Implementation:
- Public issue tracking and discussion
- Community contributions welcome and encouraged
- Regular communication with users about development direction
These design principles form the foundation of Noctis-Hypr's approach to desktop configuration. They guide both current development and future evolution, ensuring that the system remains useful, safe, and flexible for all users.