# dclause/hermes-studio architecture

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

- Interactive diagram: https://gitdiagram.com/dclause/hermes-studio
- Repository: https://github.com/dclause/hermes-studio

## Overview

##### Main Components
- Frontend Application:
- Built with Vue. Encompasses UI pages, layouts, components (for animations, hardware, commands, groups, etc.), plugins (e.g., i18n, router, Pinia, Vuetify), and composables.
- Manages user interactions, drag-and-drop functionalities, and visualization (e.g., timeline for animations, configuration panels for boards/devices).
- Backend Application:
- Written in Rust with a clear module separation. Key modules include:
- API Layer:
– REST API under backend/src/api/rest for handling HTTP requests, dealing with endpoints such as animations, boards, devices, configuration, etc.
– WebSocket API under backend/src/api/sockets to manage real-time communications and control signals.
– Payloads and data definitions for ensuring correct data exchange.
- Business Logic Modules:
– Animations, devices, hardware interfaces, and additional utilities.
– Device-specific modules (for LED, servo, mp3, etc.) and hardware controllers (boards, expanders).
- Utility Modules:
– CLI, configuration, logging, database interfacing, and other helper functions.
- Supporting Infrastructure:
- Scripts for building/deployment (both frontend and backend).
- CI/CD configuration with GitHub Actions integrating various workflows for build, test, deploy, and coverage.
- Documentation site (docs folder) for user guidance and advanced configuration details.
- External entity: Arduino boards and potentially other IoT hardware needing compatible firmware (e.g., the StandardFirmataPlus sketch).

##### Relationships and Data Flows
- The Frontend and Backend communicate over HTTP/REST and WebSocket channels.
- The Frontend sends API requests to the Backend (for configuring devices, running animations, etc.) and receives real-time updates via WebSocket.
- The Backend routes these requests through the appropriate API controllers; for REST routes, it uses structured endpoints while for live events, sockets are used.
- Device-specific modules on the Backend abstract the control logic, interacting with the underlying hardware through serial connections or specific protocols.
- Build and deployment scripts contribute to the continuous integration ecosystem.

##### Architectural Patterns and Design Principles
- Decoupled architecture with clear separation between frontend and backend responsibilities.
- Modular design within the backend (e.g., organizing code by API payloads, REST and sockets, devices, animations, and hardware) hints at a layered architecture.
- Clean separation of concerns in the frontend via components, stores, composables, and clearly divided routes.

##### Detailed Explanation for the Principal Software Engineer
- For the Backend, create a block with subdivisions:
- API Layer: split further into “REST Endpoints” (with modules for animations, board config, devices, etc.) and “WebSocket Endpoints” (live control, real-time updates).
- Business Logic / Device Modules: include “Animations”, “Devices”, “Hardware (Board, Expander, Controller)”, and “Utils (CLI, logging, configuration, etc.)”
- Modular separation and clearly annotate any interactions, especially the interplay of WebSockets for real-time commands versus HTTP for regular state management.

Happy diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend (Vue) Block
    subgraph "Frontend (Vue)"
        FE1["UI Components & Pages"]:::frontend
        FE2["Stores_&_States"]:::frontend
        FE3["Routes_&_Layouts"]:::frontend
        FE4["Plugins_&_Composables"]:::frontend
    end

    %% Backend (Rust) Block
    subgraph "Backend (Rust)"
        subgraph "API Layer"
            BE1["REST API Endpoints"]:::backend
            BE2["WebSocket API Endpoints"]:::backend
            BE3["API Payloads"]:::backend
        end
        subgraph "Business Logic"
            BL1["Animations Module"]:::backend
            BL2["Devices Module"]:::backend
            BL3["Hardware Control"]:::backend
            BL4["Utility Modules"]:::backend
        end
    end

    %% External Devices Block
    subgraph "External Devices"
        ED1["Arduino_/_IoT Hardware"]:::external
    end

    %% CI/CD & Build Scripts Block
    subgraph "CI/CD_&_Build Scripts"
        CI1["CI/CD Pipeline_(GitHub_Actions)"]:::infrastructure
        CI2["Build_&_Deploy Scripts"]:::infrastructure
    end

    %% Documentation Block
    subgraph "Documentation"
        DOC["Documentation Site"]:::infrastructure
    end

    %% Connections between Frontend and Backend API Layer
    FE1 -->|"REST_Call"| BE1
    FE1 -->|"WebSocket"| BE2

    %% API Layer uses API Payloads
    BE1 -->|"Uses"| BE3
    BE2 -->|"Uses"| BE3

    %% REST API routes requests to Business Logic Modules
    BE1 -->|"Triggers"| BL1
    BE1 -->|"Triggers"| BL2
    BE1 -->|"Triggers"| BL3
    BE1 -->|"Triggers"| BL4

    %% WebSocket API routes requests to select Business Logic Modules
    BE2 -->|"Triggers"| BL1
    BE2 -->|"Triggers"| BL2

    %% Hardware Control interacts with External Devices
    BL3 -->|"Sends_Commands"| ED1

    %% CI/CD and Build Scripts interactions
    CI1 -->|"Deploys"| FE1
    CI1 -->|"Deploys"| BE1
    CI2 -->|"Builds"| FE1
    CI2 -->|"Builds"| BE1

    %% Documentation connects to Frontend and Backend
    DOC -->|"Describes"| FE1
    DOC -->|"Describes"| BE1

    %% Click Event Mappings
    click FE1 "https://github.com/dclause/hermes-studio/tree/develop/frontend/src"
    click BE1 "https://github.com/dclause/hermes-studio/tree/develop/backend/src/api/rest"
    click BE2 "https://github.com/dclause/hermes-studio/tree/develop/backend/src/api/sockets"
    click BE3 "https://github.com/dclause/hermes-studio/tree/develop/backend/src/api/payloads"
    click BL1 "https://github.com/dclause/hermes-studio/tree/develop/backend/src/animations"
    click BL2 "https://github.com/dclause/hermes-studio/tree/develop/backend/src/devices"
    click BL3 "https://github.com/dclause/hermes-studio/tree/develop/backend/src/hardware"
    click BL4 "https://github.com/dclause/hermes-studio/tree/develop/backend/src/utils"
    click DOC "https://github.com/dclause/hermes-studio/tree/develop/docs"
    click CI1 "https://github.com/dclause/hermes-studio/tree/develop/.github/workflows"
    click CI2 "https://github.com/dclause/hermes-studio/tree/develop/scripts"

    %% Styles
    classDef frontend fill:#AEDFF7,stroke:#1B6CA8,stroke-width:2px;
    classDef backend fill:#F7D6AE,stroke:#D98448,stroke-width:2px;
    classDef external fill:#C3F7C3,stroke:#4CAF50,stroke-width:2px;
    classDef infrastructure fill:#FBE7C6,stroke:#F5A623,stroke-width:2px;
```
