To manage the complexity of this study, the codebase follows a microservice architecture, where each independent service is responsible for a specialised task. Services are stateless and only execute commands received from a central authority. This central authority follows an event-driven architecture enabled through state machines.

This modular architecture was chosen for better fault management and scalability. With this clear separation of concerns, the state machine defines "what to do", while the services handle "how to do it".

Services

General Principles

• Stateless & Reactive: Services do not contain decision-making logic.
• Simple Command Execution:
  • Commands received → Immediate execution → Publish status updates.
• Event-Driven Communication:
  • Services communicate only when needed to complete a task.

Database

The database service manages two databases:

1. Persistent Database

Stores service state data for system continuity.

id	service_name	state_name	state_value

2. Study Database

Stores research-related data for later analysis.

Study meta

Tracks study-wide metrics.

id	number_of_interactions_in_a_day	number_of_robot_crashes	number_of_network_failures	number_of_network_failures	reminder_message

Check-In meta database

Stores metadata related to check-in sessions.

id	checkin_time	checkin_duration

Check-In database

Stores responses for each time the participant checks in

id	question	response

Peripherals

Manages external devices connected to the system:

• WiFi Router: Monitors connection status and internet speed.
• LCD Touchscreen: Turns off the backlight after 10 seconds of inactivity.

Reminder

This service handles time-triggered reminders to encourage users to perform their chosen behaviour. The reminder only triggers if:

• No other behaviour is currently running.
• The reminder is overdue.

Robot control

This service interfaces with the Anki Vector SDK and provides high-level robot functions:

• Text-to-Speech
• Movement: Drive off/on the charger.
• Animations: Happy, sad, greeting, backchanneling, celebration.

#### Connection Management

• Checks robot connection periodically.
• Attempts automatic reconnection if disconnected.
• If reconnection fails, an error is raised.

Speech recognition

This service processes speech into text using Google Cloud Speech-to-Text.

Response Handling

1. Waits up to 15 seconds for the participant to start speaking.
2. Records speech until 3 seconds of silence is detected.
3. Classifies responses:
   • Closed-ended questions: Detects numbers (e.g., Likert scale) or "yes/no" responses.
   • Open-ended questions: Captures full responses.

State management

The state machine uses a hybrid architecture consisting of:

• Reactive Layer → Handles real-time reactions (subsumption architecture).
• Deliberate Layer → Handles structured decisions using:
  • Finite State Machine (FSM)
  • Behaviour Tree (BT)

Execution Flow

1. The reactive layer detects critical conditions that influence the FSM.
2. FSM determines the overall state.
3. Behaviour Tree executes structured sequences.

Implementation Details

• Event-driven & non-blocking.
• Complex behaviours that are managed by the BT have an orchestrator that clearly defines the sequence of events to complete the behaviour.
• Behaviour Branches define which services are active.
• Services are torn down before initialising for a new behaviour branch.

This structured approach ensures scalability, manageability, and fault management.

User interface

The UI is a Flask-based web app designed to simulate a touch interface. It consists of four pages:

1. Home
2. Check-in
3. History
4. Settings

Communication

• WebSockets: Handles real-time updates from the backend.
• AJAX: Handles user click events. This ensures a responsive UI that updates based on both user interactions and backend events.

## Share libraries

The shared_libraries module contains reusable components:

• MQTT Config: This is the parent class that defines shared messaging functions
• event_dispacher: This is used for communication between Python scripts in a service, where messages dispatched are processed sequentially
• custom_logging.py: While the application is running it continuously updates the log file in each service. This is useful for later debugging if the user mentions there was an issue with the system during deployment.

Configuration

Stores environmental values and participant-specific settings.

Environment Variables (.env file)

• API Keys
• Hardware & Software configurations.

User-Specific Configuration

• initial_configurations.py stores user-specific personalised settings.

Errors and warnings

The only critical error that triggers a dialogue box is a robot connection failure.

Error Handling Flow

1. The FSM enters an error state, pausing all services.
2. If possible, services cancel the current execution.
3. A dialogue box appears, instructing the participant to:
   • Check the robot's power & network.
   • Manually attempt reconnection via the UI.
4. If an error occurs during check-in, the system:
   • Pauses and waits for resolution.
   • Resumes from the last asked question upon recovery.

# Feedback During initial setup and before check-in starts, a loading indicator shows real-time system status to inform users about ongoing background processes.