How robocup-junior/soccer-referee-app works
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