# watonomous/wato_monorepo architecture

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

- Interactive diagram: https://gitdiagram.com/watonomous/wato_monorepo
- Repository: https://github.com/watonomous/wato_monorepo

## Overview

##### Project type and purpose
- This is a Dockerized ROS2 “monorepo” for an autonomous vehicle software pipeline.
- It bundles multiple ROS2 packages (perception, world modeling, planning, control, simulation, interfacing, sample apps) into Docker images and composes them via `watod` (a CLI wrapper around Docker Compose).

##### File structure
- Top-level orchestration:
- `watod`, `watod-setup-env.sh`: CLI & env management
- `modules/*.yaml`: per-module Docker Compose fragments
- `docker/...`: Dockerfiles for each ROS2 service
- Source code:
- `src/action`, `src/perception`, `src/world_modeling`, `src/interfacing`, `src/simulation`, `src/samples`, `src/wato_msgs`
- Each is a ROS2 package exposing nodes, topics, services.
- Docs and CI:
- `docs/`: developer & setup guides
- `.github/`: CI workflows, linters

##### README
- Explains “modules” which map 1:1 to functional domains (perception, planning, etc.).
- Describes `watod up/run` as the single command to spin up containers.
- Emphasizes environment selection via `ACTIVE_MODULES` → `.env` → Docker Compose.

##### Main components
A. CLI & Orchestration Layer
- watod CLI
- `.env` generator (`watod-setup-env.sh`)
- Docker Compose module loader (selects `modules/*.yaml`)
B. Container Layer
- Action (behaviour_planning, global_planning, local_planning, model_predictive_control)
- Interfacing (CAN, sensor)
- Perception (camera_detection, depth_estimation, lane_detection, lidar/det, radar_det, semseg, tracking, traffic_light)
- World Modeling (hd_map, localization, occupancy, occupancy_segmentation, motion_forecasting)
- Simulation (Carla bridge, sample node, viz, notebooks)
- Infrastructure (data_stream, foxglove, VNC)
- Samples (cpp_*/py_*)
- Each container runs one or more ROS2 nodes, mounts the corresponding `src/...` folder.
C. Communication Layer (ROS2 DDS network)
- Shared pub/sub bus: topics and services built on `wato_msgs`.
- External bridges: e.g., CARLA simulator <-> ROS2, Foxglove bridge.
D. External systems & tools
- CARLA simulator
- Foxglove visualization
- Host (for VNC, port forwarding)

##### Relationships and interactions
- All containers join a virtual network (show a “ROS2 network” backbone).
- Sensors → Interfacing → Perception → World Modeling → Action → Model Predictive Control → Actuator commands
- Simulation ↔ CARLA bridge feeds simulated sensors and consumes control commands.
- That messages are typed by `wato_msgs` packages.

##### Architectural patterns and principles
- Microservices: each ROS2 node runs in its own container; modules selected on demand.
- Pub/Sub: decoupled communication via ROS2 topics.
- Extensibility: new modules equate to new Docker-Compose fragments + Dockerfiles + ROS2 packages.
- Monorepo: source mounts drive live code changes in containers without rebuilding images.

##### Technologies & frameworks
- ROS2 (rclcpp, rclpy)
- Docker & Docker Compose
- Python & C++ (various ROS2 packages)
- CARLA simulator, Foxglove
- Tensorrt for inference in perception modules
- CI: GitHub Actions

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Orchestration Layer
    subgraph "Orchestration Layer"
        style OrchestrationLayer fill:#9f6,stroke:#333,stroke-width:2px
        watod["watod CLI"]:::orchestration
        SetupEnv["watod-setup-env.sh"]:::orchestration
        ModulesLoader["Module Loader\n(modules/*.yaml)"]:::orchestration
    end
    click watod "https://github.com/watonomous/wato_monorepo/tree/main/watod"
    click SetupEnv "https://github.com/watonomous/wato_monorepo/blob/main/watod_scripts/watod-setup-env.sh"
    click ModulesLoader "https://github.com/watonomous/wato_monorepo/blob/main/modules/docker-compose.*.yaml"

    %% Container Layer
    subgraph "Containers"
        style ContainersLayer fill:none,stroke:#333,stroke-dasharray: 5 5
        subgraph "Action" 
            style ActionGroup fill:#6cf,stroke:#333
            ActionGroupNode["Action Modules\n(behaviour, global, local, mpc)"]:::container
        end
        subgraph "Interfacing"
            style InterfacingGroup fill:#6cf,stroke:#333
            InterfacingNode["Interfacing Modules\n(CAN, Sensor)"]:::container
        end
        subgraph "Perception"
            style PerceptionGroup fill:#6cf,stroke:#333
            PerceptionNode["Perception Modules\n(camera, depth, lane, lidar, radar, semseg, tracking, traffic_light)"]:::container
        end
        subgraph "World Modeling"
            style WorldModelingGroup fill:#6cf,stroke:#333
            WorldModelingNode["World Modeling Modules\n(hd_map, localization, occupancy, occupancy_segmentation, motion_forecasting)"]:::container
        end
        subgraph "Simulation"
            style SimulationGroup fill:#6cf,stroke:#333
            SimulationNode["Simulation Modules\n(CARLA bridge, sample, viz, notebooks)"]:::container
        end
        subgraph "Infrastructure"
            style InfrastructureGroup fill:#6cf,stroke:#333
            InfrastructureNode["Infrastructure Modules\n(data_stream, foxglove, VNC)"]:::container
        end
        subgraph "Samples"
            style SamplesGroup fill:#6cf,stroke:#333
            SamplesNode["Sample Apps\n(C++ & Python)"]:::container
        end
    end

    %% Communication Layer
    ROSBus("ROS2 DDS Network\n(pub/sub bus)"):::bus

    %% External Systems
    subgraph "External Systems"
        style ExternalLayer fill:none,stroke:#333,stroke-dasharray: 5 5
        CARLA["CARLA Simulator"]:::external
        Foxglove["Foxglove Visualization"]:::external
        Host["Host (VNC, Ports)"]:::external
    end

    %% Connections
    watod -->|invokes| ModulesLoader
    ModulesLoader -->|configures| ActionGroupNode
    ModulesLoader -->|configures| InterfacingNode
    ModulesLoader -->|configures| PerceptionNode
    ModulesLoader -->|configures| WorldModelingNode
    ModulesLoader -->|configures| SimulationNode
    ModulesLoader -->|configures| InfrastructureNode
    ModulesLoader -->|configures| SamplesNode

    ActionGroupNode -->|runs ROS2 nodes| ROSBus
    InterfacingNode -->|runs ROS2 nodes| ROSBus
    PerceptionNode -->|runs ROS2 nodes| ROSBus
    WorldModelingNode -->|runs ROS2 nodes| ROSBus
    SimulationNode -->|runs ROS2 nodes| ROSBus
    InfrastructureNode -->|runs ROS2 nodes| ROSBus
    SamplesNode -->|runs ROS2 nodes| ROSBus

    SimulationNode <-->|simulated sensors & commands| CARLA
    InfrastructureNode -->|bridge| Foxglove
    InfrastructureNode -->|VNC access| Host

    ROSBus -->|topics typed by wato_msgs| ActionGroupNode
    ROSBus -->|topics typed by wato_msgs| InterfacingNode

    %% Styles
    classDef orchestration fill:#9f6,stroke:#333,stroke-width:1px
    classDef container fill:#6cf,stroke:#333,stroke-width:1px
    classDef bus fill:#f96,stroke:#333,stroke-width:2px,stroke-dasharray: 4 2
    classDef external fill:#c9f,stroke:#333,stroke-width:1px
```
