How jderobot/roboticsacademy works
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 Academy app · App.tsx React portal · tests Tests · file_access.py Assets access
Components 23
Platform core
Django backend, React portal, and persistence that coordinate the academy
- manage.py · Django launcher
manage.py - Academy app · Core server-side academy domain and routing
academy - Domain layer · Metadata, project views, serializers, and admin surface
academy/models.py - Assets access · File access, templates, context processors, and error handling
academy/file_access.py - React portal · User-facing browser app for browsing and running exercises
react_frontend/src/App.tsx - API client · Client-side integration with Django endpoints
react_frontend/src/api/api.ts - UI shell · Routes, layouts, headers, cards, status bars, and visualizers
react_frontend/src/components - App state · Theme, exercise, homepage state and explorer/editor helpers
react_frontend/src/contexts - Database seed · Auth and exercise seed data plus initialization scripts
database/django_auth.sql
Shared interfaces
Reusable robotics abstractions used by exercises
- Console interfaces · Console abstractions reused by some exercises
common/console_interfaces/package.xml - GUI interfaces · Threaded GUI helpers and shared presentation scaffolding
common/gui_interfaces/package.xml - HAL interfaces · Robot hardware abstraction for sensors, actuators, and time
common/hal_interfaces/package.xml
Exercise runtimes
Representative exercise families and their runtime patterns
- ROS + Gazebo · Launch files, worlds, and robot simulation wiring
exercises/follow_turtlebot/launch/gazebo.launch - Python templates · Common Python exercise pattern: Frequency, HAL, WebGUI, user algorithm
exercises/basic_computer_vision/python_template/Frequency.py - C++ templates · C++ exercise pattern with compiled HAL/Frequency/WebGUI libraries
exercises/dynamic_window_approach/cpp_template/main.cpp - WebGUIs · Per-exercise React/WebGUI presentation layer
exercises/3d_reconstruction/frontend/WebGUI.tsx - Legacy GUIs · PyQt-style and desktop exercise interfaces
exercises/follow_face/gui/GUI.py - Vision & perception · Object detection, classification, face following, and image processing
exercises/object_detection - Navigation & mapping · Localization, global navigation, mapping, and obstacle avoidance
exercises/global_navigation - Robot control · Turtlebot, drones, delivery, manipulation, and landing exercises
exercises/follow_turtlebot
Tooling
Deployment, scripts, and quality gates
- RADI build · Container images and reproducible runtime builds
scripts/RADI/build.sh - Scripts · Run, benchmark, and development helpers
scripts/run_academy.sh - Tests · Shared interface suites and browser end-to-end checks
tests
Connections 29
- 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