# johnnwallace/cloudmav architecture

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

## Overview

##### Project’s Main Purpose and Components
- Project Type: Embedded firmware for an ESP32-based device (or similar) that handles camera functionalities, data transport, and communication.
- Key Functions: Image capture and processing (via the esp32-camera managed component); various transport methods including WiFi, UART, and websocket for communication; routing and handling of data streams; certificate-based security (as indicated by the certificates directory).

##### Major Architectural Components
a. Hardware Layer:
- ESP32 Microcontroller
- Camera Sensor (integrated via the esp32-camera component)
- UART interfaces and potentially other I/O components
b. Firmware/Application Layer (located in “cloud-deck/main”):
- Main application module (main.c) that ties all sub-systems together.
- Communication modules:
▪ wifi.c: Manages WiFi connectivity.
▪ websocket.c: Handles websocket communications.
▪ uart_transport.c & esp_transport.c: Provide data transport over UART and ESP transports.
▪ router.c: Likely routes commands/messages between different transport interfaces.
- Camera management:
▪ cam.c and related headers: Interface with the camera sensor and perform image-related operations.
- CPX module (cpx.c): Possibly for compressed image handling or other processing.
- CRTP: Likely a protocol or message format for control.
c. External/Managed Components (in “cloud-deck/managed_components”):
- esp32-camera library: Contains drivers, sensor-specific modules, and image conversion utilities.
- Multiple directories such as “conversions”, “driver”, “sensors”, and “target” which detail hardware-specific implementations.
d. Testing & Validation Modules:
- “deck-test”: Contains test implementations in C++ (via PlatformIO) for components like esp_transport, uart_transport, and router.
- “scripts”: Python scripts that seem to run connectivity and transmission tests (e.g., cam_tcp_test.py, ws_test.py, etc.).
- “tools”: Contains utility tools such as “find-mac” which could be used for probing network addresses.
e. Support Files & Configurations:
- Certificate files for secure communications (under certificates).
- CMakeLists.txt files spread across directories to define build processes.
- DevContainer configuration for containerized development environments.

▪ Data from the camera sensor flows into the Camera Module (cam.c) then possibly through CPX, before going through the various transport layers.
▪ Network-related modules (wifi.c, websocket.c) communicate with external servers or client applications.
▪ Routing and message distribution flow managed by the router module.
- An external block for Managed Components (esp32-camera library) and show its interaction with the Camera Interface.
- Testing ecosystem (deck-test, scripts, and tools) that interface with the firmware components to ensure correct behavior.

##### Architectural Patterns and Design Principles
- Component Separation: Clearly delineate each module (communication, camera, transport, routing).
- Modularity & Reuse: Highlight the use of managed external components (esp32-camera) so that sensor-specific drivers and conversions are maintained separately.
- Layered Design: Differentiate the hardware layer, firmware/application layer, and testing/diagnostic layer.
- Cross-Compilation/Multiple Targets: Note the specific directories under “managed_components” that target various ESP32 variants (esp32, esp32s2, esp32s3).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware Layer
    subgraph "Hardware Layer"
        A1["ESP32 Microcontroller"]:::hardware
        A2["Camera Sensor"]:::hardware
        A3["UART Interfaces"]:::hardware
    end

    %% Firmware/Application Layer
    subgraph "Firmware/Application Layer"
        F1["Main Firmware Application"]:::firmware
        F2["Camera Management (cam.c)"]:::firmware
        F3["CPX Module (cpx.c)"]:::firmware
        F4["WiFi Module (wifi.c)"]:::firmware
        F5["Websocket Module (websocket.c)"]:::firmware
        F6["UART Transport (uart_transport.c)"]:::firmware
        F7["ESP Transport (esp_transport.c)"]:::firmware
        F8["Routing Module (router.c)"]:::firmware
        F9["CRTP Support (crtp.h)"]:::firmware
    end

    %% External & Testing Tools
    subgraph "External & Testing Tools"
        E1["esp32-camera Library"]:::external
        E2["Certificates for Security"]:::external
        T1["Embedded Tests (deck-test)"]:::testing
        T2["Diagnostic Scripts (scripts)"]:::testing
        T3["Utility Tools (find-mac)"]:::testing
    end

    %% Hardware connections
    A2 --->|"captures"| F2
    A3 --->|"interfaces"| F6
    A2 --->|"attachedTo"| A1

    %% Firmware/Application connections
    F1 --->|"init_control"| F2
    F2 --->|"processes"| F3
    F1 --->|"init_control"| F4
    F1 --->|"init_control"| F5
    F1 --->|"init_control"| F6
    F1 --->|"init_control"| F7
    F1 --->|"routes_via"| F8
    F8 --->|"protocol"| F9

    %% Integration with external components
    F2 --->|"uses"| E1
    F1 --->|"secures"| E2
    F1 --->|"runs_on"| A1

    %% Testing & Diagnostic connections (dashed arrows)
    T1 -.->|"tests"| F1
    T2 -.->|"diagnoses"| F1
    T3 -.->|"probes"| F1

    %% Click Events
    click F1 "https://github.com/johnnwallace/cloudmav/blob/main/cloud-deck/main/main.c"
    click F2 "https://github.com/johnnwallace/cloudmav/blob/main/cloud-deck/main/cam.c"
    click F3 "https://github.com/johnnwallace/cloudmav/blob/main/cloud-deck/main/cpx.c"
    click F4 "https://github.com/johnnwallace/cloudmav/blob/main/cloud-deck/main/wifi.c"
    click F5 "https://github.com/johnnwallace/cloudmav/blob/main/cloud-deck/main/websocket.c"
    click F6 "https://github.com/johnnwallace/cloudmav/blob/main/cloud-deck/main/uart_transport.c"
    click F7 "https://github.com/johnnwallace/cloudmav/blob/main/cloud-deck/main/esp_transport.c"
    click F8 "https://github.com/johnnwallace/cloudmav/blob/main/cloud-deck/main/router.c"
    click F9 "https://github.com/johnnwallace/cloudmav/blob/main/cloud-deck/main/crtp.h"
    click E1 "https://github.com/johnnwallace/cloudmav/tree/main/cloud-deck/managed_components/espressif__esp32-camera"
    click E2 "https://github.com/johnnwallace/cloudmav/tree/main/cloud-deck/certificates"
    click T1 "https://github.com/johnnwallace/cloudmav/tree/main/deck-test"
    click T2 "https://github.com/johnnwallace/cloudmav/tree/main/scripts"
    click T3 "https://github.com/johnnwallace/cloudmav/tree/main/tools/find-mac"

    %% Styles
    classDef hardware fill:#FFD700,stroke:#B8860B,stroke-width:2px;
    classDef firmware fill:#87CEFA,stroke:#4682B4,stroke-width:2px;
    classDef external fill:#90EE90,stroke:#32CD32,stroke-width:2px;
    classDef testing fill:#FFC0CB,stroke:#FF69B4,stroke-width:2px;
```
