75 lines
3.0 KiB
Markdown
75 lines
3.0 KiB
Markdown
# 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.
|