# modular-autonomous-robotic-systems/neurorobotics-ws architecture

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

- Interactive diagram: https://gitdiagram.com/modular-autonomous-robotic-systems/neurorobotics-ws
- Repository: https://github.com/modular-autonomous-robotic-systems/neurorobotics-ws

## Overview

##### Project type and purpose
- This project is not a classic web or mobile app but a Docker-based robotics development environment. It automates building and running multiple Docker images/containers that host ROS-based SLAM, calibration, visualization (Pangolin), and related toolchains. The “djinn” script is the entry point for installing prerequisites, building images, and starting containers for various subsystems (NRT, Kalibr, Skynet-ROS, etc.).

##### File structure
- Top‐level scripts/ directory (djinn, install.sh, start.sh, build.sh, etc.) implements the orchestration CLI.
- docker/ contains subdirectories for each Docker image:
- base/ – generic base environment
- ros/ – ROS over base
- nrt/ (camera, pangolin) – real-time modules
- ext/ contains calibration toolchains (kalibr, allan_variance_ros) each with its own Dockerfile.
- config/ holds JSON settings for different hardware/environments and an RViz config.
- ros_ws/ is presumably where ROS packages live or get checked out by scripts.
- .gitmodules indicates some repos are embedded as submodules (likely ros packages).

##### README for additional insights
- “djinn install --docker --ssh --git” sets up host dependencies, clones repos, builds all Docker images.
- “djinn init docker [nrt|kalibr]” builds selected images & starts containers.
- “djinn up nrt”/“djinn exec nrt bash” show the typical workflow of interacting with containers.
- External dependencies (BFX, repos in ext/) must be manually placed.

