# john-trager/datadash architecture

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

## Overview

##### Main Components
- Entry/Control: The main script (datadash.py) orchestrates the overall flow based on the system state.
- Sensors & Inputs: Include modules interfacing with the camera (lib/camera.py, lib/oakdcam.py), motion detection (lib/motiondetector.py and its mock version for testing), and IMU (the calibration script and the configuration file for offsets in config/imu_offsets.json).
- User Feedback/Output: The LCD display module (lib/lcd16x2.py) provides system status.
- Data Recording & Processing: This includes components capturing and recording video (lib/datarecorder.py) and additional data like sensor parameters (lib/params.py, lib/state.py).
- Networking/Upload: The uploader (lib/uploader.py) is responsible for transmitting the collected data to the remote server (running on a secondary Raspberry Pi hosting remote video storage).
- State Machine & Workflow: Use the documented states (“idle”, “in-motion”, “wait-for-upload”, “upload-state”, “done”) to map out how data collection is managed and transitions are triggered.
- Auxiliary Scripts: The runDataDash script in the bin directory that likely ensures the application starts on boot.
- Testing Components: Although you might not include every test in the architecture, note that there’s comprehensive test coverage, for example, test_camera.py, test_display.py, etc.

##### Relationships and Data Flow
- The central controller (datadash.py) triggers hardware component functions (e.g., initializing the camera, starting the motion detection).
- In the “idle” state, the system waits until a sensor (motion detector) signals activity, then transitions to “in-motion” where the camera modules actively record.
- Once data is captured, the state machine waits (in "wait-for-upload") and then triggers the uploader when wireless connectivity is available.
- Feedback loop where if the connection fails during upload, the system cycles back to “wait-for-upload” or “idle”.

##### Architectural Patterns and Principles
- Clearly separate concerns: hardware interfacing (sensors, camera, display) is managed by individual modules, while the state machine logic encapsulates the control flow.
- How configuration data (like IMU offsets) is isolated, enhancing maintainability.
- If applicable, mention the use of modular design which aids in testing, as evident from the multiple test files provided.
- How the system supports extensions, for example future integration of GPS data or OBD-II sensor data.

##### Relevant Technologies and Interactions
- Hardware components: Raspberry Pis, Logitech webcam, MPU/IMU sensor, LCD display.
- Software interactions: Python modules for each hardware aspect, networking functions for data upload, and OS-level scripts (crontab configuration and gadget mode for remote access).
- Interfaces: Highlight that the uploader interacts with remote storage/cloud, and may include authentication and error handling (transitioning to “done” or retry state).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Boot Process
    Boot["Boot Script (runDataDash)"]:::control

    %% Core Controller
    Control["Main Controller (datadash.py)"]:::control

    %% Sensor Modules
    subgraph "Sensor Modules"
        Camera1["Camera Module (camera.py)"]:::sensor
        Camera2["Camera Module (oakdcam.py)"]:::sensor
        Motion["Motion Detector (motiondetector.py)"]:::sensor
        MockMotion["Mock Motion Detector (mock_motiondetector.py)"]:::sensor
        IMU["IMU Calibration (calibrate_imu.py)"]:::sensor
        IMUConfig["IMU Config (imu_offsets.json)"]:::sensor
    end

    %% Processing Modules
    subgraph "Processing Modules"
        Recorder["Data Recorder (datarecorder.py)"]:::process
        Params["Parameters (params.py)"]:::process
        StateMod["State (state.py)"]:::process
    end

    %% User Feedback / Output
    subgraph "Output Modules"
        LCD["LCD Display (lcd16x2.py)"]:::sensor
    end

    %% Networking / Uploading
    subgraph "Networking Modules"
        Uploader["Uploader (uploader.py)"]:::network
    end

    %% External System
    External["Remote Server"]:::external

    %% Testing Components
    subgraph "Testing Components"
        T_Camera["Test: test_camera.py"]:::testing
        T_Display["Test: test_display.py"]:::testing
        T_Motion["Test: test_motiondetector.py"]:::testing
        T_Oak["Test: test_oakd.py"]:::testing
        T_OakDebug["Test: test_oakd_debug.py"]:::testing
        T_Optimize["Test: test_optimize_md.py"]:::testing
        T_RVC["Test: test_rvc.py"]:::testing
    end

    %% Connections
    Boot -->|"triggers"| Control

    %% Control invoking Sensor Modules
    Control -->|"init"| Camera1
    Control -->|"init"| Camera2
    Control -->|"init"| Motion
    Control -.->|"used_in_tests"| MockMotion
    Control -->|"calibrate"| IMU
    Control -->|"load"| IMUConfig

    %% Control invoking Processing and Output
    Control -->|"process_data"| Recorder
    Control -->|"process_data"| Params
    Control -->|"manage_state"| StateMod
    Control -->|"display_status"| LCD

    %% Control invoking Networking and then External Upload
    Control -->|"upload_trigger"| Uploader
    Uploader -->|"transmit_data"| External

    %% Style Definitions
    classDef control fill:#F8B195,stroke:#333,stroke-width:2px;
    classDef sensor fill:#C06C84,stroke:#333,stroke-width:2px,color:#fff;
    classDef process fill:#99B898,stroke:#333,stroke-width:2px;
    classDef network fill:#355C7D,stroke:#333,stroke-width:2px,color:#fff;
    classDef external fill:#F67280,stroke:#333,stroke-width:2px;
    classDef testing fill:#B8A9C9,stroke:#333,stroke-dasharray: 5 5,stroke-width:2px;

    %% Click Events
    click Boot "https://github.com/john-trager/datadash/tree/main/bin/runDataDash"
    click Control "https://github.com/john-trager/datadash/blob/main/datadash.py"
    click Camera1 "https://github.com/john-trager/datadash/blob/main/lib/camera.py"
    click Camera2 "https://github.com/john-trager/datadash/blob/main/lib/oakdcam.py"
    click Motion "https://github.com/john-trager/datadash/blob/main/lib/motiondetector.py"
    click MockMotion "https://github.com/john-trager/datadash/blob/main/lib/mock_motiondetector.py"
    click IMU "https://github.com/john-trager/datadash/blob/main/lib/calibrate_imu.py"
    click IMUConfig "https://github.com/john-trager/datadash/blob/main/config/imu_offsets.json"
    click LCD "https://github.com/john-trager/datadash/blob/main/lib/lcd16x2.py"
    click Recorder "https://github.com/john-trager/datadash/blob/main/lib/datarecorder.py"
    click Params "https://github.com/john-trager/datadash/blob/main/lib/params.py"
    click StateMod "https://github.com/john-trager/datadash/blob/main/lib/state.py"
    click Uploader "https://github.com/john-trager/datadash/blob/main/lib/uploader.py"
    click T_Camera "https://github.com/john-trager/datadash/blob/main/test_camera.py"
    click T_Display "https://github.com/john-trager/datadash/blob/main/test_display.py"
    click T_Motion "https://github.com/john-trager/datadash/blob/main/test_motiondetector.py"
    click T_Oak "https://github.com/john-trager/datadash/blob/main/test_oakd.py"
    click T_OakDebug "https://github.com/john-trager/datadash/blob/main/test_oakd_debug.py"
    click T_Optimize "https://github.com/john-trager/datadash/blob/main/test_optimize_md.py"
    click T_RVC "https://github.com/john-trager/datadash/blob/main/test_rvc.py"
```
