# berryerlouis/hexapodcpp architecture

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

- Interactive diagram: https://gitdiagram.com/berryerlouis/hexapodcpp
- Repository: https://github.com/berryerlouis/hexapodcpp

## Overview

##### Overall Project Breakdown
- Two major subsystems:
- The Embedded/Firmware Layer (located in the src directory and associated unit tests, unittests, Makefile/CMakeLists, etc.)
- The HMI/User Interface Layer (located in the HMI directory with HTML, JavaScript, CSS, and related configuration files)

##### Main Components to Highlight
a. HMI (Frontend Interface):
- HMI/index.html, HMI/styles, and HMI/js folders form the GUI for the robot.
- External libraries or browser capabilities (if any are documented) and show data communication (through WebSocket or serial communication) between the browser and the backend.

b. Embedded/Firmware Code (Backend/Robot Control):
- The src directory is split into several domains:
- Bot – the main logic representing the hexapod robot’s structure and behavior.
- Cluster – which groups related functionalities for different hardware aspects (Battery, Body, General, IMU, Proximity, Servo). This indicates a modular design where each “cluster” abstracts a hardware component of the robot.
- Component – these directories encapsulate hardware interfacing (Battery, Communication, Display, Imu, LED, Proximity sensors, Servos, etc.) helping in separating concerns. Interfaces and Observers are used for software decoupling.
- Driver – low-level drivers for hardware interfaces like ADC, GPIO, UART, TWI, and others. Note how there are both standard and X64 implementations for testing or simulation purposes.
- Service – higher-level services that incorporate multiple components (e.g., ServiceBattery, ServiceDisplay, ServiceControl) to coordinate actions and manage events.
- Core and Misc – include utilities and fundamental interfaces for interoperation (such as Event Management, Logging, Maths, etc.)

- Flow from low-level hardware drivers up through component interfaces and service layers to the Bot’s control logic.

c. Supporting Infrastructure
- Unit Tests: The unittests directory is extensive, covering tests for clusters, components, services, and mocks for drivers. This reinforces the modular and test-driven design.
- Build and Deployment Tools: Mention the CMakeLists.txt files, Makefile, and relevant scripts in the bin/dev and bin/prod directories that are used for building, flashing, testing, and uploading the firmware.
- External Dependencies: Note dependencies like avr-gcc (for compiling firmware for microcontrollers) and uncrustify (for code formatting).

##### Relationships and Interactions
- UI (HMI) initiates commands that are structured as messages (see HMI/js/protocol) and sent to the backend.
- The backend (firmware) processes these messages through the protocol (Cluster/Protocol files) and directs them through service layers to the appropriate drivers/components.
- The driver modules interact with physical sensors/actuators (such as battery, IMU, proximity sensors, servos) that are abstracted by clusters and managed via services.
- Unit test frameworks validate the functionality of clusters, components, and services. Connect these tests to the respective modules showing the testing harness.
- That the build, prebuild, and upload scripts (in bin/dev and bin/prod) orchestrate the compilation and deployment to the hardware.

##### Architectural Patterns and Design Principles
- The design appears modular, heavily separating different concerns:
- Clusters and Components: Abstraction layers to modularize hardware and logical functions.
- Service Layer: Central coordination of different modules using event dispatching and listener interfaces.
- Dependency Injection and Observer Patterns: Evidenced by observer interfaces (e.g., for battery state, sensor observation) for decoupling.
- Patterns when drawing components as distinct modules with defined interfaces.