##### Detail without overthinking
- Explicitly show:
- Build phase (scripts → Dockerfiles → images)
- Runtime phase (containers ← volume mounts ← host, container interconnections)
- External dependencies (Git repos, X server)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer Host and Orchestration
    subgraph "Developer Host"
        direction TB
        DJINN["djinn CLI & Orchestration"]:::orchestration
        INSTALL["install.sh"]:::orchestration
        BUILD["build.sh"]:::orchestration
        START["start.sh"]:::orchestration
        DOCKER_BUILD["docker-build.sh"]:::orchestration
        DOCKER_SETUP["docker-setup.sh"]:::orchestration
        BUILD_ROS["build_ros_packages.sh"]:::orchestration
    end

    %% Docker Control Plane
    DJINN -->|"invokes"| DOCKER_ENGINE["Docker Engine (Daemon)"]:::control

    %% Build Phase
    subgraph "Build Phase"
        direction TB
        BASE_IMG["Base Image"]:::image
        ROS_IMG["ROS Image"]:::image
        NRT_CAM_IMG["NRT Camera Image"]:::image
        PANGOLIN_IMG["Pangolin Image"]:::image
        CALIB_IMG["Calibration Image"]:::image
        ALLAN_IMG["Allan Variance Image"]:::image
        KALIBR_IMG["Kalibr Image"]:::image
    end

    DOCKER_ENGINE -->|"build base"| BASE_IMG
    BASE_IMG -->|"build ros"| ROS_IMG
    DOCKER_ENGINE -->|"build nrt camera"| NRT_CAM_IMG
    DOCKER_ENGINE -->|"build pangolin"| PANGOLIN_IMG
    DOCKER_ENGINE -->|"build calibration"| CALIB_IMG
    CALIB_IMG -->|"includes allan tool"| ALLAN_IMG
    CALIB_IMG -->|"includes kalibr tool"| KALIBR_IMG

    %% Runtime Phase
    subgraph "Runtime Phase"
        direction TB
        BASE_CONT["Base Container"]:::container
        ROS_CONT["ROS Container"]:::container
        NRT_CAM_CONT["NRT Camera Container"]:::container
        PANGOLIN_CONT["Pangolin Container"]:::container
        CALIB_CONT["Calibration Container"]:::container
    end

    DOCKER_ENGINE -->|"run base"| BASE_CONT
    DOCKER_ENGINE -->|"run ros"| ROS_CONT
    DOCKER_ENGINE -->|"run nrt camera"| NRT_CAM_CONT
    DOCKER_ENGINE -->|"run pangolin"| PANGOLIN_CONT
    DOCKER_ENGINE -->|"run calibration"| CALIB_CONT

    %% Volume Mounts
    CONFIG["config/"]:::volume
    EXT["ext/"]:::volume
    ROS_WS["ros_ws/"]:::volume

    CONFIG --> BASE_CONT
    CONFIG --> ROS_CONT
    CONFIG --> NRT_CAM_CONT
    EXT --> CALIB_CONT
    ROS_WS --> ROS_CONT
    ROS_WS --> NRT_CAM_CONT

    %% External Dependencies
    subgraph "External Services"
        direction TB
        GITHUB["GitHub Repos"]:::external
        XSERVER["Host X Server"]:::external
        GITMODULES[".gitmodules"]:::external
    end

    DJINN -->|"clones repos"| GITHUB
    GITHUB --> ROS_WS
    DJINN --> GITMODULES
    PANGOLIN_CONT -->|"GUI forwarding"| XSERVER

    %% Click Events
    click DJINN "https://github.com/modular-autonomous-robotic-systems/neurorobotics-ws/tree/master//djinn"
    click INSTALL "https://github.com/modular-autonomous-robotic-systems/neurorobotics-ws/blob/master//scripts/install.sh"
    click BUILD "https://github.com/modular-autonomous-robotic-systems/neurorobotics-ws/blob/master//scripts/build.sh"
    click START "https://github.com/modular-autonomous-robotic-systems/neurorobotics-ws/blob/master//scripts/start.sh"
    click DOCKER_BUILD "https://github.com/modular-autonomous-robotic-systems/neurorobotics-ws/blob/master//scripts/docker-build.sh"
    click DOCKER_SETUP "https://github.com/modular-autonomous-robotic-systems/neurorobotics-ws/blob/master//scripts/docker-setup.sh"
    click BUILD_ROS "https://github.com/modular-autonomous-robotic-systems/neurorobotics-ws/blob/master//scripts/build_ros_packages.sh"
    click BASE_IMG "https://github.com/modular-autonomous-robotic-systems/neurorobotics-ws/tree/master//docker/base/Dockerfile"
    click ROS_IMG "https://github.com/modular-autonomous-robotic-systems/neurorobotics-ws/tree/master//docker/base/ros/Dockerfile"
    click NRT_CAM_IMG "https://github.com/modular-autonomous-robotic-systems/neurorobotics-ws/tree/master//docker/nrt/camera/Dockerfile"
    click PANGOLIN_IMG "https://github.com/modular-autonomous-robotic-systems/neurorobotics-ws/tree/master//docker/nrt/pangolin/Dockerfile"
    click CALIB_IMG "https://github.com/modular-autonomous-robotic-systems/neurorobotics-ws/tree/master//ext/calibration/Dockerfile"
    click ALLAN_IMG "https://github.com/modular-autonomous-robotic-systems/neurorobotics-ws/tree/master//ext/calibration/allan_variance_ros/"
    click KALIBR_IMG "https://github.com/modular-autonomous-robotic-systems/neurorobotics-ws/tree/master//ext/calibration/kalibr/"
    click GITMODULES "https://github.com/modular-autonomous-robotic-systems/neurorobotics-ws/blob/master//.gitmodules"
    click ROS_WS "https://github.com/modular-autonomous-robotic-systems/neurorobotics-ws/tree/master//ros_ws/"

    %% Styles
    classDef orchestration fill:#f9f,stroke:#333,stroke-width:2px
    classDef control fill:#bbf,stroke:#333,stroke-width:2px
    classDef image fill:#bfb,stroke:#333,stroke-width:2px
    classDef container fill:#fbf,stroke:#333,stroke-width:2px
    classDef volume fill:#ffb,stroke:#333,stroke-width:2px
    classDef external fill:#ccc,stroke:#333,stroke-width:2px
```
