# blackfrogsftc6134/into_the_deep_worlds architecture

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

- Interactive diagram: https://gitdiagram.com/blackfrogsftc6134/into_the_deep_worlds
- Repository: https://github.com/blackfrogsftc6134/into_the_deep_worlds

## Overview

##### Project type and purpose
- This is an Android-based robot control system (the FTC Robot Controller) plus accompanying user code (TeamCode) and a small Java test harness (MeepMeepTesting). It’s a full-stack mobile control application that runs on an Android device (phone or Control Hub), communicates with a Driver Station over Wi-Fi Direct, and drives hardware modules (Expansion Hubs, sensors, motors) via USB/FTDI and I²C.

##### File structure
- Top-level modules (defined in settings.gradle):
- FtcRobotController – the Android app (src/main/java/org/firstinspires/ftc/robotcontroller…, AndroidManifest.xml, res/)
- TeamCode – the team’s Java OpModes and libraries (src/main/java/org/firstinspires/ftc/teamcode…)
- MeepMeepTesting – a standalone Java test (src/main/java/com/example/meepmeeptesting)
- Build scripts: root build.gradle, build.common.gradle, build.dependencies.gradle, Gradle wrapper under gradle/, settings.gradle.
- .github contains CI/contribution templates.
- doc/ and libs/ hold legal docs, media, and keystores.

##### README for additional insights
- Confirms that FtcRobotController builds an Android app to control an FTC robot.
- Explains OpMode samples in external/samples and user code in TeamCode.
- Lists dependencies (Android Studio Ladybug, Java 1.8) and external docs (Blocks, OnBot Java, Javadoc, online tutorials).

##### Main components
a. Android Device (Robot Controller)
- Presentation/UI Layer
- FtcRobotControllerActivity (layouts in res/layout, menus in res/menu)
- Web server for Blocks/OnBot Java (via WebHandlerRegistrar)
- OpMode Framework
- FtcOpModeRegister, OpModeManager, LinearOpMode/OpMode base classes
- Annotation processor (OpModeAnnotationProcessor.jar) to register TeamCode classes
- Hardware Abstraction Layer
- HardwareMap (DigitalChannel, DcMotor, Servo, IMU, etc.)
- Device interface modules (LegacyModule, ModernRoboticsUsbDeviceInterfaceModule)
- Low-Level Drivers
- USB/FTDI layer (Robocol socket, ReadWriteRunnable)
- I²C (I2cDeviceSynch)
- Resources & Config
- res/xml device_filter, app_settings, teamwebcamcalibrations
- External Libraries
- OpenCV/EasyOpenCV, AprilTag, TensorFlow (for vision processors)
b. TeamCode Module (User OpModes)
- Drive/trajectory libraries (SampleMecanumDrive, SampleTankDrive)
- Subsystems (ArmMech, Claw, Pivot, etc.)
- Opmode definitions (iterative & linear) under drive/opmode, opmode, test, trajectorysequence
c. MeepMeepTesting
- Simple Java program (MeepMeepTesting.java) for off-device testing
d. Build & CI
- Gradle Wrapper → resolves dependencies → compiles modules into APKs
- GitHub Actions/triggers via .github templates for PRs and contributions

##### Relationships and interactions
- Driver Station App ←Wi-Fi Direct→ Robot Controller App (Robocol/TCP)
- Robot Controller App ←USB/FTDI & I²C→ Expansion Hubs, Control Hub, sensors, motors
- TeamCode classes → loaded at runtime by OpModeManager inside Robot Controller
- Blocks/OnBot Java front-end (browser) ←HTTP→ Robot Controller embedded server
- Gradle build → outputs Robot Controller APK + TeamCode library → deployed to Android device

##### Architectural patterns & design principles
- Android MVC/MVP: Activities (View/Controller), resource layouts (View), HW abstraction (Model)
- Plugin/Annotation-scanning: user OpModes are automatically discovered and registered
- Layered design: Presentation → Control Framework → Hardware Abstraction → Drivers → OS
- Modularity: separate Gradle modules for core SDK (FtcRobotController), user code (TeamCode), tests

