diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
new file mode 100644
index 0000000..5858d62
--- /dev/null
+++ b/docs/ARCHITECTURE.md
@@ -0,0 +1,62 @@
+# 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
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
new file mode 100644
index 0000000..39fbf16
--- /dev/null
+++ b/docs/CONFIGURATION.md
@@ -0,0 +1,35 @@
+# Configuration
+
+Application settings are loaded from classpath properties files in `src/main/resources/config`.
+
+## `application.properties`
+
+| Key | Purpose | Current Default |
+|---|---|---|
+| `app.mode` | Generic mode flag | `test` |
+| `python.path` | Python interpreter for simulator process | `C:\\Program Files\\PyManager\\python.exe` |
+| `mqtt.topic` | MQTT topic to subscribe to | `PREDICTION` |
+| `mqtt_sim.enabled` | Enables simulator startup | `false` |
+| `mqtt_sim.script` | Simulator script path | `src/main/resources/scripts/mqtt_simulator.py` |
+| `unreal.enabled` | Enables Unreal startup flow | `true` |
+| `unreal.executable` | PowerShell script to start Unreal process | absolute path |
+| `unreal.signalling_server.script` | Signalling server BAT file path | absolute path |
+
+Notes:
+
+- MQTT broker host/port are currently hardcoded in Java (`MqttClientService`): `tcp://localhost:1883`.
+- Several Unreal-related paths are absolute and environment-specific.
+
+## `logger.properties`
+
+| Key | Purpose | Current Default |
+|---|---|---|
+| `logger.level` | Minimum log level | `DEBUG` |
+| `logger.file.enabled` | Enables file logging | `true` |
+| `logger.file` | Log output file | `logs/application.log` |
+| `logger.max.size.mb` | Rotation threshold | `10` |
+
+## Related Script Files
+
+- `src/main/resources/scripts/mqtt_simulator.py`
+- `src/main/resources/scripts/start_avatar.ps1`
diff --git a/docs/INDEX.md b/docs/INDEX.md
new file mode 100644
index 0000000..5f827d7
--- /dev/null
+++ b/docs/INDEX.md
@@ -0,0 +1,20 @@
+# Documentation Index
+
+This folder contains project-level documentation for the virtual health assistant.
+
+## Contents
+
+- [Architecture](ARCHITECTURE.md)
+- [Setup and Run](SETUP_AND_RUN.md)
+- [Configuration](CONFIGURATION.md)
+- [Source Map](SOURCE_MAP.md)
+- [Testing](TESTING.md)
+- [Known Issues](KNOWN_ISSUES.md)
+
+## Recommended Reading Order
+
+1. [Architecture](ARCHITECTURE.md)
+2. [Setup and Run](SETUP_AND_RUN.md)
+3. [Configuration](CONFIGURATION.md)
+4. [Testing](TESTING.md)
+5. [Known Issues](KNOWN_ISSUES.md)
diff --git a/docs/KNOWN_ISSUES.md b/docs/KNOWN_ISSUES.md
new file mode 100644
index 0000000..3c8e4d9
--- /dev/null
+++ b/docs/KNOWN_ISSUES.md
@@ -0,0 +1,45 @@
+# Known Issues
+
+## 1. Hardcoded Environment Paths
+
+Several runtime paths are absolute and machine-specific:
+
+- animation output file path in `AnimationFileService`
+- Unreal process script paths in `application.properties`
+- PID file cleanup paths in `ProcessManagerService`
+
+Impact:
+
+- project is not portable across machines without local path edits
+
+## 2. Database Deleted on Shutdown
+
+`App.deleteDatabase()` deletes `data/health.db` on app exit.
+
+Impact:
+
+- historical data is lost every run unless behavior is changed
+
+## 3. Signalling Process Startup Incomplete
+
+In `ProcessManagerService.startSignallingServer()`, process creation is currently prepared but not started (`pb.start()` is commented).
+
+Impact:
+
+- log output may indicate startup intent, but process is not actually launched via that path
+
+## 4. Legacy Mockito Dependency
+
+Mockito-based tests fail on Java 17 due to old `mockito-all:2.0.2-beta`.
+
+Impact:
+
+- full CI-style green test run is blocked until dependency modernization
+
+## 5. Encoding Artifacts in Logs/Strings
+
+Some source/log text contains mojibake characters in comments/messages.
+
+Impact:
+
+- readability and consistency issues in logs and source text
diff --git a/docs/SETUP_AND_RUN.md b/docs/SETUP_AND_RUN.md
new file mode 100644
index 0000000..3001a97
--- /dev/null
+++ b/docs/SETUP_AND_RUN.md
@@ -0,0 +1,58 @@
+# Setup and Run
+
+## Prerequisites
+
+- Java 17 (JDK)
+- Maven 3.9+
+- MQTT broker reachable at `localhost:1883`
+- Windows environment for bundled PowerShell/BAT process scripts
+
+Optional:
+
+- Python (for MQTT simulator startup)
+- Unreal + Pixel Streaming environment (if enabled in config)
+
+## Build
+
+```powershell
+mvn clean compile
+```
+
+## Run (CLI)
+
+```powershell
+mvn org.codehaus.mojo:exec-maven-plugin:3.5.0:java -Dexec.mainClass=vassistent.App
+```
+
+## Run (IDE)
+
+Run the class:
+
+- `vassistent.App`
+
+## MQTT Payload Format
+
+Publish payloads to configured topic (default `PREDICTION`) in this format:
+
+```json
+{
+  "valid": true,
+  "_id": 1,
+  "prediction": 0
+}
+```
+
+Rules:
+
+- `valid` must be `true`
+- `_id` must exist
+- `prediction` must be `0` or `1`
+
+## Shutdown Behavior
+
+On shutdown, the app:
+
+- disconnects MQTT
+- stops managed external processes
+- flushes logger queue
+- deletes `data/health.db` (current implementation)
diff --git a/docs/SOURCE_MAP.md b/docs/SOURCE_MAP.md
new file mode 100644
index 0000000..11db99e
--- /dev/null
+++ b/docs/SOURCE_MAP.md
@@ -0,0 +1,59 @@
+# Source Map
+
+Package-level map of all Java source files in `src/main/java` and tests in `src/test/java`.
+
+## Main Sources
+
+### `vassistent`
+
+- `App.java`: application entry point and shutdown hook logic
+
+### `vassistent.bootstrap`
+
+- `ApplicationContext.java`: container for shared services/state
+- `ApplicationInitializer.java`: wiring and startup sequence
+- `ApplicationShutdownManager.java`: managed shutdown sequence
+
+### `vassistent.controller`
+
+- `AppWindowController.java`: main window lifecycle and state-driven UI updates
+- `DashboardController.java`: chart and level updates on state changes
+- `StreamingController.java`: stream view actions (reload/focus)
+
+### `vassistent.model`
+
+- `AppState.java`: observable app state
+- `DatabaseEntry.java`: persisted event value + timestamp
+- `ProblemLevel.java`: risk level enum
+- `RatioPoint.java`: chart point model
+
+### `vassistent.service`
+
+- `AnimationFileService.java`: writes animation state JSON file
+- `BinaryEventService.java`: payload validation + dispatch
+- `DataPersistenceService.java`: SQLite init and CRUD-like methods
+- `EvaluationService.java`: ratio-to-problem-level mapping
+- `MqttClientService.java`: MQTT connectivity and callbacks
+- `ProcessManagerService.java`: optional process startup/shutdown
+- `StatisticsService.java`: ratio and rolling-avg computations
+
+### `vassistent.ui`
+
+- `AppWindow.java`: root frame with tabbed layout
+- `DashboardView.java`: chart + threshold markers + level display
+- `PixelStreamingView.java`: JCEF browser panel for stream
+- `ProblemLevelBar.java`: custom level visualization widget
+
+### `vassistent.util`
+
+- `ConfigLoader.java`: classpath properties loader
+- `Logger.java`: async logger with file rotation
+
+## Test Sources
+
+### `vassistent.service`
+
+- `BinaryEventServiceTest.java`
+- `DataPersistenceServiceTest.java`
+- `EvaluationServiceTest.java`
+- `StatisticsServiceTest.java`
diff --git a/docs/TESTING.md b/docs/TESTING.md
new file mode 100644
index 0000000..4712ca9
--- /dev/null
+++ b/docs/TESTING.md
@@ -0,0 +1,39 @@
+# Testing
+
+## Run Tests
+
+```powershell
+mvn test
+```
+
+## Current Test Suite
+
+Located in `src/test/java/vassistent/service`:
+
+- `BinaryEventServiceTest`
+- `DataPersistenceServiceTest`
+- `EvaluationServiceTest`
+- `StatisticsServiceTest`
+
+## Current Status (Java 17)
+
+The suite does not fully pass on Java 17 because of legacy Mockito dependency:
+
+- project uses `mockito-all:2.0.2-beta`
+- this version relies on CGLIB behavior that conflicts with modern Java module access
+- result: Mockito-based tests fail at initialization (`InaccessibleObjectException`)
+
+Tests not depending on Mockito are expected to run successfully.
+
+## Recommended Fix
+
+Replace legacy dependency with modern Mockito stack, for example:
+
+- `org.mockito:mockito-core` (or `mockito-junit-jupiter`)
+- ensure JUnit Jupiter engine is configured by Surefire
+
+After dependency update, rerun:
+
+```powershell
+mvn test
+```
diff --git a/readme.md b/readme.md
index 1194368..d6abfe4 100644
--- a/readme.md
+++ b/readme.md
@@ -2,6 +2,16 @@
 
 Java desktop application that receives binary health predictions via MQTT, stores them in SQLite, computes rolling risk ratios, and visualizes the result in a dashboard with an avatar streaming view.
 
+## Documentation
+
+- [Docs Index](docs/INDEX.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [Setup and Run](docs/SETUP_AND_RUN.md)
+- [Configuration](docs/CONFIGURATION.md)
+- [Source Map](docs/SOURCE_MAP.md)
+- [Testing](docs/TESTING.md)
+- [Known Issues](docs/KNOWN_ISSUES.md)
+
 ## Features
 
 - Swing desktop UI with two tabs: