# robocup-junior/soccer-referee-app architecture

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

- Interactive diagram: https://gitdiagram.com/robocup-junior/soccer-referee-app
- Repository: https://github.com/robocup-junior/soccer-referee-app

## Overview

##### Project type and purpose
- This is a cross-platform mobile application (built with Flutter/Dart) named “RCJ Soccer RefMate.”
- Purpose: Assist referees in RoboCup Junior Soccer matches by providing match timing, score/team management, robot control via BLE, optional MQTT integration, and match preloading from a web service.

##### File structure
- Top-level directories:
- android/ — native Android project (Gradle-based, MainActivity.kt)
- ios/ — native iOS project (Xcode workspace, AppDelegate.swift)
- lib/ — Dart code:
– models/ — game, team, module data classes
– screens/ — UI pages (home, match QR scanner, settings, module settings)
– services/ — BLE, MQTT, match_data logic
– main.dart — Flutter entry point
- docs/ — MkDocs documentation
- test/ — widget tests
- Configuration/build: pubspec.yaml, analysis_options.yaml, android/gradle, ios/Flutter configs.

##### Key points from README
- Features: match flow automation, penalty/score management, BLE pairing (via scan and QR), up to 10 modules, optional MQTT publishing, tournament match preloading.
- Interaction patterns: double-tap, long-press, single-tap gestures; global settings.
- External dependencies: BLE hardware modules, MQTT broker, web API for match info.

##### Main components & their relationships
a. Mobile App Container
- Flutter UI Layer (screens & widgets)
- Business Logic Layer (match state machine in services/match_data.dart)
- Data Models (game.dart, module.dart, team.dart)
- Service Layer
– BLE Service: scan/connect to robot modules, send control commands, receive status
– MQTT Service: publish live match data to broker (optional)
– Web API Client: fetch match preloading data
- Platform Integration
– Flutter Engine & Dart VM
– Platform Channels bridging to Android/iOS Bluetooth stacks
b. Native Platform Modules
- Android (Kotlin) and iOS (Swift) wrappers for Flutter, BLE permissions, lifecycle
c. External Systems
- Robot Modules (BLE devices showing state on OLED)
- MQTT Broker (for real-time dashboards, live streams)
- Tournament Web Service (match info endpoint)

Data flows:
- UI triggers business logic → updates models → service layer actions
- BLE Service ↔ Robot Modules
- MQTT Service → MQTT Broker
- Web API Client ↔ Tournament Web Service

##### Architectural patterns & design principles
- Layered architecture: UI → Logic → Services → External
- MVVM-like separation: screens observe model state managed by match_data service
- Dependency injection (via constructor parameters or Flutter InheritedWidget/Provider)
- Single source of truth for match state in match_data service
- Platform abstraction: Flutter plugins for BLE and HTTP/MQTT

