# derivedfunction/mdc-ubuntu architecture

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

- Interactive diagram: https://gitdiagram.com/derivedfunction/mdc-ubuntu
- Repository: https://github.com/derivedfunction/mdc-ubuntu

## Overview

##### Project type and purpose
- This is a robotics full-stack application built on ROS 2 (Humble) that fuses sensor data (Azure Kinect), user input (Xbox controller or keyboard), and vehicle actuation (miniature car) with optional SLAM (rtabmap).

##### Main components
a. Hardware
- Azure Kinect camera (RGB-D sensor)
- Laptop (runs user-input node)
- On-car computer (runs car controller node, optionally SLAM)
- Car actuators via Maestro servo controller
b. ROS 2 Nodes / Software Modules
- laptop: subscribes to Xbox/keyboard, publishes geometry_msgs/Twist or custom control topic
- mdc_car: subscribes control topic, issues servo commands via maestro.py
- (Optional) rtabmap node: subscribes to camera topics, builds map, writes/reads database file
c. Middleware and Services
- ROS 2 DDS (pub/sub layer carrying topics)
- rtabmap SQLite/DB (rtabmap_data)

##### Relationships & Data Flows
- (Optional) SLAM node (rtabmap) subscribes to camera topics → publishes /map, /odom
- laptop node reads Xbox or keyboard → publishes /cmd_vel or /steering_cmd
- mdc_car node subscribes to control topic → drives car via local Maestro API
- All nodes communicate over ROS 2 DDS (via localhost or network)

##### Architectural Patterns & Design Principles
- Modular ROS 2 nodes following single-responsibility principle
- Topic-based pub/sub decoupling sensor, control, and actuation
- Clear separation of concerns: sensing (driver), planning/mapping (rtabmap), input (laptop), actuation (mdc_car)
- Scripts orchestrate builds and launches, but do not alter runtime architecture

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Sensor Host"
        AK["Azure_Kinect_ROS_Driver"]:::sensor
    end

    subgraph "Laptop Machine"
        LP["laptop Node"]:::compute
        CTRL["Gamepad/Keyboard"]:::sensor
    end

    subgraph "Car On-Board Computer"
        MD["mdc_car Node"]:::compute
        SLAM["rtabmap Node (Optional)"]:::compute
        DB["rtabmap_data"]:::storage
        ACT["Maestro Servo Controller"]:::actuator
        CHASSIS["Car Chassis"]:::actuator
    end

    DDS["ROS 2 DDS"]:::middleware

    %% Data Flows
    AK -->|"/camera/color<br>/camera/depth<br>/tf"| DDS
    DDS -->|"camera topics"| SLAM
    SLAM -->|"/map<br>/odom"| DDS
    CTRL -->|"user input"| LP
    LP -->|"/cmd_vel<br>/steering_cmd"| DDS
    DDS -->|"control topic"| MD
    MD -->|"servo commands"| ACT
    ACT -->|"drives"| CHASSIS
    SLAM -->|"persists map"| DB

    %% Click Events
    click AK "https://github.com/derivedfunction/mdc-ubuntu/tree/main/Azure_Kinect_ROS_Driver/"
    click AK "https://github.com/derivedfunction/mdc-ubuntu/tree/main/Azure_Kinect_ROS_Driver/src/"
    click AK "https://github.com/derivedfunction/mdc-ubuntu/tree/main/Azure_Kinect_ROS_Driver/launch/"
    click LP "https://github.com/derivedfunction/mdc-ubuntu/tree/main/src/laptop/"
    click LP "https://github.com/derivedfunction/mdc-ubuntu/blob/main/src/laptop/laptop/include/controller.py"
    click LP "https://github.com/derivedfunction/mdc-ubuntu/blob/main/src/laptop/laptop/include/keyboard.py"
    click LP "https://github.com/derivedfunction/mdc-ubuntu/blob/main/src/laptop/laptop/include/input.py"
    click LP "https://github.com/derivedfunction/mdc-ubuntu/blob/main/src/laptop/laptop/include/listener.py"
    click LP "https://github.com/derivedfunction/mdc-ubuntu/blob/main/src/laptop/package.xml"
    click LP "https://github.com/derivedfunction/mdc-ubuntu/blob/main/src/laptop/setup.py"
    click MD "https://github.com/derivedfunction/mdc-ubuntu/tree/main/src/mdc_car/"
    click MD "https://github.com/derivedfunction/mdc-ubuntu/blob/main/src/mdc_car/mdc_car/main_control.py"
    click MD "https://github.com/derivedfunction/mdc-ubuntu/blob/main/src/mdc_car/mdc_car/include/maestro.py"
    click MD "https://github.com/derivedfunction/mdc-ubuntu/blob/main/src/mdc_car/package.xml"
    click MD "https://github.com/derivedfunction/mdc-ubuntu/blob/main/src/mdc_car/setup.py"
    click SLAM "https://github.com/derivedfunction/mdc-ubuntu/blob/main/Azure_Kinect_ROS_Driver/launch/slam_rtabmap.launch.py"
    click SLAM "https://github.com/derivedfunction/mdc-ubuntu/blob/main/config/rtabmap_slam.rviz"
    click DB "https://github.com/derivedfunction/mdc-ubuntu/tree/main/rtabmap_data/"
    click DB "https://github.com/derivedfunction/mdc-ubuntu/blob/main/config/nav2_params.yaml"
    click .devcontainer "https://github.com/derivedfunction/mdc-ubuntu/tree/main/.devcontainer/"
    click launch "https://github.com/derivedfunction/mdc-ubuntu/blob/main/scripts/launch.sh"
    click runcar "https://github.com/derivedfunction/mdc-ubuntu/blob/main/scripts/runcar.sh"

    %% Styles
    classDef sensor fill:#cce5ff,stroke:#3399ff,color:#003366;
    classDef compute fill:#d4edda,stroke:#28a745,color:#155724;
    classDef middleware fill:#fff3cd,stroke:#ffce54,color:#856404;
    classDef actuator fill:#f8d7da,stroke:#dc3545,color:#721c24;
    classDef storage fill:#fff3cd,stroke:#ff9933,color:#856404;
```
