165 lines
4.5 KiB
Markdown
165 lines
4.5 KiB
Markdown
# Virtueller Gesundheitsassistent
|
|
|
|
A Java 17 desktop application that ingests binary health predictions over MQTT, stores them in SQLite, computes rolling risk levels, and visualizes the result in a dashboard with optional avatar/Unreal integration.
|
|
|
|
## Contents
|
|
|
|
- [Features](#features)
|
|
- [Architecture Overview](#architecture-overview)
|
|
- [Tech Stack](#tech-stack)
|
|
- [Getting Started](#getting-started)
|
|
- [Configuration](#configuration)
|
|
- [Testing](#testing)
|
|
- [Project Structure](#project-structure)
|
|
- [Documentation](#documentation)
|
|
- [Known Limitations](#known-limitations)
|
|
|
|
## Features
|
|
|
|
- Swing desktop UI with:
|
|
- `Avatar Streaming` tab (embedded JCEF browser)
|
|
- `Dashboard` tab (risk time-series chart + level bar)
|
|
- MQTT subscription to prediction events (`PREDICTION` by default)
|
|
- SQLite persistence (`data/health.db`)
|
|
- Threshold-based risk classification from the latest 20 values:
|
|
- `NONE` for ratio `< 0.5`
|
|
- `WARNING` for ratio `>= 0.5`
|
|
- `HIGH` for ratio `>= 0.8`
|
|
- `DISASTER` for ratio `>= 0.9`
|
|
- Animation state JSON export (`animation.output.path`)
|
|
- Optional startup/shutdown management for:
|
|
- Python MQTT simulator
|
|
- Unreal/Pixel Streaming startup script
|
|
- Asynchronous logger with optional file output and rotation
|
|
|
|
## Architecture Overview
|
|
|
|
Runtime flow:
|
|
|
|
1. The app initializes UI and services.
|
|
2. MQTT messages are received on a configured topic.
|
|
3. Incoming JSON payloads are validated.
|
|
4. Accepted predictions are persisted in SQLite.
|
|
5. Risk ratio and level are re-evaluated.
|
|
6. App state notifies UI controllers.
|
|
7. Dashboard widgets and chart update.
|
|
8. Animation JSON is written for external consumers.
|
|
|
|
## Tech Stack
|
|
|
|
- Java 17
|
|
- Maven
|
|
- Swing + FlatLaf + JFreeChart
|
|
- Eclipse Paho MQTT client
|
|
- SQLite JDBC
|
|
- JCEF (`jcefmaven`)
|
|
- JUnit 5 + Mockito
|
|
|
|
## Getting Started
|
|
|
|
### Prerequisites
|
|
|
|
- JDK 17
|
|
- Maven 3.9+
|
|
- MQTT broker running at `localhost:1883` (or adjust config)
|
|
- Windows for bundled PowerShell/BAT integration scripts
|
|
- Optional: Python for simulator support
|
|
- Optional: Unreal/Pixel Streaming environment
|
|
|
|
### 1) Configure a minimal local run
|
|
|
|
In `src/main/resources/config/application.properties`, disable optional external integrations if they are not available on your machine:
|
|
|
|
```properties
|
|
mqtt_sim.enabled=false
|
|
unreal.enabled=false
|
|
```
|
|
|
|
### 2) Build and run
|
|
|
|
```powershell
|
|
mvn clean compile
|
|
mvn org.codehaus.mojo:exec-maven-plugin:3.5.0:java -Dexec.mainClass=vassistent.App
|
|
```
|
|
|
|
You can also run `vassistent.App` directly from an IDE.
|
|
|
|
### 3) Send test data
|
|
|
|
Publish to topic `PREDICTION` with payload format:
|
|
|
|
```json
|
|
{
|
|
"valid": true,
|
|
"_id": 1,
|
|
"prediction": 0
|
|
}
|
|
```
|
|
|
|
Validation rules:
|
|
|
|
- `valid` must be `true`
|
|
- `_id` must exist
|
|
- `prediction` must be `0` or `1`
|
|
|
|
## Configuration
|
|
|
|
Main config: `src/main/resources/config/application.properties`
|
|
Logger config: `src/main/resources/config/logger.properties`
|
|
|
|
High-impact keys:
|
|
|
|
- `mqtt.broker.url`, `mqtt.client.id`, `mqtt.topic`
|
|
- `streaming.url`
|
|
- `animation.output.path`
|
|
- `mqtt_sim.enabled`, `python.path`, `mqtt_sim.script`
|
|
- `unreal.enabled`, `unreal.executable`, `unreal.signalling_server.script`
|
|
|
|
A full key-by-key reference is available in [`docs/CONFIGURATION.md`](docs/CONFIGURATION.md).
|
|
|
|
## Testing
|
|
|
|
Run tests with:
|
|
|
|
```powershell
|
|
mvn test
|
|
```
|
|
|
|
The suite includes unit and integration tests for state changes, payload validation, threshold evaluation, persistence behavior, process management, MQTT behavior, and animation output.
|
|
|
|
## Project Structure
|
|
|
|
```text
|
|
src/main/java/vassistent
|
|
App.java
|
|
bootstrap/ # startup wiring + shutdown sequencing
|
|
controller/ # UI orchestration
|
|
model/ # app state + value objects
|
|
service/ # MQTT, DB, stats, evaluation, processes
|
|
ui/ # Swing views/components
|
|
util/ # config loading/validation + logging
|
|
|
|
src/main/resources
|
|
config/application.properties
|
|
config/logger.properties
|
|
scripts/mqtt_simulator.py
|
|
scripts/start_avatar.ps1
|
|
```
|
|
|
|
## Documentation
|
|
|
|
- [Documentation Index](docs/INDEX.md)
|
|
- [Project Review](docs/PROJECT_REVIEW.md)
|
|
- [Architecture](docs/ARCHITECTURE.md)
|
|
- [Setup and Run](docs/SETUP_AND_RUN.md)
|
|
- [Configuration](docs/CONFIGURATION.md)
|
|
- [Testing](docs/TESTING.md)
|
|
- [Source Map](docs/SOURCE_MAP.md)
|
|
- [Known Issues](docs/KNOWN_ISSUES.md)
|
|
|
|
## Known Limitations
|
|
|
|
- The runtime database (`data/health.db`) is currently deleted on application shutdown.
|
|
- Default Unreal-related paths in `application.properties` are machine-specific and require adaptation on other systems.
|
|
- Enabling optional external integrations without valid local paths causes startup validation to fail.
|