How zetaloop/keyviz works
Major Components
• Flutter Frontend/UI: At the core, the “lib” folder contains the main Dart files (e.g., main.dart) and a structured hierarchy with subdirectories like “config”, “domain”, “providers”, and “windows”. This represents the main Flutter application.
• Domain Layer: The “lib/domain” directory includes business logic, services (such as key mapping and raw keyboard/mouse processing), and vault-related functionality (e.g., JSON handling). This is where the core behavior is implemented.
• Presentation Layer: The “lib/windows” directory is dedicated to UI components for displaying key visualizers, mouse visualizers, error messages, and settings dialogs. Note the further sub-division into widgets, animations, and settings views.
• Configuration & Providers: The “lib/config” and “lib/providers” folders encapsulate theme settings, style, assets, and reactive state management for key events and visual styles.
• Cross-Platform Shells: Separate directories for “windows”, “macos”, and “linux” include platform-specific build scripts (e.g., CMakeLists.txt, Xcode project files) that indicate native integration beyond Flutter’s scope.
• CI/CD & Automation: The “.github” folder, including workflow definitions, shows how the project integrates with GitHub Actions for automated builds across platforms.
Relationships and Interactions
• User Input Flow: User triggers (keyboard/mouse) → System listeners in the domain/services modules → Providers update the state → Visual components in the “windows/key_visualizer” and “mouse_visualizer” render the changes.
• Configuration Management: The configuration module feeds styling, assets, and theme details into the UI components to allow personalized visualization.
• Settings & Customization: The settings components (under “lib/windows/settings”) allow users to change the visual and behavioral parameters. These components interact with the providers to update the state dynamically.
• Platform-specific Code: The separate directories for native platform integration (windows/, macos/, linux/) indicate that the Flutter app interfaces with native code to capture system events and render the window using OS-specific APIs.
Architectural Patterns and Design Principles
• Separation of Concerns: The split between domain (business logic), configuration (styling/asset management), providers (state management), and presentation (visualizers and settings) indicates a layered architecture.
• Cross-Platform and Native Integration: Highlight that while the business and presentation logic are implemented in Flutter, native build scripts and directories handle OS-specific concerns.
Including Technologies and Frameworks
• Flutter Framework: Central to the UI rendering and cross-platform logic.
• Platform-specific Build Tools: For Windows (CMake, C++ source files), macOS (Xcode, Swift/C/Objective-C), and Linux (CMake).
• GitHub Actions: Representing continuous integration workflows that automatically build and test the application.