# cedbossneo/mowgli-docker architecture

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

- Interactive diagram: https://gitdiagram.com/cedbossneo/mowgli-docker
- Repository: https://github.com/cedbossneo/mowgli-docker

## Overview

##### Project Type and Purpose
- This is a full-stack, containerized robotics application.
- It orchestrates hardware interfaces (Mowgli device, GPS), a ROS backend (OpenMower/Mowgli software), an MQTT broker, and web UIs (Mowgli GUI & OpenMower web) via Docker Compose.
- It supports local execution on a Raspberry Pi or remote setups via TCP redirection (ser2net) or split host/mower deployments.

##### Main Components
A. Physical Layer (Host & Devices)
- Host OS (Raspberry Pi or Remote Machine) running Docker Engine
- Hardware devices:
– /dev/mowgli (Mowgli serial interface)
– /dev/gps (GPS serial interface)
B. Container Layer
1. openmower container
– ROS master and nodes: mowgli_driver, GPS/IMU fusion (ekf), planners (move_base_flex), ftc local planner, costmaps
– Mowgli GUI server (port 4006)
2. mosquitto container
– MQTT broker for telemetry & control
3. nginx (reverse-proxy)
– Serves OpenMower web app (port 4005) and proxies websocket/API to ROS/MQTT
4. ser2net container (only in serial-redirect mode)
– Exposes /dev/mowgli and /dev/gps over TCP ports (4001, 4002)
5. ublox container (optional GPS emulator)
C. Web Assets
– Flutter-based OpenMower UI (static assets under web/)
– Websocket/REST clients that communicate with backend over MQTT/WebSocket/ROS bridge
D. Configuration & Supporting Scripts
– config/ (driver, MQTT, mower configs)
– utils/ and tools/ (udev rules installer, RViz launcher, button press scripts)

##### Component Relationships & Data Flows
- Serial Data Flow:
Physical Device → Host OS /dev symlink → openmower container (or ser2net container)
In ser2net mode:
/dev/mowgli → ser2net → TCP → remote openmower container’s rosserial node
- ROS Internals:
mowgli_driver publishes sensor topics → ekf node → planner nodes → control topics
- Messaging:
ROS bridge ↔ MQTT broker (mosquitto container)
– Telemetry and commands flow via MQTT topics
- Web UI Interaction:
Browser ↔ nginx ↔ (Websocket/API) ↔ MQTT → ROS
- Remote Deployment:
Remote Host and Mower Pi each run Docker Compose; interact over network using MOWER_IP and ROS_IP variables

##### Architectural Patterns & Design Principles
- Microservices: one container per service (ROS, MQTT, reverse-proxy, device proxy)
- Message-broker pattern: decouples UI and backend via MQTT
- Device-proxy pattern: ser2net abstracts serial devices to TCP
- Layered separation: Physical → Container/Services → APIs/WebSockets → Presentation

##### Critical Details to Capture
- udev rules: mapping physical USB devices to /dev symlinks
- port mappings in docker-compose.yaml (4005, 4006, ROS ports)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        Browser["Web Browser"]:::frontend
        RViz["RViz GUI"]:::frontend
    end

    %% Communication Layer
    subgraph "Communication Layer"
        MQTTBus["MQTT Network"]:::message
        ROSBus["ROS Network"]:::backend
    end

    %% Container Layer
    subgraph "Container Layer"
        direction TB
        openmower["openmower Container\n(ROS Master & Nodes + GUI)"]:::backend
        mosquitto["mosquitto Container"]:::message
        nginx["nginx Reverse-Proxy"]:::frontend
        ser2net["ser2net Container\n(Serial-Redirect Mode)"]:::device
        ublox["ublox Emulator"]:::device
    end

    %% Physical Layer
    subgraph "Physical Layer"
        direction TB
        HostOS["Host OS\n(Raspberry Pi / Remote)"]:::device
        DevM["/dev/mowgli"]:::device
        DevG["/dev/gps"]:::device
        Udev["udev Rules & Installer"]:::device
    end

    %% Data Flows
    DevM -->|"/dev mount"| HostOS
    DevG -->|"/dev mount"| HostOS
    HostOS -->|"/dev bind mount"| openmower
    HostOS -->|"/dev TCP (4001/4002)"| ser2net
    ser2net -->|"TCP 4001/4002"| openmower
    openmower -->|"mqtt://mosquitto:1883"| mosquitto
    openmower -->|"ROS topics"| ROSBus
    mosquitto -->|"MQTT topics"| MQTTBus
    nginx -->|"ws://nginx/api"| MQTTBus
    nginx -->|"ws://nginx/ros"| ROSBus
    Browser -->|"WebSocket/HTTP"| nginx
    RViz -->|"ROS TCP"| ROSBus
    ublox -->|"UDP/TCP GPS"| openmower

    %% Docker Compose Orchestration
    composeLocal["Local Compose"]:::config
    composeSerial["Serial-Redirect Compose"]:::config
    composeRemoteHost["Remote Host Compose"]:::config
    composeRemotePi["Remote Pi Compose"]:::config

    composeLocal --> openmower
    composeLocal --> mosquitto
    composeLocal --> nginx

    composeSerial --> ser2net
    composeSerial --> openmower
    composeSerial --> mosquitto
    composeSerial --> nginx

    composeRemoteHost --> openmower
    composeRemoteHost --> mosquitto

    composeRemotePi --> openmower
    composeRemotePi --> mosquitto

    HostOS -->|".env MOWER_IP, ROS_IP"| composeLocal
    HostOS -->|".env MOWER_IP, ROS_IP"| composeSerial
    HostOS -->|".env MOWER_IP, ROS_IP"| composeRemoteHost
    HostOS -->|".env MOWER_IP, ROS_IP"| composeRemotePi

    %% Click Events
    click Udev "https://github.com/cedbossneo/mowgli-docker/blob/cedbossneo/utils/imu.sh"
    click openmower "https://github.com/cedbossneo/mowgli-docker/tree/cedbossneo/docker/openmower/Dockerfile"
    click ser2net "https://github.com/cedbossneo/mowgli-docker/blob/cedbossneo/docker-compose.ser2net.yaml"
    click mosquitto "https://github.com/cedbossneo/mowgli-docker/blob/cedbossneo/config/mqtt/mosquitto.conf"
    click nginx "https://github.com/cedbossneo/mowgli-docker/blob/cedbossneo/docker/openmower/assets/nginx.conf"
    click ublox "https://github.com/cedbossneo/mowgli-docker/tree/cedbossneo/docker/ublox/Dockerfile"
    click composeLocal "https://github.com/cedbossneo/mowgli-docker/blob/cedbossneo/docker-compose.yaml"
    click composeSerial "https://github.com/cedbossneo/mowgli-docker/blob/cedbossneo/docker-compose.ser2net.yaml"
    click composeRemoteHost "https://github.com/cedbossneo/mowgli-docker/blob/cedbossneo/docker-compose.remote.host.yaml"
    click composeRemotePi "https://github.com/cedbossneo/mowgli-docker/blob/cedbossneo/docker-compose.remote.pi.yaml"

    %% Styling
    classDef device fill:#e0f7e9,stroke:#2e7d32,color:#2e7d32;
    classDef backend fill:#e3f2fd,stroke:#1565c0,color:#1565c0;
    classDef message fill:#fff3e0,stroke:#ef6c00,color:#ef6c00;
    classDef frontend fill:#fff9c4,stroke:#f9a825,color:#f9a825;
    classDef config fill:#eceff1,stroke:#607d8b,color:#455a64;
```
