# migcube1/stream-deck architecture

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

- Interactive diagram: https://gitdiagram.com/migcube1/stream-deck
- Repository: https://github.com/migcube1/stream-deck

## Overview

##### Project’s Type and Purpose
- The project is a desktop application built in Java (using Ant and NetBeans), intended to interface with hardware (a “Stream Deck”).
- It includes a user interface (with Views and Forms), business logic (in Controllers, Helpers, and Models), and low-level hardware communication (using the purejavahidapi and JNA libraries).
- In addition, there’s some firmware code (in the firmware directory) and prototype documentation (in the prototype folder) indicating both the software and hardware prototyping aspects of the project.

##### File Structure and Its Implications
- The src/app/StreamDeckApp directory holds the core application, built using an Ant build file (build.xml) and configured with NetBeans projects (nbproject).
- The Java source is organized into several folders that indicate an MVC-like pattern:
- Views (src/Views) → likely the UI forms and view classes.
- Controllers (src/Controllers) → handling user input and updating the view or model.
- Models (src/Models) → representing the business data/entities.
- Main (src/Main) → the application’s entry point.
- The purejavahidapi directories (both in the src and build trees) along with the inclusion of JNA-related JAR files suggest that the application communicates with underlying USB/HID devices. There are platform-specific implementations (linux, macosx, windows) showing that hardware interaction is a key component.
- The firmware folder contains C source and hex files.
- The releases directory holds a pre-built Windows executable (StreamDeckAppV1.exe), indicating that cross-platform deployment might be part of the delivery strategy.

a. Main Components to Represent:
- User Interface Layer: Represent the Views (GUI forms like AppView, EventosView, InfoView).
- Controller Layer: Indicate controllers (e.g., AppController) that mediate UI actions.
- Business / Domain Layer: Show Models (Evento, Eventos, etc.) which encapsulate business logic.
- Hardware Abstraction Layer: Show the PureJavaHidApi components (with platform-specific sub-components for Linux, Mac, and Windows). This layer is responsible for interacting with the underlying USB/HID devices.
- Deployment/Build Subsystem: Note the use of Ant build scripts (build.xml) and project configuration (nbproject, manifest.mf) that assemble the application.
- Firmware Component: Separate a block that indicates firmware (stream_deck.c and stream_deck.hex) which suggest there is a lower-level embedded system controlling the hardware from the device side.

b. Relationships and Interactions:
- Flow from the User Interface:
– UI (Views) sends user commands to the Controllers.
– Controllers update the Models or trigger hardware actions.
– The hardware communication layer, via PureJavaHidApi, abstracts different operating system specifics and connects to the USB/HID device.
- Link the build/deployment process to ensure build artifacts (in the build/dist folders, and the release executable) are clearly separate from the source.

c. Architectural Patterns and Design Principles:
- Model-View-Controller (MVC): Show clear separation between the View, Controller, and Model components.
- Hardware abstraction: Emphasize the layer that abstracts platform-dependent functionalities via PureJavaHidApi and JNA.
- Modular design: The organization of Helpers, external libraries (JNA, purejavahidapi), and firmware shows separation of concerns.

d. Relevant Technologies, Frameworks, and Libraries:
- Java with Ant and NetBeans
- JNA (Java Native Access) for native library interactions.
- PureJavaHidApi for USB/HID device communication.
- Platform-specific libraries (LinuxBackend, MacOsXBackend, WindowsBackend) within the purejavahidapi package.
- The firmware code indicates C programming with a hex file for programming the device’s microcontroller.

