# 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.