# Project Review

## Purpose

The virtual health assistant is built as an event-driven desktop system that converts binary health predictions into a continuously updated risk visualization.

Primary goals:

1. receive predictions in near real time via MQTT,
2. persist events locally,
3. compute rolling risk levels,
4. provide immediate visual feedback in the UI,
5. export machine-readable state for external avatar integration.

## End-to-End Pipeline

1. `MqttClientService` subscribes to the configured topic.
2. Payloads are forwarded to `BinaryEventService`.
3. Payloads are validated (`valid`, `_id`, `prediction`).
4. Accepted predictions are stored by `DataPersistenceService`.
5. `StatisticsService` computes the current ratio from the latest 20 entries.
6. `EvaluationService` maps ratio to `ProblemLevel`.
7. `AppState` notifies UI controllers and views.
8. `AnimationFileService` writes `animation.json`.

## Functional Scope

- Desktop monitoring UI with two views (stream + dashboard)
- MQTT-driven event ingestion
- SQLite event persistence
- Rolling ratio analytics
- Level classification (`NONE`, `WARNING`, `HIGH`, `DISASTER`)
- Optional external process orchestration (simulator + Unreal launcher)
- Startup configuration validation and structured logging

## Design Highlights

- **Separation of concerns**  
  Startup/shutdown orchestration lives in `bootstrap`; business logic in `service`; view orchestration in `controller`.
- **Config-first runtime behavior**  
  MQTT, simulator, Unreal, and animation output are controlled via properties.
- **Fail-fast startup validation**  
  `AppConfigValidator` blocks startup when enabled integrations are misconfigured.
- **Testability by construction**  
  Multiple services support dependency injection in tests (for example process launchers and MQTT client instances).

## Quality and Verification

Automated tests cover:

- App state transitions and listener notifications
- Payload validation and duplicate-id handling
- Ratio and threshold evaluation behavior
- SQLite persistence integration behavior
- MQTT subscribe/publish/callback flow
- Process startup/shutdown command sequencing and startup report behavior
- Animation file mapping and overwrite behavior

See [Testing](TESTING.md) for details and command examples.

## Current Limitations

- Runtime database is deleted on shutdown (`ApplicationShutdownManager`), so historical data is not retained.
- Default Unreal-related paths are machine-specific and must be adapted for new environments.
- UI behavior is not covered by end-to-end GUI tests.
- Duplicate payload protection is based on the last seen `_id` only (consecutive duplicates).

## Improvement Roadmap

1. Make database cleanup optional through configuration.
2. Add profile-based configuration (local/dev/demo) to reduce machine-specific defaults.
3. Add UI-level automated checks (or contract tests around controller/view boundaries).
4. Improve duplicate handling (e.g., bounded cache of recent IDs).
5. Add metrics/telemetry for startup health and message throughput.