##### Technologies and Frameworks
- HMI: HTML/JavaScript/CSS (with modules for GUI components, protocol processing).
- Backend: C++ with CMake and Make. Libraries in use include standard firmware drivers, hardware abstraction layers (for ADC, GPIO, UART, etc.), and unit testing frameworks.
- Tools: avr-gcc for compiling for microcontrollers, uncrustify for code formatting, and CI via GitHub Actions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% HMI Layer
    subgraph "HMI (Frontend)"
        HMI_HTML["GUI (index.html)"]:::hmi
        HMI_Styles["Styles (CSS)"]:::hmi
        HMI_JS["JavaScript Modules (JS)"]:::hmi
    end

    %% Firmware/Embedded Layer
    subgraph "Firmware (Embedded)"
        BOT["Main Application Bot"]:::firmware
        CLUSTERS["Cluster Modules"]:::firmware
        SERVICES["Service Layers"]:::firmware
        COMPONENTS["Hardware Interfaces"]:::firmware
        DRIVERS["Low-Level Drivers"]:::firmware
        CORE["Core Utilities (Core)"]:::firmware
        MISC["Core Utilities (Misc)"]:::firmware
    end

    %% Infrastructure: Build & Testing
    subgraph "Supporting Infrastructure"
        UNITTESTS["Unit Tests"]:::infrastructure
        MAKEFILE["Makefile"]:::infrastructure
        CMAKE["CMakeLists.txt"]:::infrastructure
        DEV_SCRIPTS["Dev Scripts (bin/dev)"]:::infrastructure
        PROD_SCRIPTS["Prod Scripts (bin/prod)"]:::infrastructure
        HMI_UNITTESTS["HMI Unit Tests"]:::infrastructure
    end

    %% Connections between HMI and Firmware
    HMI_JS -->|"commandMessages"| BOT
    HMI_HTML -->|"renders interface"| HMI_JS
    HMI_Styles -->|"styles"| HMI_HTML

    %% Internal Firmware Flow
    BOT -->|"delegates"| CLUSTERS
    CLUSTERS -->|"processes and routes"| SERVICES
    SERVICES -->|"controls"| COMPONENTS
    SERVICES -->|"manages"| DRIVERS
    COMPONENTS -->|"interfaces with"| DRIVERS
    DRIVERS -->|"communicates with"| CORE
    DRIVERS -->|"communicates with"| MISC

    %% Infrastructure connections
    UNITTESTS ---|"tests"| BOT
    UNITTESTS ---|"tests"| CLUSTERS
    UNITTESTS ---|"tests"| SERVICES
    HMI_UNITTESTS ---|"tests"| HMI_JS

    DEV_SCRIPTS ---|"build/deploy"| BOT
    PROD_SCRIPTS ---|"build/deploy"| BOT
    MAKEFILE ---|"build"| BOT
    CMAKE ---|"build"| BOT

    %% Styles
    classDef hmi fill:#AED6F1,stroke:#2E86C1,stroke-width:2px;
    classDef firmware fill:#ABEBC6,stroke:#27AE60,stroke-width:2px;
    classDef infrastructure fill:#F9E79F,stroke:#F5B041,stroke-width:2px;

    %% Click Events for HMI Components
    click HMI_HTML "https://github.com/berryerlouis/hexapodcpp/blob/develop/HMI/index.html"
    click HMI_Styles "https://github.com/berryerlouis/hexapodcpp/blob/develop/HMI/styles/style.css"
    click HMI_JS "https://github.com/berryerlouis/hexapodcpp/tree/develop/HMI/js/"

    %% Click Events for Firmware Components
    click BOT "https://github.com/berryerlouis/hexapodcpp/tree/develop/src/Bot"
    click CLUSTERS "https://github.com/berryerlouis/hexapodcpp/tree/develop/src/Cluster"
    click COMPONENTS "https://github.com/berryerlouis/hexapodcpp/tree/develop/src/Component"
    click DRIVERS "https://github.com/berryerlouis/hexapodcpp/tree/develop/src/Driver"
    click SERVICES "https://github.com/berryerlouis/hexapodcpp/tree/develop/src/Service"
    click CORE "https://github.com/berryerlouis/hexapodcpp/tree/develop/src/Core"
    click MISC "https://github.com/berryerlouis/hexapodcpp/tree/develop/src/Misc"

    %% Click Events for Testing and Build Infrastructure
    click UNITTESTS "https://github.com/berryerlouis/hexapodcpp/tree/develop/unittests/"
    click HMI_UNITTESTS "https://github.com/berryerlouis/hexapodcpp/tree/develop/HMI/unittests/"
    click DEV_SCRIPTS "https://github.com/berryerlouis/hexapodcpp/tree/develop/bin/dev/"
    click PROD_SCRIPTS "https://github.com/berryerlouis/hexapodcpp/tree/develop/bin/prod/"
    click MAKEFILE "https://github.com/berryerlouis/hexapodcpp/tree/develop/Makefile"
    click CMAKE "https://github.com/berryerlouis/hexapodcpp/blob/develop/CMakeLists.txt"
```
