# lucmeynkens/dwaalspoor architecture

> Architecture diagram of the GitHub repository lucmeynkens/dwaalspoor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lucmeynkens/dwaalspoor
- Repository: https://github.com/lucmeynkens/dwaalspoor

## Overview

Dwaalspoor is a care-facility monitoring prototype for supporting residents with dementia who wander. Its main workflow sends sensor detections over MQTT; the core updates zone, person and time-of-day context, decides whether to follow a moving resident at night, and can publish a light command for an actuator. The tree also exposes position sensing and AI-related topic conventions, but the sampled code does not establish their full runtime behavior. Relationships below are limited to shown calls or documented topic conventions.

Main entry points: [`core/dwaalspoor_core.py`](https://github.com/lucmeynkens/dwaalspoor/blob/main/core/dwaalspoor_core.py) (Core event handler), [`communication/mqtt_manager.py`](https://github.com/lucmeynkens/dwaalspoor/blob/main/communication/mqtt_manager.py) (MQTT manager), [`communication/topics.py`](https://github.com/lucmeynkens/dwaalspoor/blob/main/communication/topics.py) (Topic conventions), [`devices/sensors/sensor.py`](https://github.com/lucmeynkens/dwaalspoor/blob/main/devices/sensors/sensor.py) (Presence sensor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and messaging"]
  node_main["Application entry<br/>[main.py]"]
  node_mqtt["MQTT manager<br/>[mqtt_manager.py]"]
  node_topics["Topic conventions<br/>[topics.py]"]
end

subgraph group_sensing["Sensor input"]
  node_sensor["Presence sensor<br/>[sensor.py]"]
  node_combisensor["Combined sensor<br/>[combisensor.py]"]
  node_sensor_sim["Sensor simulator<br/>[simulator.py]"]
end

subgraph group_domain["Resident context and decisions"]
  node_core["Core event handler<br/>[dwaalspoor_core.py]"]
  node_zone["Zone state<br/>[zone.py]"]
  node_person["Resident movement<br/>[person.py]"]
  node_context["Movement context<br/>[context.py]"]
  node_decision["Decision engine<br/>[decision_engine.py]"]
end

subgraph group_output["Actuation and integrations"]
  node_actuator["Light actuator<br/>[actuator.py]"]
  node_actuator_sim["Actuator simulator<br/>[simulator.py]"]
  node_ai_sim["AI simulator<br/>[simulator.py]"]
end

node_sensor_actor(("Sensor device"))
node_broker(("MQTT broker"))

node_sensor_actor -.->|"provides detections"| node_sensor
node_main -->|"creates and connects"| node_mqtt
node_main -->|"starts core"| node_core
node_main -->|"starts message loop"| node_mqtt
node_mqtt -->|"connects and exchanges"| node_broker
node_sensor -->|"uses presence topic"| node_topics
node_sensor -->|"publishes detection"| node_mqtt
node_combisensor -->|"uses input topics"| node_topics
node_combisensor -->|"publishes detections"| node_mqtt
node_sensor_sim -->|"simulates input"| node_sensor
node_sensor_sim -->|"connects broker"| node_mqtt
node_core -->|"subscribes and publishes"| node_mqtt
node_core -->|"uses subscription and output topics"| node_topics
node_core -->|"updates presence"| node_zone
node_core -->|"updates location"| node_person
node_core -->|"updates context"| node_context
node_context -->|"reads movement fields"| node_person
node_core -->|"requests action"| node_decision
node_decision -->|"checks movement and night"| node_context
node_core -->|"publishes light command"| node_actuator
node_actuator -->|"uses light topic"| node_topics
node_actuator -->|"subscribes to commands"| node_mqtt
node_actuator_sim -->|"starts actuator"| node_actuator
node_actuator_sim -->|"connects broker"| node_mqtt
node_ai_sim -.->|"possible AI topics"| node_topics

click node_main "https://github.com/lucmeynkens/dwaalspoor/blob/main/main.py"
click node_mqtt "https://github.com/lucmeynkens/dwaalspoor/blob/main/communication/mqtt_manager.py"
click node_topics "https://github.com/lucmeynkens/dwaalspoor/blob/main/communication/topics.py"
click node_sensor "https://github.com/lucmeynkens/dwaalspoor/blob/main/devices/sensors/sensor.py"
click node_combisensor "https://github.com/lucmeynkens/dwaalspoor/blob/main/devices/sensors/combisensor.py"
click node_sensor_sim "https://github.com/lucmeynkens/dwaalspoor/blob/main/devices/sensors/simulator.py"
click node_core "https://github.com/lucmeynkens/dwaalspoor/blob/main/core/dwaalspoor_core.py"
click node_zone "https://github.com/lucmeynkens/dwaalspoor/blob/main/models/zone.py"
click node_person "https://github.com/lucmeynkens/dwaalspoor/blob/main/models/person.py"
click node_context "https://github.com/lucmeynkens/dwaalspoor/blob/main/models/context.py"
click node_decision "https://github.com/lucmeynkens/dwaalspoor/blob/main/core/decision_engine.py"
click node_actuator "https://github.com/lucmeynkens/dwaalspoor/blob/main/devices/actuators/actuator.py"
click node_actuator_sim "https://github.com/lucmeynkens/dwaalspoor/blob/main/devices/actuators/simulator.py"
click node_ai_sim "https://github.com/lucmeynkens/dwaalspoor/blob/main/devices/ai/simulator.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_mqtt,node_topics toneBlue
class node_sensor,node_combisensor,node_sensor_sim toneAmber
class node_core,node_zone,node_person,node_context,node_decision toneMint
class node_actuator,node_actuator_sim,node_ai_sim toneRose
class node_sensor_actor,node_broker toneIndigo
```

## Components

### Runtime and messaging

- [Application entry](https://github.com/lucmeynkens/dwaalspoor/blob/main/main.py): `main.py`
- [MQTT manager](https://github.com/lucmeynkens/dwaalspoor/blob/main/communication/mqtt_manager.py): `communication/mqtt_manager.py`
- [Topic conventions](https://github.com/lucmeynkens/dwaalspoor/blob/main/communication/topics.py): `communication/topics.py`

### Sensor input

- [Presence sensor](https://github.com/lucmeynkens/dwaalspoor/blob/main/devices/sensors/sensor.py): `devices/sensors/sensor.py`
- [Combined sensor](https://github.com/lucmeynkens/dwaalspoor/blob/main/devices/sensors/combisensor.py): `devices/sensors/combisensor.py`
- [Sensor simulator](https://github.com/lucmeynkens/dwaalspoor/blob/main/devices/sensors/simulator.py): `devices/sensors/simulator.py`

### Resident context and decisions

- [Core event handler](https://github.com/lucmeynkens/dwaalspoor/blob/main/core/dwaalspoor_core.py): `core/dwaalspoor_core.py`
- [Zone state](https://github.com/lucmeynkens/dwaalspoor/blob/main/models/zone.py): `models/zone.py`
- [Resident movement](https://github.com/lucmeynkens/dwaalspoor/blob/main/models/person.py): `models/person.py`
- [Movement context](https://github.com/lucmeynkens/dwaalspoor/blob/main/models/context.py): `models/context.py`
- [Decision engine](https://github.com/lucmeynkens/dwaalspoor/blob/main/core/decision_engine.py): `core/decision_engine.py`

### Actuation and integrations

- [Light actuator](https://github.com/lucmeynkens/dwaalspoor/blob/main/devices/actuators/actuator.py): `devices/actuators/actuator.py`
- [Actuator simulator](https://github.com/lucmeynkens/dwaalspoor/blob/main/devices/actuators/simulator.py): `devices/actuators/simulator.py`
- [AI simulator](https://github.com/lucmeynkens/dwaalspoor/blob/main/devices/ai/simulator.py): `devices/ai/simulator.py`

### Other components

- **Sensor device**
- **MQTT broker**

## Connections

- Sensor device → Presence sensor: provides detections
- Application entry → MQTT manager: creates and connects (evidence: `main.py`)
- Application entry → Core event handler: starts core (evidence: `main.py`)
- Application entry → MQTT manager: starts message loop (evidence: `main.py`)
- MQTT manager → MQTT broker: connects and exchanges (evidence: `communication/mqtt_manager.py`)
- Presence sensor → Topic conventions: uses presence topic (evidence: `devices/sensors/sensor.py`)
- Presence sensor → MQTT manager: publishes detection (evidence: `devices/sensors/sensor.py`)
- Combined sensor → Topic conventions: uses input topics (evidence: `devices/sensors/combisensor.py`)
- Combined sensor → MQTT manager: publishes detections (evidence: `devices/sensors/combisensor.py`)
- Sensor simulator → Presence sensor: simulates input (evidence: `devices/sensors/simulator.py`)
- Sensor simulator → MQTT manager: connects broker (evidence: `devices/sensors/simulator.py`)
- Core event handler → MQTT manager: subscribes and publishes (evidence: `core/dwaalspoor_core.py`)
- Core event handler → Topic conventions: uses subscription and output topics (evidence: `core/dwaalspoor_core.py`)
- Core event handler → Zone state: updates presence (evidence: `core/dwaalspoor_core.py`)
- Core event handler → Resident movement: updates location (evidence: `core/dwaalspoor_core.py`)
- Core event handler → Movement context: updates context (evidence: `core/dwaalspoor_core.py`)
- Movement context → Resident movement: reads movement fields (evidence: `models/context.py`)
- Core event handler → Decision engine: requests action (evidence: `core/dwaalspoor_core.py`)
- Decision engine → Movement context: checks movement and night (evidence: `core/decision_engine.py`)
- Core event handler → Light actuator: publishes light command (evidence: `core/dwaalspoor_core.py`)
- Light actuator → Topic conventions: uses light topic (evidence: `devices/actuators/actuator.py`)
- Light actuator → MQTT manager: subscribes to commands (evidence: `devices/actuators/actuator.py`)
- Actuator simulator → Light actuator: starts actuator (evidence: `devices/actuators/simulator.py`)
- Actuator simulator → MQTT manager: connects broker (evidence: `devices/actuators/simulator.py`)
- AI simulator → Topic conventions: possible AI topics
