Fahrsimulator_MSY2526_UX/docs/ARCHITECTURE.md

Architecture

High-Level Overview

The application is a Java Swing desktop client that:

1. subscribes to MQTT prediction events,
2. stores accepted events in SQLite,
3. computes risk ratios,
4. updates UI state and visualization,
5. exports animation state for Unreal integration.

Layers

• bootstrap
• builds and wires all services in ApplicationInitializer
• handles orderly shutdown in ApplicationShutdownManager
• service
• integration and business logic (MQTT, DB, stats, evaluation, external processes)
• model
• simple state and value objects (AppState, ProblemLevel, DatabaseEntry, RatioPoint)
• controller
• UI orchestration between state/services and Swing views
• ui
• window and visual components (tabs, chart, browser, status widgets)
• util
• shared helpers for config and logging

Runtime Data Flow

1. App.main initializes look-and-feel and context.
2. MqttClientService connects to tcp://localhost:1883.
3. Subscription on configured topic routes payloads into BinaryEventService.
4. BinaryEventService validates JSON and stores prediction values.
5. EvaluationService gets ratio from StatisticsService.
6. AppState is updated with the new ProblemLevel.
7. Controllers listen to AppState and refresh UI (DashboardView, status bar).
8. AnimationFileService writes the animation JSON consumed by Unreal side logic.

Main Components

• vassistent.App
• process entry point and shutdown hook registration
• ApplicationContext
• in-memory service container
• DataPersistenceService
• SQLite schema init and data access
• MqttClientService
• MQTT connect/subscribe/publish callbacks
• StatisticsService
• ratio and rolling-average computations
• EvaluationService
• ratio-to-level mapping
• ProcessManagerService
• optional startup/shutdown of simulator/Unreal helper processes

UI Structure

• Main window: AppWindow
• Tab 1: PixelStreamingView (JCEF browser)
• Tab 2: DashboardView (JFreeChart + ProblemLevelBar)
• Footer status bar: MQTT status + current level