- UI Layer (screens)
- Business Logic & Models
- Service Layer (BLE, MQTT, HTTP)
- Flutter Engine / Platform Channel interfaces
b. Outside the device boundary, place:
- Robot Modules (BLE devices)
- MQTT Broker
- Tournament Web API Server
- UI → Logic → Services
- BLE Service ↔ Robot Modules
- MQTT Service → MQTT Broker
- HTTP Client ↔ Web API
- Green for business logic & data models
- Orange for services
- Gray for external systems

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Mobile Device Boundary
    subgraph "Mobile Device"
        direction TB

        %% Flutter Entry Point
        Main["main.dart\n(Entry Point)"]:::platform

        %% UI Layer
        subgraph "UI Layer" 
            direction TB
            Home["Home Screen"]:::ui
            QRScanner["Match QR Scanner"]:::ui
            ModuleSettings["Module Settings"]:::ui
            Settings["Settings Screen"]:::ui
        end

        %% Business Logic & Models
        subgraph "Business Logic & Data Models"
            direction TB
            MatchData["match_data Service\n(Match State Machine)"]:::logic
            GameModel["Game Model"]:::logic
            ModuleModel["Module Model"]:::logic
            TeamModel["Team Model"]:::logic
        end

        %% Service Layer
        subgraph "Service Layer"
            direction TB
            BLE["BLE Service"]:::service
            MQTT["MQTT Service"]:::service
        end

        %% Platform & Native
        subgraph "Flutter & Native Layers"
            direction TB
            FlutterEngine["Flutter Engine\n& Dart VM"]:::platform
            AndroidNative["Android MainActivity"]:::native
            iOSNative["iOS AppDelegate"]:::native
        end
    end

    %% External Systems
    RobotModules["Robot Modules\n(BLE Devices)"]:::external
    MQTTBroker["MQTT Broker"]:::external
    WebAPI["Tournament Web API Server"]:::external

    %% Connections within Mobile Device
    Main -->|"loads"| Home
    Main -->|"loads"| QRScanner
    Main -->|"loads"| ModuleSettings
    Main -->|"loads"| Settings

    Home -->|"interacts"| MatchData
    QRScanner -->|"interacts"| MatchData
    ModuleSettings -->|"interacts"| MatchData
    Settings -->|"accesses"| MatchData

    MatchData -->|"uses Models"| GameModel
    MatchData -->|"uses Models"| ModuleModel
    MatchData -->|"uses Models"| TeamModel

    MatchData -->|"calls"| BLE
    BLE <-->|"BLE Data"| RobotModules

    MatchData -->|"publishes"| MQTT
    MQTT -->|"forwards"| MQTTBroker

    MatchData -->|"fetches"| WebAPI
    WebAPI -->|"responds"| MatchData

    %% Platform channel integration
    Home -->|"renders via"| FlutterEngine
    MatchData -->|"platform calls"| FlutterEngine
    FlutterEngine -->|"invokes"| AndroidNative
    FlutterEngine -->|"invokes"| iOSNative

    %% Click Events
    click Main "https://github.com/robocup-junior/soccer-referee-app/blob/main/lib/main.dart"
    click Home "https://github.com/robocup-junior/soccer-referee-app/blob/main/lib/screens/home.dart"
    click QRScanner "https://github.com/robocup-junior/soccer-referee-app/blob/main/lib/screens/mac_qr_scanner.dart"
    click ModuleSettings "https://github.com/robocup-junior/soccer-referee-app/blob/main/lib/screens/module_settings.dart"
    click Settings "https://github.com/robocup-junior/soccer-referee-app/blob/main/lib/screens/settings.dart"
    click MatchData "https://github.com/robocup-junior/soccer-referee-app/blob/main/lib/services/match_data.dart"
    click GameModel "https://github.com/robocup-junior/soccer-referee-app/blob/main/lib/models/game.dart"
    click ModuleModel "https://github.com/robocup-junior/soccer-referee-app/blob/main/lib/models/module.dart"
    click TeamModel "https://github.com/robocup-junior/soccer-referee-app/blob/main/lib/models/team.dart"
    click BLE "https://github.com/robocup-junior/soccer-referee-app/blob/main/lib/services/ble.dart"
    click MQTT "https://github.com/robocup-junior/soccer-referee-app/blob/main/lib/services/mqtt.dart"
    click AndroidNative "https://github.com/robocup-junior/soccer-referee-app/blob/main/android/app/src/main/kotlin/com/robocup/rcj_scoreboard/MainActivity.kt"
    click iOSNative "https://github.com/robocup-junior/soccer-referee-app/blob/main/ios/Runner/AppDelegate.swift"
    click RobotModules "https://github.com/robocup-junior/soccer-referee-app/tree/main/web/icons"
    click MQTTBroker "https://github.com/robocup-junior/soccer-referee-app/blob/main/web/manifest.json"
    click WebAPI "https://github.com/robocup-junior/soccer-referee-app/blob/main/web/index.html"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef logic fill:#D0FFD6,stroke:#333,stroke-width:1px
    classDef service fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef platform fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef native fill:#F0E0F0,stroke:#333,stroke-width:1px
    classDef external fill:#E8E8E8,stroke:#333,stroke-width:1px
```
