# dclause/hermes-five architecture

> Architecture diagram of the GitHub repository dclause/hermes-five, 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-five
- Repository: https://github.com/dclause/hermes-five

## Overview

##### Project Overview & Main Components
- Project Type & Purpose: Hermes-Five is an open-source Rust library allowing remote control of Arduino (and similar) boards. It’s comparable to the Johnny-Five framework in JavaScript but offers a Rust-based solution for handling devices (LEDs, servos, sensors, buttons, etc.), hardware control, animations, and event-driven programming.
- Crate Organization: The project is modularized into multiple interrelated crates:
– hermes-five (main library, contains the core functionality and API),
– hermes-five-macros (procedural macros used to simplify code annotations, e.g. the runtime macro),
– hermes-five-macros-internals (internal implementations to power the macros).
- Documentation & Examples: The docs folder and README indicate extensive user and API documentation along with real-world examples for usage.

##### Analyzing the File Structure for Architectural Insights
- Top-Level Structure:
– . GitHub workflows and configuration files (for CI/CD, building, testing, coverage and docs deployment).
– Cargo.toml and LICENSE indicate the project’s Rust ecosystem and open-source licensing.
– docs – Contains user guides, versioned docs, theme customizations (via VitePress), examples and public assets.
- Crates/Sources:
– Each crate (hermes-five, hermes-five-macros, hermes-five-macros-internals) separates concerns such as core functionality, macros support, and build-time logic.
– Within hermes-five, directories like src/animations, src/devices (with subdirectories for input and output), src/io (protocols and transports), and src/hardware reveal a layered, modular design with clear separation of responsibilities.
- Testing & Examples:
– Examples in hermes-five/examples demonstrate practical usage (e.g., board control, LED, servo animations) and serve as integration tests.
– Tests directory covers version-related test cases.

##### Determining Relationships & Interactions
- Core Library (hermes-five):
– Handles Board abstraction, device definitions, animation logic, IO handling (protocols: e.g., Serial for Firmata).
– Exposes public API for users to create boards, register events, control devices, and orchestrate animations.
- Macro Crates:
– hermes-five-macros and hermes-five-macros-internals work together to simplify API usage (e.g., the #[hermes_five::runtime] attribute). They interact with the main library by generating boilerplate code during compilation.
- Hardware Abstraction:
– Modules under src/hardware and src/io provide abstractions over physical connections (Arduino boards, firmata protocol communication, serial transport).
- Devices & Animations:
– Devices are implemented separately as “input” (buttons, sensors) and “output” (LEDs, servos). The animations module provides a mechanism to sequence device state changes.

##### Architectural Patterns & Design Principles
- Modularity & Separation of Concerns: Different functionalities (hardware interfacing, protocol handling, device management, animation sequencing) are encapsulated in dedicated modules/crates.
- Event-Driven & Asynchronous Behavior: The API is based on events (see BoardEvent) and leverages Rust’s async capabilities.
- Macro-Driven Enhancements: Procedural macros abstract repetitive patterns and help maintain a clean API.
- Extensibility: The feature flag support (e.g., libudev, serde, mock) suggests an architecture that supports optional, pluggable components based on deployment and testing needs.

– From the User/Application layer to the Core Library.
– Within the Core Library (“Board” triggering events which then activate “Devices” and “Animations”).
– Between separate crates (macros feeding into the core).
– Differentiate between business logic (like Board, Devices, and Animations), support libraries (Macros), communication layers (IO Protocols, Hardware Abstraction), and auxiliary components (Documentation, Examples).

Happy diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User/Application Layer
    Docs["Documentation"]:::userlayer
    Examples["Examples & Integration Tests"]:::userlayer

    %% Macro Infrastructure
    Macros["Procedural Macros"]:::macro
    MacroInternals["Macro Internals"]:::macro

    %% Core Library (hermes-five) Subgraph
    subgraph "Core Library (hermes-five)"
        Board["Board Abstraction"]:::board
        subgraph "Devices"
            InputDevices["Input Devices"]:::devices
            OutputDevices["Output Devices"]:::devices
        end
        Animation["Animation Engine"]:::core
        IOProtocols["IO Protocols/Transports"]:::io
        Hardware["Hardware Abstraction"]:::core
        %% Internal Connections within Core Library
        Board -->|"triggers"| InputDevices
        Board -->|"triggers"| OutputDevices
        Board -->|"activates"| Animation
        Board -->|"communicates"| IOProtocols
        IOProtocols -->|"interfaces"| Hardware
    end

    %% External Dependency
    Firmata["Firmata Protocol"]:::external
    Hardware -->|"utilizes"| Firmata

    %% CI/CD and Testing
    CI["CI/CD & Testing"]:::ci

    %% Relationships between Layers
    Docs -->|"consumes"| Board
    Examples -->|"demonstrates"| Board
    Macros -->|"enhances"| Board
    MacroInternals -->|"supports"| Macros
    CI -->|"verifies"| Board

    %% Click Events for Component Mapping
    click Board "https://github.com/dclause/hermes-five/tree/develop/hermes-five/src"
    click Hardware "https://github.com/dclause/hermes-five/tree/develop/hermes-five/src/hardware"
    click IOProtocols "https://github.com/dclause/hermes-five/tree/develop/hermes-five/src/io"
    click InputDevices "https://github.com/dclause/hermes-five/tree/develop/hermes-five/src/devices/input"
    click OutputDevices "https://github.com/dclause/hermes-five/tree/develop/hermes-five/src/devices/output"
    click Macros "https://github.com/dclause/hermes-five/tree/develop/hermes-five-macros/src"
    click Macros "https://github.com/dclause/hermes-five/blob/develop/hermes-five-macros/Cargo.toml"
    click MacroInternals "https://github.com/dclause/hermes-five/tree/develop/hermes-five-macros-internals/src"
    click MacroInternals "https://github.com/dclause/hermes-five/blob/develop/hermes-five-macros-internals/lib.rs"
    click Docs "https://github.com/dclause/hermes-five/tree/develop/docs/"
    click Examples "https://github.com/dclause/hermes-five/tree/develop/hermes-five/examples"
    click CI "https://github.com/dclause/hermes-five/tree/develop/.github/workflows"
    click CI "https://github.com/dclause/hermes-five/tree/develop/hermes-five/tests"

    %% Styles
    classDef userlayer fill:#FDF6E3,stroke:#333,stroke-width:2px;
    classDef board fill:#FFEEAD,stroke:#333,stroke-width:2px;
    classDef core fill:#D0E1F9,stroke:#333,stroke-width:2px;
    classDef devices fill:#F9D0F9,stroke:#333,stroke-width:2px;
    classDef io fill:#CFFFE5,stroke:#333,stroke-width:2px;
    classDef macro fill:#DFF9DF,stroke:#333,stroke-width:2px;
    classDef external fill:#F9D0D0,stroke:#333,stroke-width:2px;
    classDef ci fill:#FFF9C4,stroke:#333,stroke-width:2px;
```