##### Technologies & frameworks
- Java 1.8, Android SDK Ladybug
- Gradle build system
- FTDI/USB drivers, I²C device sync
- OpenCV, EasyOpenCV, AprilTag, TensorFlow Lite
- Android WebView/HTTP server for Blocks & OnBot Java
- JUnit (if present in MeepMeepTesting)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    DriverStation["Driver Station App"]:::external
    BlocksEditor["Blocks/OnBot Java Editor"]:::external

    %% Robot Controller App
    subgraph "Robot Controller App"
        direction TB
        subgraph "UI Layer"
            direction TB
            UIActivity["FtcRobotControllerActivity"]:::android
            Layout["activity_ftc_controller.xml"]:::android
        end
        subgraph "Web Server"
            direction TB
            WebServer["WebHandlerRegistrar (HTTP)"]:::android
        end
        subgraph "OpMode Framework"
            direction TB
            OpModeReg["FtcOpModeRegister"]:::android
            OpModeMgr["OpModeManager"]:::android
            AnnotationProc["OpModeAnnotationProcessor (jar)"]:::android
        end
        subgraph "Hardware Abstraction Layer"
            direction TB
            HWMap["HardwareMap"]:::android
            DeviceInterfaces["Device Interfaces"]:::android
        end
        subgraph "Low-Level Drivers"
            direction TB
            USB["USB/FTDI & Robocol"]:::android
            I2C["I2C (I2cDeviceSynch)"]:::android
        end
        subgraph "Resources & Config"
            direction TB
            AppSettings["app_settings.xml"]:::android
            DeviceFilter["device_filter.xml"]:::android
            Sounds["gold.wav / silver.wav"]:::android
            Strings["strings.xml"]:::android
        end
        subgraph "External Libraries"
            direction TB
            Vision["OpenCV/AprilTag/TensorFlow"]:::android
        end
    end

    %% TeamCode Module
    subgraph "TeamCode Module"
        direction TB
        Samples["SampleMecanumDrive, SampleTankDrive"]:::user
        Subsystems["Subsystems (ArmMech, Claw, Pivot, ...)"]:::user
        UserOpModes["OpMode Definitions"]:::user
        AnnotationJar["OpModeAnnotationProcessor.jar"]:::user
    end

    %% MeepMeep Testing
    Meep["MeepMeepTesting"]:::test

    %% Build & CI
    subgraph "Build & CI"
        direction TB
        SettingsGradle["settings.gradle"]:::ci
        GradleRoot["build.gradle (root)"]:::ci
        CommonGradle["build.common.gradle"]:::ci
        DepsGradle["build.dependencies.gradle"]:::ci
        GitHub[".github templates"]:::ci
        Wrapper["gradle-wrapper.properties"]:::ci
        Scripts["gradlew / gradlew.bat"]:::ci
        FtcBuild["FtcRobotController APK"]:::ci
        TeamCodeBuild["TeamCode Library"]:::ci
    end

    %% Hardware Devices
    HardwareDevices["Motors, Sensors, Hubs"]:::hardware

    %% Connections
    DriverStation -->|"Wi-Fi Direct"| UIActivity
    BlocksEditor -->|"HTTP"| WebServer

    AnnotationJar -->|"compile-time"| OpModeReg
    OpModeReg -->|"registers"| OpModeMgr
    Samples -->|"runtime load"| OpModeMgr
    UserOpModes -->|"runtime load"| OpModeMgr
    OpModeMgr -->|"invokes"| UserOpModes
    AnnotationProc -.->|"annotation processing"| AnnotationJar

    OpModeMgr -->|"uses"| HWMap
    HWMap --> DeviceInterfaces
    DeviceInterfaces --> USB
    DeviceInterfaces --> I2C
    USB -->|"drives"| HardwareDevices
    I2C --> HardwareDevices

    Vision --> OpModeMgr

    GradleRoot --> SettingsGradle
    GradleRoot --> CommonGradle
    GradleRoot --> DepsGradle
    GradleRoot --> Wrapper
    GradleRoot --> Scripts
    GradleRoot --> FtcBuild
    GradleRoot --> TeamCodeBuild

    %% Click Events
    click UIActivity "https://github.com/blackfrogsftc6134/into_the_deep_worlds/blob/main/FtcRobotController/src/main/java/org/firstinspires/ftc/robotcontroller/internal/FtcRobotControllerActivity.java"
    click Layout "https://github.com/blackfrogsftc6134/into_the_deep_worlds/blob/main/FtcRobotController/src/main/res/layout/activity_ftc_controller.xml"
    click OpModeReg "https://github.com/blackfrogsftc6134/into_the_deep_worlds/blob/main/FtcRobotController/src/main/java/org/firstinspires/ftc/robotcontroller/internal/FtcOpModeRegister.java"
    click DeviceInterfaces "https://github.com/blackfrogsftc6134/into_the_deep_worlds/tree/main/FtcRobotController/src/main/java/org/firstinspires/ftc/robotcontroller/external"
    click DeviceFilter "https://github.com/blackfrogsftc6134/into_the_deep_worlds/blob/main/FtcRobotController/src/main/res/xml/device_filter.xml"
    click AppSettings "https://github.com/blackfrogsftc6134/into_the_deep_worlds/blob/main/FtcRobotController/src/main/res/xml/app_settings.xml"
    click Sounds "https://github.com/blackfrogsftc6134/into_the_deep_worlds/blob/main/FtcRobotController/src/main/res/raw/gold.wav"
    click Strings "https://github.com/blackfrogsftc6134/into_the_deep_worlds/blob/main/FtcRobotController/src/main/res/values/strings.xml"
    click Samples "https://github.com/blackfrogsftc6134/into_the_deep_worlds/tree/main/FtcRobotController/src/main/java/org/firstinspires/ftc/robotcontroller/external/samples"
    click AnnotationJar "https://github.com/blackfrogsftc6134/into_the_deep_worlds/blob/main/TeamCode/lib/OpModeAnnotationProcessor.jar"
    click Meep "https://github.com/blackfrogsftc6134/into_the_deep_worlds/blob/main/MeepMeepTesting/src/main/java/com/example/meepmeeptesting/MeepMeepTesting.java"
    click SettingsGradle "https://github.com/blackfrogsftc6134/into_the_deep_worlds/blob/main/settings.gradle"
    click GradleRoot "https://github.com/blackfrogsftc6134/into_the_deep_worlds/blob/main/build.gradle"
    click CommonGradle "https://github.com/blackfrogsftc6134/into_the_deep_worlds/blob/main/build.common.gradle"
    click DepsGradle "https://github.com/blackfrogsftc6134/into_the_deep_worlds/blob/main/build.dependencies.gradle"
    click GitHub "https://github.com/blackfrogsftc6134/into_the_deep_worlds/blob/main/.github/CONTRIBUTING.md"
    click Wrapper "https://github.com/blackfrogsftc6134/into_the_deep_worlds/blob/main/gradle/wrapper/gradle-wrapper.properties"
    click Scripts "https://github.com/blackfrogsftc6134/into_the_deep_worlds/tree/main/gradlew"

    %% Styles
    classDef android fill:#add8e6,stroke:#000,stroke-width:1px
    classDef user fill:#90ee90,stroke:#000,stroke-width:1px
    classDef external fill:#ffa500,stroke:#000,stroke-width:1px
    classDef hardware fill:#f0e68c,stroke:#000,stroke-width:1px
    classDef ci fill:#d3d3d3,stroke:#000,stroke-width:1px
    classDef test fill:#dcdcdc,stroke:#000,stroke-width:1px
```
