Fahrsimulator_MSY2526_UX/docs/ARCHITECTURE.md

Architecture

System Overview

The application is a state-driven desktop client with an event-processing pipeline:

1. ingest prediction events from MQTT,
2. persist accepted values in SQLite,
3. evaluate risk based on recent history,
4. update UI state and rendering,
5. export animation state for external consumers.

Module Structure

• vassistent.bootstrap
  Application startup/shutdown orchestration (ApplicationInitializer, ApplicationShutdownManager)
• vassistent.service
  Runtime services and integrations (MQTT, persistence, statistics, evaluation, process management)
• vassistent.model
  Core state/data objects (AppState, ProblemLevel, DatabaseEntry, RatioPoint)
• vassistent.controller
  Connects app state/services with Swing views
• vassistent.ui
  Window and visual components
• vassistent.util
  Configuration loading/validation and logging

Runtime Flow

Startup sequence

1. App.main initializes look-and-feel.
2. ApplicationInitializer.initialize() validates config and wires all services.
3. MQTT subscription is registered on configured topic.
4. Optional external processes are started via ProcessManagerService.
5. UI window/controller is created on the Swing event thread.
6. JVM shutdown hook is registered through ApplicationShutdownManager.

Event processing sequence

1. MQTT message arrives (MqttClientService.messageArrived).
2. Payload is routed to BinaryEventService.handlePayload.
3. Payload validation checks:
   • valid == true
   • _id is present
   • prediction is 0 or 1
   • duplicate _id vs last processed message is rejected
4. Accepted value is stored by DataPersistenceService.
5. EvaluationService requests ratio from StatisticsService.getRatio(20).
6. Ratio is mapped to a ProblemLevel.
7. AppState updates notify registered listeners.
8. AnimationFileService writes the corresponding animation JSON file.

Core Domain Rules

EvaluationService maps ratios to levels:

• < 0.5 -> NONE
• >= 0.5 -> WARNING
• >= 0.8 -> HIGH
• >= 0.9 -> DISASTER

Persistence schema (binary_event):

• id (autoincrement primary key)
• value (0/1)
• timestamp (ISO local date-time string)

Integration Boundaries

• MQTT: Eclipse Paho client, broker URL and topic from config.
• Database: local SQLite file (data/health.db by default).
• UI streaming tab: JCEF browser for a configured URL (streaming.url).
• External processes: optional Python simulator and Unreal launcher script.
• Animation output: JSON file written to animation.output.path.

Shutdown Behavior

ApplicationShutdownManager performs:

1. MQTT disconnect,
2. managed process shutdown,
3. runtime database file deletion (data/health.db),
4. logger shutdown.

Architectural Tradeoffs

• Pros
  • Clear service boundaries and explicit startup wiring.
  • Good testability for service layer and integration logic.
  • Configuration validation catches many misconfigurations early.
• Current tradeoffs
  • Local database lifecycle is ephemeral by default (deleted on shutdown).
  • Startup is tightly coupled to external-process configuration when enabled.
  • UI logic is mostly verified indirectly through state and service tests.