##### Instructing the Principal Software Engineer to Include the Following
- Clearly labeled components:
- User Interface (Views)
- Controllers (Business Logic)
- Models (Data Management)
- Hardware Abstraction Layer (PureJavaHidApi with OS-specific branches)
- Utilities/Helpers
- Build/Configuration (Ant build script, NetBeans config)
- Firmware Module (for device-specific code)
- Data flow: UI → Controller → Model/Hardware Interaction.
- Interaction between the Java application and the native/firmware layer.
- Clearly distinguish between internal components and external dependencies (like JNA libraries).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "User Interface Layer"
        UI["User Interface (Views)"]:::frontend
    end

    %% Application Logic Layer
    subgraph "Application Logic Layer"
        CTR["Controller Layer"]:::controller
        MOD["Business / Domain Models"]:::model
        HELP["Utility/Helpers Layer"]:::helper
    end

    %% Hardware Abstraction Layer
    subgraph "Hardware Abstraction Layer"
        HARD["PureJavaHidApi Core"]:::hardware
        HIDP["HID Parser"]:::hardware
        SHARE["Shared Code"]:::hardware
        LINUX["Linux Implementation"]:::hardware
        MAC["MacOSX Implementation"]:::hardware
        WIN["Windows Implementation"]:::hardware
    end

    %% Deployment/Build Subsystem
    subgraph "Deployment/Build Subsystem"
        ANT["Ant Build Script"]:::build
        NET["NetBeans Project Configuration"]:::build
    end

    %% Firmware Module
    FW["Firmware Module"]:::firmware

    %% Connections: UI to Application Logic
    UI -->|"sendsInput"| CTR
    CTR -->|"updates"| MOD
    CTR -->|"uses"| HELP

    %% Connection: Application Logic to Hardware Abstraction
    CTR -->|"invokesHW"| HARD

    %% Internal connections within Hardware Abstraction Layer
    HARD -->|"parses"| HIDP
    HARD -->|"shares"| SHARE
    HARD -->|"supports"| LINUX
    HARD -->|"supports"| MAC
    HARD -->|"supports"| WIN

    %% Hardware communicates with Firmware
    HARD -->|"communicatesWith"| FW

    %% Deployment/Build builds Application Logic components
    ANT -->|"builds"| UI
    ANT -->|"builds"| CTR
    ANT -->|"builds"| MOD
    NET -->|"configures"| UI
    NET -->|"configures"| CTR

    %% Click Events for component mapping
    click UI "https://github.com/migcube1/stream-deck/tree/master/src/app/StreamDeckApp/src/Views"
    click CTR "https://github.com/migcube1/stream-deck/tree/master/src/app/StreamDeckApp/src/Controllers"
    click MOD "https://github.com/migcube1/stream-deck/tree/master/src/app/StreamDeckApp/src/Models"
    click HELP "https://github.com/migcube1/stream-deck/tree/master/src/app/StreamDeckApp/src/Helpers"
    click HARD "https://github.com/migcube1/stream-deck/tree/master/src/app/StreamDeckApp/src/purejavahidapi"
    click HIDP "https://github.com/migcube1/stream-deck/tree/master/src/app/StreamDeckApp/src/purejavahidapi/hidparser"
    click SHARE "https://github.com/migcube1/stream-deck/tree/master/src/app/StreamDeckApp/src/purejavahidapi/shared"
    click LINUX "https://github.com/migcube1/stream-deck/tree/master/src/app/StreamDeckApp/src/purejavahidapi/linux"
    click MAC "https://github.com/migcube1/stream-deck/tree/master/src/app/StreamDeckApp/src/purejavahidapi/macosx"
    click WIN "https://github.com/migcube1/stream-deck/tree/master/src/app/StreamDeckApp/src/purejavahidapi/windows"
    click ANT "https://github.com/migcube1/stream-deck/blob/master/src/app/StreamDeckApp/build.xml"
    click NET "https://github.com/migcube1/stream-deck/tree/master/src/app/StreamDeckApp/nbproject"
    click FW "https://github.com/migcube1/stream-deck/tree/master/src/firmware"

    %% Styles for color coding
    classDef frontend fill:#f9e79f,stroke:#d35400,stroke-width:2px;
    classDef controller fill:#aed6f1,stroke:#2874a6,stroke-width:2px;
    classDef model fill:#a9dfbf,stroke:#239b56,stroke-width:2px;
    classDef helper fill:#f5b7b1,stroke:#c0392b,stroke-width:2px;
    classDef hardware fill:#f9e79f,stroke:#b9770e,stroke-width:2px;
    classDef build fill:#d2b4de,stroke:#7d3c98,stroke-width:2px;
    classDef firmware fill:#fadbd8,stroke:#922b21,stroke-width:2px;
```
