# ubc-thunderbots/software architecture

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

- Interactive diagram: https://gitdiagram.com/ubc-thunderbots/software
- Repository: https://github.com/ubc-thunderbots/software
- Video tour (about a minute): https://gitdiagram.com/ubc-thunderbots/software/video

## Overview

Based on both the file tree and the README, this repository is the central “Software” and firmware repository for a robotics system that participates in RoboCup Small Size League competitions. In other words, it’s a large-scale robotics software project that combines decision-making, simulation, real‐robot embedded software, and a host of utilities (such as geometry, physics, multithreading, logging, networking, etc.) built on top of a Bazel-powered build system.

- Core Framework & Build System: Represent Bazel’s BUILD/WORKSPACE files, overall source (“src”) hierarchy, and shared utilities. This provides the structural backbone of the project.
- AI and Decision-Making Module: Represent components under src/software/ai, including the high-level play selection FSM, tactics (attacker, defender, goalkeeper, etc.), evaluation, and STP (situation “play”) modules.
- Embedded and Hardware Control: Include modules under src/software/embedded, which handle communication with hardware (GPIO, power, motor control, estop, etc.), as well as firmware tasks.
- Backend & Communication Services: Capture components such as src/software/backend and networking components under src/software/networking and src/software/estop, which bridge the decision-making (AI) with robot actuation and sensor feedback.
- Simulation & Testing: Include simulation-related modules (e.g., src/software/simulation, er_force_simulator, field_tests, simulated_tests) to represent how the system is validated in a simulation environment.
- Shared Libraries & Utilities: Represent supporting libraries for geometry (src/software/geom), physics (src/software/physics), math, multithreading, logging, sensor fusion, and others that provide essential algorithms and basic services used across components.
- Communication Protocols & Protobufs: Identify directories like src/proto and parts of extlibs that handle protocol buffers and other message translations (also relevant if the system is interacting with external controllers or simulators).

##### Interactions and relationships
- Layering: Illustrate a layered architecture where the low-level embedded services and hardware communications serve as the foundation, above which lie real-time services (e.g., logging, network communications) and on top the AI decision and planning modules.
- Inter-Module Communication: Highlight the importance of message passing via protos and shared communications libraries (for example, between networking components and the backend) to integrate simulation results with live data.
- Testing/Simulation: Show a dedicated simulation/testing block that is “wired” into the system via the AI modules and sensor fusion, outlining how simulation results can loop back into the system as inputs for refinement/testing.

##### Important architectural patterns and design principles
- Modularity: The repository is organized in a highly modular way so each component (AI, Embedded, Simulation, etc.) is nearly self-contained with its BUILD files and tests.
- Separation of Concerns: Clearly separating the decision-making (AI/stp/tactics) from the hardware control (embedded) and utilities (geometry, physics) ensures that a change in one area (like updating tactics) does not negatively impact, for example, network communication.
- Extensibility and Testability: Modules for simulation, sensor fusion, and testing utilities (present in directories like src/software/simulated_tests and src/software/test_util) illustrate an architecture designed for iterative testing and extension.

