# jderobot/roboticsacademy architecture

> Architecture diagram of the GitHub repository jderobot/roboticsacademy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jderobot/roboticsacademy
- Repository: https://github.com/jderobot/roboticsacademy

## Overview

1. **Repository shape**
   - This is a monorepo for **JdeRobot RoboticsAcademy**, a ROS-based training platform.
   - It combines a **Django backend**, a **React/TypeScript frontend**, a large catalog of **exercise packages**, shared **robotics interface libraries**, and **Docker/RADI build scripts** for reproducible deployment.

2. **Top-level control plane**
   - The main application entrypoint is the Django project under `academy/`, launched via `manage.py`.
   - Django is responsible for the academy’s core server-side concerns: exercise/project metadata, views, serializers, admin UI, URL routing, settings, and error handling.
   - The backend is the central coordination layer between the database, the web UI, and exercise execution artifacts.

3. **Academy backend boundary**
   - `academy/models.py`, `serializers.py`, `views.py`, and `project_view.py` indicate a classic server-side domain layer exposing data to the client.
   - `academy/admin*.py` and custom admin templates show an internal management surface for maintaining exercise/catalog data.
   - `academy/file_access.py` and `academy/templates.py` suggest the backend also mediates access to generated files, templates, and exercise assets.

4. **Front-end portal**
   - `react_frontend/` is the main user-facing SPA for browsing exercises, launching/controlling them, and viewing status/content.
   - Its structure shows clear UI subdomains: routes, layouts, headers, exercise cards, file creation, status bars, visualizers, and shared contexts.
   - The SPA talks to the Django backend through `react_frontend/src/api/`, while the Django app also serves the React build and template shell.

5. **Exercise execution model**
   - Exercises are packaged as isolated directories under `exercises/`, each with its own runtime, GUI, templates, and sometimes launch files or simulation worlds.
   - A common pattern appears across many exercises: a **user algorithm** file, a **HAL** layer, a **WebGUI** layer, and a **Frequency** loop/control helper.
   - This creates a three-way boundary: user code operates on abstract hardware interfaces, the GUI visualizes state and sends control inputs, and the HAL connects to simulation/robot middleware.

6. **Shared robotics interface libraries**
   - `common/console_interfaces`, `common/gui_interfaces`, and `common/hal_interfaces` provide reusable packages for exercise implementations.
   - These libraries standardize access to robot sensors/actuators and UI behaviors across many exercises, reducing duplication.
   - The HAL packages cover core robotics concepts such as camera, motors, lidar/laser, bumper, odometry, time, and related specialized variants.

7. **Exercise families and runtime diversity**
   - The repo contains many exercise-specific stacks, including:
     - **ROS/Gazebo-style robot exercises** like `follow_turtlebot`, `package_delivery`, `drone_cat_mouse`, `visual_lander_newmanager`.
     - **Perception/vision exercises** like `object_detection`, `image_classification`, `follow_face`, `basic_computer_vision`.
     - **Navigation/localization/mapping exercises** like `laser_loc`, `global_navigation`, `montecarlo_laser_loc`, `vacuum_cleaner_loc`.
     - **Control/behavior exercises** like `autoparking`, `dynamic_window_approach`, `obstacle_avoidance`, `follow_line`.
   - Some exercises are Python-based templates, some are C++ packages, and some include React-based web GUIs or Qt-style desktop GUIs.

8. **Simulation and robotics middleware**
   - The repository is strongly tied to **ROS** and simulation tooling such as **Gazebo**, plus robot-specific launch files and world definitions.
   - Many exercises include `.launch` files, `.world` files, and YAML configs that define the simulated robot, sensors, and middleware wiring.
   - The `compose_cfg/` and `scripts/RADI/` folders indicate containerized execution environments, with variants for CPU/GPU and Linux/Windows NVIDIA setups.

9. **Data and persistence**
   - `database/` contains SQL bootstrap data for authentication and exercise databases, including initialization scripts.
   - This implies the platform persists academy content, user/auth state, and exercise definitions outside the codebase itself.
   - The backend likely uses these database artifacts to populate the exercise catalog and support authenticated academy workflows.

