Architecture

carp_mobile_sensing is one Dart package with four parts. Each is a folder under lib/, and each has its own section in this documentation.

Part	Folder	Answers
Domain	lib/domain/	What is a study? Protocol, triggers, tasks, measures, devices
Runtime	lib/runtime/	How is it run? Client manager, executors, task queue
Infrastructure	lib/infrastructure/	Where does it go? Data managers, persistence, notifications
Sampling packages	lib/infrastructure/sampling_packages/	Where does the data come from? Probes for sensors and devices

Sampling packages sit in a subfolder of infrastructure/ but are exported as their own library (lib/sampling_packages.dart). Most sampling packages are separate pub.dev packages.

Terms used below

Term	Meaning	Details
Study protocol	The description of a study, written in Dart: what to collect, when, and where to send it	Study protocol
Trigger	When something happens, e.g. at 08:00 every day, or right away	Triggers
Task	What to do when a trigger fires. A background task collects data silently. An app task asks the user to do something, e.g. fill in a survey	Tasks
Measure	One kind of data to collect, e.g. steps or screen events	Measures and data
Measurement	One collected value of a measure, with a timestamp	Measures and data
Probe	The code that reads one sensor or device and produces measurements	How sampling packages work
Sampling package	A set of measures with the probes that collect them	Sampling packages
Executor	The runtime object that carries out a trigger, task or probe	Executors
Data manager	Stores or uploads measurements	Data managers

The four parts

Domain

The classes that describe a study: the protocol, its triggers, tasks and measures, and the data classes. Its responsibility is to say what the study is. It does not run anything.

Runtime

The code that runs a study on the phone. You start, pause and resume studies through SmartPhoneClientManager, and executors carry out the triggers and tasks. Its responsibility is to run the study and keep the list of tasks the user has to do.

Sampling packages

The code that reads sensors and devices. Each package offers a set of measures and a probe for each one. Its responsibility is to collect the data.

Infrastructure

The services around the study. Data managers store or upload measurements, persistence saves the state so a study resumes after a restart, and notifications and background execution work with the OS. Its responsibility is everything that saves data or talks to the OS.

How the parts relate

lib/domain/ has two folders:

• core/ is the study: protocol, triggers, tasks, measures, devices, data classes.
• services/ holds the interfaces CAMS can be extended through: DataManager, NotificationManager, StudyProtocolManager and SamplingPackage. They declare what is needed. They are not part of the protocol.

The other parts fill them in:

Interface (domain/services/)	Implemented in
DataManager	Infrastructure: console, file and SQLite data managers
NotificationManager	Infrastructure: FlutterLocalNotificationManager
StudyProtocolManager	Infrastructure: FileStudyProtocolManager
SamplingPackage	Sampling packages: device, sensors, and your own

Replace an implementation to change how CAMS stores data or notifies. Register a new SamplingPackage to add measures.

This is not a strict layering. The interfaces refer to runtime classes (NotificationManager takes a UserTask, SamplingPackage returns a Probe and a DeviceManager), and the runtime uses the domain classes. They are folders of one package.

Outside the package

Outside	Role
carp_core	Shared domain classes, used by the domain part
Flutter plugins	Access to sensors and the OS, called from probes
CAWS or your server	Optional. Deploys studies and receives data, through a data manager