##### Relevant technologies, frameworks, and libraries
- Bazel Build System: The presence of various BUILD files and a WORKSPACE indicates Bazel is central.
- C++ and Python: Although the codebase is predominantly in C++ (given the file extensions and naming conventions), there are Python components (for example, in thunderscope and proto message translators) used for scripting or UI tasks.
- Protocol Buffers: The numerous proto definitions and message translation modules underline the role of protobufs in inter-component communication.
- Third-Party Tools: Libraries and external toolchains (like cc_toolchain resources, nanopb, Tracy, g3log) are integral and can be noted as external dependencies.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Simulation & Testing (Top Layer)
    subgraph "Simulation & Testing"
        Simulation_Main("Simulation"):::simulation
        Simulated_Tests("Simulated Tests"):::simulation
        Field_Tests("Field Tests"):::simulation
        Simulation_Main --> Simulated_Tests
        Simulation_Main --> Field_Tests
    end

    %% AI and Decision-Making Module
    subgraph "AI and Decision-Making Module"
        AI_Main("AI & Decision Making"):::ai
        AI_HL("High-Level Play Selection"):::ai
        AI_Eval("Evaluation Module"):::ai
        AI_Main --> AI_HL
        AI_Main --> AI_Eval
    end

    %% Backend & Communication Services
    subgraph "Backend & Communication Services"
        Backend_Main("Backend Services"):::backend
        Networking("Networking"):::backend
        EStop("Emergency Stop"):::backend
        Backend_Main --> Networking
        Backend_Main --> EStop
    end

    %% Embedded and Hardware Control
    subgraph "Embedded and Hardware Control"
        Embedded_Main("Embedded & Hardware Control"):::embedded
        Embedded_Services("Embedded Services"):::embedded
        Embedded_Ansible("Embedded Ansible"):::embedded
        Embedded_Main --> Embedded_Services
        Embedded_Main --> Embedded_Ansible
    end

    %% Core Framework & Build System (Bottom Layer)
    subgraph "Core Framework & Build System"
        Core_WS("WORKSPACE"):::core
        Core_BUILD("BUILD"):::core
        Core_Bazelrc(".bazelrc"):::core
        Core_Bazelversion(".bazelversion"):::core
        Core_Module("MODULE.bazel"):::core
        Core_WS --> Core_BUILD
        Core_BUILD --> Core_Bazelrc
        Core_Bazelrc --> Core_Bazelversion
        Core_Bazelversion --> Core_Module
    end

    %% Shared Libraries & Utilities (Side Component)
    subgraph "Shared Libraries & Utilities"
        Shared_Others("Shared Utilities"):::utilities
        Geometry("Geometry"):::utilities
        Physics("Physics"):::utilities
        Math("Math"):::utilities
        Multithreading("Multithreading"):::utilities
        Logger("Logger"):::utilities
    end

    %% Communication Protocols & Protobufs (Side Component)
    subgraph "Communication Protocols & Protobufs"
        Proto_Main("Communication Protocols"):::protocols
        Protobuf_Ext("External Protobufs"):::protocols
        Message_Translation("Message Translation"):::protocols
        Proto_Main --> Protobuf_Ext
        Proto_Main --> Message_Translation
    end

    %% Vertical Data Flow Connections
    Simulation_Main -->|"simulation_data"| AI_Main
    AI_Main -->|"commands"| Backend_Main
    Backend_Main -->|"actuation"| Embedded_Main
    Embedded_Main -->|"sensor_data"| AI_Main
    AI_Main -->|"simulate"| Simulation_Main

    %% Shared Utilities Usage (Dotted Connections)
    Simulation_Main -.->|"uses"| Shared_Others
    AI_Main -.->|"uses"| Shared_Others
    Backend_Main -.->|"uses"| Shared_Others
    Embedded_Main -.->|"uses"| Shared_Others

    %% Communication Protocols Connections (Dotted Connections)
    AI_Main -.->|"messages"| Proto_Main
    Backend_Main -.->|"messages"| Proto_Main
    Simulation_Main -.->|"messages"| Proto_Main

    %% Click Events for Core Framework & Build System
    click Core_WS "https://github.com/ubc-thunderbots/software/tree/master/src/WORKSPACE"
    click Core_BUILD "https://github.com/ubc-thunderbots/software/tree/master/src/BUILD"
    click Core_Bazelrc "https://github.com/ubc-thunderbots/software/blob/master/src/.bazelrc"
    click Core_Bazelversion "https://github.com/ubc-thunderbots/software/blob/master/src/.bazelversion"
    click Core_Module "https://github.com/ubc-thunderbots/software/blob/master/src/MODULE.bazel"

    %% Click Events for AI and Decision-Making Module
    click AI_Main "https://github.com/ubc-thunderbots/software/tree/master/src/software/ai"
    click AI_HL "https://github.com/ubc-thunderbots/software/tree/master/src/software/ai/hl"
    click AI_Eval "https://github.com/ubc-thunderbots/software/tree/master/src/software/ai/evaluation"

    %% Click Events for Embedded and Hardware Control
    click Embedded_Main "https://github.com/ubc-thunderbots/software/tree/master/src/software/embedded"
    click Embedded_Services "https://github.com/ubc-thunderbots/software/tree/master/src/software/embedded/services"
    click Embedded_Ansible "https://github.com/ubc-thunderbots/software/tree/master/src/software/embedded/ansible"

    %% Click Events for Backend & Communication Services
    click Backend_Main "https://github.com/ubc-thunderbots/software/tree/master/src/software/backend"
    click Networking "https://github.com/ubc-thunderbots/software/tree/master/src/software/networking"
    click EStop "https://github.com/ubc-thunderbots/software/tree/master/src/software/estop"

    %% Click Events for Simulation & Testing
    click Simulation_Main "https://github.com/ubc-thunderbots/software/tree/master/src/software/simulation"
    click Simulated_Tests "https://github.com/ubc-thunderbots/software/tree/master/src/software/simulated_tests"
    click Field_Tests "https://github.com/ubc-thunderbots/software/tree/master/src/software/field_tests"

    %% Click Events for Shared Libraries & Utilities
    click Geometry "https://github.com/ubc-thunderbots/software/tree/master/src/software/geom"
    click Physics "https://github.com/ubc-thunderbots/software/tree/master/src/software/physics"
    click Math "https://github.com/ubc-thunderbots/software/tree/master/src/software/math"
    click Multithreading "https://github.com/ubc-thunderbots/software/tree/master/src/software/multithreading"
    click Logger "https://github.com/ubc-thunderbots/software/tree/master/src/software/logger"
    click Shared_Others "https://github.com/ubc-thunderbots/software/tree/master/src/shared"

    %% Click Events for Communication Protocols & Protobufs
    click Proto_Main "https://github.com/ubc-thunderbots/software/tree/master/src/proto"
    click Protobuf_Ext "https://github.com/ubc-thunderbots/software/tree/master/src/extlibs/er_force_sim/src/protobuf"
    click Message_Translation "https://github.com/ubc-thunderbots/software/tree/master/src/proto/message_translation"

    %% Styles
    classDef core fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef embedded fill:#a9dfbf,stroke:#333,stroke-width:2px;
    classDef backend fill:#f5b7b1,stroke:#333,stroke-width:2px;
    classDef ai fill:#aed6f1,stroke:#333,stroke-width:2px;
    classDef simulation fill:#d2b4de,stroke:#333,stroke-width:2px;
    classDef utilities fill:#fad7a0,stroke:#333,stroke-width:2px;
    classDef protocols fill:#d7bde2,stroke:#333,stroke-width:2px;
```
