APHOTICDocumentation / Design Principles
Design Principles
Aphotic 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.
Aphotic was previously known as Noctis-Hypr.
Core Philosophy
Declarative Over Hardcoded
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.
Composable, Not Monolithic
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.
Safe to Run Twice
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
Honest About What It Will Do
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, and what the install would do to your login screen and config files
Reversible
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)
- Puts sddm back as the login screen when it’s installed, and offers to remove the greeter’s system files
- System-level changes you opted into stay until you undo them by hand: the BlackArch repo, and the
multilibrepo the gaming layer enables
Technical Design Principles
Minimal System Footprint
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
Compositor-First, GPU-When-Justified
Principle: Costly work only runs when something is actually there to consume it, and shared animation is driven from a single low-rate clock rather than per-window timers.
Rationale: The shell picks up the desktop’s visual identity — so its biggest risk is quietly consuming idle GPU and CPU for work nothing displays. Keeping the hot path cheap matters more than pushing a prettier effect that runs forever.
Implementation:
- GPU utilization and temperature polling only run while a Performance surface that shows them is open, gated by a reference count — the base CPU/memory/disk polling stays cheap on its own slower interval.
- Every breathing glow runs off one shared, low-frequency clock (a single 8 Hz
pulsevalue, easing over a 2.6-second period) instead of each glow owning its own infinite per-frame animation, capping repaints well below the display refresh rate. - Heavy surfaces are built lazily — e.g. the Agent Graph tab’s dashboard surface is only constructed once its tab is actually picked, not at shell startup.
- The shell daemon reaps its
Processchildren on restart rather than orphaning them to re-parent to init.
User-Centric Configuration
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 (
aphotictool) - Well-organized file structure with clear separation of concerns
Robust Error Handling
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
Secure Operation
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
Architectural Principles
Modular Design
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
Extensible Architecture
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
Performance-Oriented
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
User Experience Principles
Intuitive Workflow
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
Progressive Disclosure
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
Consistent Interface
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 (
aphoticCLI) - Consistent keybinding patterns
- Similar UI patterns across Quickshell components
Documentation Principles
Comprehensive Coverage
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
Practical Examples
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
Evolution Principles
Future-Proof Design
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
Community-Centric Development
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 Aphotic’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.