10. **Exercise UI rendering paths**
    - Exercises expose different UI technologies depending on generation:
      - `frontend/WebGUI.tsx` for many web-based exercises.
      - PyQt-style GUI code in legacy exercises.
      - ROS/desktop integration in some older exercises.
    - The UI layer is therefore not a single app but a set of per-exercise presentation modules, all tied into the same academy platform conventions.

11. **Testing and quality gates**
    - `tests/` covers the reusable interface libraries with dedicated suites for console, GUI, and HAL behaviors.
    - `react_frontend/cypress` contains end-to-end browser tests for layout, exercise execution, themes, explorer, and load flows.
    - GitHub Actions workflows run linting, generation, and release pipelines, which suggests the repo is continuously packaged and validated as a platform.

12. **Operational/tooling boundaries**
    - `scripts/` provides developer and release infrastructure, especially `run_academy.sh`, benchmark helpers, and RADI build tooling.
    - Documentation under `docs/` and `scripts/RADI/README.md` is part of the architecture because deployment depends on those generated container images and runtime conventions.
    - Overall, the repo is best diagrammed as a **platform core** (Django + DB + React portal) surrounded by **exercise runtimes** and **shared robotics interface packages**, with ROS/simulation and Docker acting as the execution substrate.

Main entry points: [`academy`](https://github.com/jderobot/roboticsacademy/tree/humble-devel/academy) (Academy app), [`react_frontend/src/App.tsx`](https://github.com/jderobot/roboticsacademy/blob/humble-devel/react_frontend/src/App.tsx) (React portal), [`tests`](https://github.com/jderobot/roboticsacademy/tree/humble-devel/tests) (Tests), [`academy/file_access.py`](https://github.com/jderobot/roboticsacademy/blob/humble-devel/academy/file_access.py) (Assets access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_platform["Platform core"]
  node_manage["manage.py<br/>entrypoint<br/>[manage.py]"]
  node_academy_project["Academy app<br/>django project"]
  node_academy_domain["Domain layer<br/>models/serializers/views<br/>[models.py]"]
  node_academy_assets["Assets access<br/>files/templates<br/>[file_access.py]"]
  node_react_portal["React portal<br/>SPA<br/>[App.tsx]"]
  node_react_api["API client<br/>frontend api<br/>[api.ts]"]
  node_react_ui["UI shell<br/>components"]
  node_react_state["App state<br/>contexts/helpers"]
  node_db_bootstrap[("Database seed<br/>sql bootstrap<br/>[django_auth.sql]")]
end

subgraph group_shared["Shared interfaces"]
  node_console_ifaces["Console interfaces<br/>shared pkg<br/>[package.xml]"]
  node_gui_ifaces["GUI interfaces<br/>shared pkg<br/>[package.xml]"]
  node_hal_ifaces["HAL interfaces<br/>shared pkg<br/>[package.xml]"]
end

subgraph group_exercises["Exercise runtimes"]
  node_ros_sim["ROS + Gazebo<br/>middleware/sim<br/>[gazebo.launch]"]
  node_python_exercises["Python templates<br/>exercise runtime<br/>[Frequency.py]"]
  node_cpp_exercises["C++ templates<br/>exercise runtime<br/>[main.cpp]"]
  node_webgui_exercises["WebGUIs<br/>exercise ui<br/>[WebGUI.tsx]"]
  node_legacy_gui["Legacy GUIs<br/>exercise ui<br/>[GUI.py]"]
  node_vision_family["Vision & perception<br/>exercise family"]
  node_nav_family["Navigation & mapping<br/>exercise family"]
  node_robot_family["Robot control<br/>exercise family"]
end

subgraph group_tooling["Tooling"]
  node_radi_build["RADI build<br/>docker tooling<br/>[build.sh]"]
  node_scripts["Scripts<br/>ops tooling<br/>[run_academy.sh]"]
  node_tests["Tests<br/>quality gates"]
end

node_manage -->|"starts"| node_academy_project
node_academy_project -->|"serves"| node_academy_domain
node_academy_project -->|"loads"| node_academy_assets
node_academy_project -->|"persists"| node_db_bootstrap
node_react_portal -->|"calls"| node_react_api
node_react_portal -->|"composes"| node_react_ui
node_react_portal -->|"coordinates"| node_react_state
node_react_api -->|"requests"| node_academy_project
node_academy_domain -->|"reads/writes"| node_db_bootstrap
node_react_ui -->|"renders"| node_webgui_exercises
node_academy_assets -->|"serves"| node_webgui_exercises
node_academy_assets -->|"packages"| node_python_exercises
node_academy_assets -->|"packages"| node_cpp_exercises
node_console_ifaces -->|"supports"| node_robot_family
node_gui_ifaces -->|"supports"| node_legacy_gui
node_hal_ifaces -->|"abstracts"| node_robot_family
node_ros_sim -->|"runs"| node_robot_family
node_python_exercises -.->|"includes"| node_vision_family
node_python_exercises -.->|"includes"| node_nav_family
node_cpp_exercises -.->|"includes"| node_nav_family
node_webgui_exercises -.->|"integrates"| node_react_portal
node_legacy_gui -.->|"integrates"| node_robot_family
node_scripts -->|"drives"| node_radi_build
node_scripts -->|"runs"| node_academy_project
node_radi_build -->|"packages"| node_ros_sim
node_tests -->|"validates"| node_console_ifaces
node_tests -->|"validates"| node_gui_ifaces
node_tests -->|"validates"| node_hal_ifaces
node_tests -->|"checks"| node_react_portal

click node_manage "https://github.com/jderobot/roboticsacademy/blob/humble-devel/manage.py"
click node_academy_project "https://github.com/jderobot/roboticsacademy/tree/humble-devel/academy"
click node_academy_domain "https://github.com/jderobot/roboticsacademy/blob/humble-devel/academy/models.py"
click node_academy_assets "https://github.com/jderobot/roboticsacademy/blob/humble-devel/academy/file_access.py"
click node_react_portal "https://github.com/jderobot/roboticsacademy/blob/humble-devel/react_frontend/src/App.tsx"
click node_react_api "https://github.com/jderobot/roboticsacademy/blob/humble-devel/react_frontend/src/api/api.ts"
click node_react_ui "https://github.com/jderobot/roboticsacademy/tree/humble-devel/react_frontend/src/components"
click node_react_state "https://github.com/jderobot/roboticsacademy/tree/humble-devel/react_frontend/src/contexts"
click node_db_bootstrap "https://github.com/jderobot/roboticsacademy/blob/humble-devel/database/django_auth.sql"
click node_console_ifaces "https://github.com/jderobot/roboticsacademy/blob/humble-devel/common/console_interfaces/package.xml"
click node_gui_ifaces "https://github.com/jderobot/roboticsacademy/blob/humble-devel/common/gui_interfaces/package.xml"
click node_hal_ifaces "https://github.com/jderobot/roboticsacademy/blob/humble-devel/common/hal_interfaces/package.xml"
click node_ros_sim "https://github.com/jderobot/roboticsacademy/blob/humble-devel/exercises/follow_turtlebot/launch/gazebo.launch"
click node_python_exercises "https://github.com/jderobot/roboticsacademy/blob/humble-devel/exercises/basic_computer_vision/python_template/Frequency.py"
click node_cpp_exercises "https://github.com/jderobot/roboticsacademy/blob/humble-devel/exercises/dynamic_window_approach/cpp_template/main.cpp"
click node_webgui_exercises "https://github.com/jderobot/roboticsacademy/blob/humble-devel/exercises/3d_reconstruction/frontend/WebGUI.tsx"
click node_legacy_gui "https://github.com/jderobot/roboticsacademy/blob/humble-devel/exercises/follow_face/gui/GUI.py"
click node_vision_family "https://github.com/jderobot/roboticsacademy/tree/humble-devel/exercises/object_detection"
click node_nav_family "https://github.com/jderobot/roboticsacademy/tree/humble-devel/exercises/global_navigation"
click node_robot_family "https://github.com/jderobot/roboticsacademy/tree/humble-devel/exercises/follow_turtlebot"
click node_radi_build "https://github.com/jderobot/roboticsacademy/blob/humble-devel/scripts/RADI/build.sh"
click node_scripts "https://github.com/jderobot/roboticsacademy/blob/humble-devel/scripts/run_academy.sh"
click node_tests "https://github.com/jderobot/roboticsacademy/tree/humble-devel/tests"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_manage,node_academy_project,node_academy_domain,node_academy_assets,node_react_portal,node_react_api,node_react_ui,node_react_state,node_db_bootstrap toneBlue
class node_console_ifaces,node_gui_ifaces,node_hal_ifaces toneAmber
class node_ros_sim,node_python_exercises,node_cpp_exercises,node_webgui_exercises,node_legacy_gui,node_vision_family,node_nav_family,node_robot_family toneMint
class node_radi_build,node_scripts,node_tests toneRose
```

## Components

### Platform core

Django backend, React portal, and persistence that coordinate the academy

- [manage.py](https://github.com/jderobot/roboticsacademy/blob/humble-devel/manage.py): entrypoint · Django launcher · `manage.py`
- [Academy app](https://github.com/jderobot/roboticsacademy/tree/humble-devel/academy): django project · Core server-side academy domain and routing · `academy`
- [Domain layer](https://github.com/jderobot/roboticsacademy/blob/humble-devel/academy/models.py): models/serializers/views · Metadata, project views, serializers, and admin surface · `academy/models.py`
- [Assets access](https://github.com/jderobot/roboticsacademy/blob/humble-devel/academy/file_access.py): files/templates · File access, templates, context processors, and error handling · `academy/file_access.py`
- [React portal](https://github.com/jderobot/roboticsacademy/blob/humble-devel/react_frontend/src/App.tsx): SPA · User-facing browser app for browsing and running exercises · `react_frontend/src/App.tsx`
- [API client](https://github.com/jderobot/roboticsacademy/blob/humble-devel/react_frontend/src/api/api.ts): frontend api · Client-side integration with Django endpoints · `react_frontend/src/api/api.ts`
- [UI shell](https://github.com/jderobot/roboticsacademy/tree/humble-devel/react_frontend/src/components): components · Routes, layouts, headers, cards, status bars, and visualizers · `react_frontend/src/components`
- [App state](https://github.com/jderobot/roboticsacademy/tree/humble-devel/react_frontend/src/contexts): contexts/helpers · Theme, exercise, homepage state and explorer/editor helpers · `react_frontend/src/contexts`
- [Database seed](https://github.com/jderobot/roboticsacademy/blob/humble-devel/database/django_auth.sql): sql bootstrap · Auth and exercise seed data plus initialization scripts · `database/django_auth.sql`

### Shared interfaces

Reusable robotics abstractions used by exercises

- [Console interfaces](https://github.com/jderobot/roboticsacademy/blob/humble-devel/common/console_interfaces/package.xml): shared pkg · Console abstractions reused by some exercises · `common/console_interfaces/package.xml`
- [GUI interfaces](https://github.com/jderobot/roboticsacademy/blob/humble-devel/common/gui_interfaces/package.xml): shared pkg · Threaded GUI helpers and shared presentation scaffolding · `common/gui_interfaces/package.xml`
- [HAL interfaces](https://github.com/jderobot/roboticsacademy/blob/humble-devel/common/hal_interfaces/package.xml): shared pkg · Robot hardware abstraction for sensors, actuators, and time · `common/hal_interfaces/package.xml`

### Exercise runtimes

Representative exercise families and their runtime patterns

- [ROS + Gazebo](https://github.com/jderobot/roboticsacademy/blob/humble-devel/exercises/follow_turtlebot/launch/gazebo.launch): middleware/sim · Launch files, worlds, and robot simulation wiring · `exercises/follow_turtlebot/launch/gazebo.launch`
- [Python templates](https://github.com/jderobot/roboticsacademy/blob/humble-devel/exercises/basic_computer_vision/python_template/Frequency.py): exercise runtime · Common Python exercise pattern: Frequency, HAL, WebGUI, user algorithm · `exercises/basic_computer_vision/python_template/Frequency.py`
- [C++ templates](https://github.com/jderobot/roboticsacademy/blob/humble-devel/exercises/dynamic_window_approach/cpp_template/main.cpp): exercise runtime · C++ exercise pattern with compiled HAL/Frequency/WebGUI libraries · `exercises/dynamic_window_approach/cpp_template/main.cpp`
- [WebGUIs](https://github.com/jderobot/roboticsacademy/blob/humble-devel/exercises/3d_reconstruction/frontend/WebGUI.tsx): exercise ui · Per-exercise React/WebGUI presentation layer · `exercises/3d_reconstruction/frontend/WebGUI.tsx`
- [Legacy GUIs](https://github.com/jderobot/roboticsacademy/blob/humble-devel/exercises/follow_face/gui/GUI.py): exercise ui · PyQt-style and desktop exercise interfaces · `exercises/follow_face/gui/GUI.py`
- [Vision & perception](https://github.com/jderobot/roboticsacademy/tree/humble-devel/exercises/object_detection): exercise family · Object detection, classification, face following, and image processing · `exercises/object_detection`
- [Navigation & mapping](https://github.com/jderobot/roboticsacademy/tree/humble-devel/exercises/global_navigation): exercise family · Localization, global navigation, mapping, and obstacle avoidance · `exercises/global_navigation`
- [Robot control](https://github.com/jderobot/roboticsacademy/tree/humble-devel/exercises/follow_turtlebot): exercise family · Turtlebot, drones, delivery, manipulation, and landing exercises · `exercises/follow_turtlebot`

### Tooling

Deployment, scripts, and quality gates

- [RADI build](https://github.com/jderobot/roboticsacademy/blob/humble-devel/scripts/RADI/build.sh): docker tooling · Container images and reproducible runtime builds · `scripts/RADI/build.sh`
- [Scripts](https://github.com/jderobot/roboticsacademy/blob/humble-devel/scripts/run_academy.sh): ops tooling · Run, benchmark, and development helpers · `scripts/run_academy.sh`
- [Tests](https://github.com/jderobot/roboticsacademy/tree/humble-devel/tests): quality gates · Shared interface suites and browser end-to-end checks · `tests`

## Connections

- manage.py → Academy app: starts · Bootstraps Django application
- Academy app → Domain layer: serves · Exposes academy data and views
- Academy app → Assets access: loads · Uses file/template access and error handling
- Academy app → Database seed: persists · Reads and populates catalog/auth data
- React portal → API client: calls · Browser app consumes backend API
- React portal → UI shell: composes · Routes render shared UI components
- React portal → App state: coordinates · Contexts and helpers drive portal state
- API client → Academy app: requests · HTTP boundary into Django backend
- Domain layer → Database seed: reads/writes · Domain data maps to persisted records
- UI shell → WebGUIs: renders · Embeds per-exercise WebGUI content
- Assets access → WebGUIs: serves · Delivers exercise templates and generated files
- Assets access → Python templates: packages · Provides exercise file/template access
- Assets access → C++ templates: packages · Provides exercise file/template access
- Console interfaces → Robot control: supports · Console behavior for robot exercises
- GUI interfaces → Legacy GUIs: supports · Threaded GUI helpers for desktop exercises
- HAL interfaces → Robot control: abstracts · Hardware abstraction for robot exercises
- ROS + Gazebo → Robot control: runs · Launch/world files define robot simulation
- Python templates → Vision & perception: includes · Shared Python template pattern appears in perception exercises
- Python templates → Navigation & mapping: includes · Shared Python template pattern appears in navigation exercises
- C++ templates → Navigation & mapping: includes · Compiled runtime pattern used by navigation/control exercises
- WebGUIs → React portal: integrates · Exercise-specific web UIs plug into the portal
- Legacy GUIs → Robot control: integrates · Older exercises use desktop GUIs and launch glue
- Scripts → RADI build: drives · Build and execution scripts orchestrate containers
- Scripts → Academy app: runs · Developer scripts launch the academy backend
- RADI build → ROS + Gazebo: packages · Containerized runtime carries ROS and simulation stack
- Tests → Console interfaces: validates · Interface libraries are covered by dedicated tests
- Tests → GUI interfaces: validates · Interface libraries are covered by dedicated tests
- Tests → HAL interfaces: validates · Interface libraries are covered by dedicated tests
- Tests → React portal: checks · Cypress suites validate portal flows
