# zetaloop/keyviz architecture

> Architecture diagram of the GitHub repository zetaloop/keyviz, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zetaloop/keyviz
- Repository: https://github.com/zetaloop/keyviz

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    U("User"):::user

    subgraph "Flutter Frontend/UI"
        FM("Main Entry"):::frontend
        FA("App Module"):::frontend
        F("Flutter Application"):::frontend
    end

    U --> F
    FM --> F
    FA --> F

    F --> D("Domain & Business Logic"):::business
    F --> PUI("UI Components"):::presentation

    D --> PR("State Management & Providers"):::business

    subgraph "Presentation Layer"
        KV("Key Visualizer"):::presentation
        MV("Mouse Visualizer"):::presentation
        SU("Settings UI"):::presentation
        C("Configuration & Theming"):::presentation
    end

    PR --> KV
    PR --> MV
    PR --> SU
    C --> KV
    C --> SU

    F --> W("Windows Integration"):::native
    F --> M("macOS Integration"):::native
    F --> L("Linux Integration"):::native

    F --> CICD("CI/CD Pipeline"):::cicd

    click FM "https://github.com/zetaloop/keyviz/blob/main/lib/main.dart"
    click FA "https://github.com/zetaloop/keyviz/blob/main/lib/app.dart"
    click D "https://github.com/zetaloop/keyviz/tree/main/lib/domain"
    click PR "https://github.com/zetaloop/keyviz/tree/main/lib/providers"
    click KV "https://github.com/zetaloop/keyviz/tree/main/lib/windows/key_visualizer"
    click MV "https://github.com/zetaloop/keyviz/tree/main/lib/windows/mouse_visualizer"
    click SU "https://github.com/zetaloop/keyviz/tree/main/lib/windows/settings"
    click C "https://github.com/zetaloop/keyviz/tree/main/lib/config"
    click W "https://github.com/zetaloop/keyviz/tree/main/windows"
    click M "https://github.com/zetaloop/keyviz/tree/main/macos"
    click L "https://github.com/zetaloop/keyviz/tree/main/linux"
    click CICD "https://github.com/zetaloop/keyviz/blob/main/.github"

    classDef frontend fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef business fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef presentation fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef native fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef cicd fill:#D6EAF8,stroke:#2E86C1,stroke-dasharray:5,stroke-width:2px;
    classDef user fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
```
