Software Architecture

This tutotial describes the overall software architecture of ResearchPackage and its API, and how to get started.

API and Architecture

API Naming

We are following the pattern from Apple’s Research Kit’s when it comes to naming. ResearchKit uses the prefix ORK (Open Research Kit) before the names of classes, types etc. Following this naming model, the class names in ResearchPackage starts a RP prefix. UI widgets uses the RPUI (Research Package UI) prefix.

Note that objects starting with RP are part of the Model (e.g. RPConsentDocument) while those which start with RPUI are part of the UI library (e.g. RPUIVisualConsentStep).

Main Domain Model

Overall, ResearchPackage uses a Task to represent the survey containing a list of Steps, which each returns a Result. In the API, the task is an RPOrderedTask object and the steps are RPQuestionStep objects. Results are saved as RPTaskResult objects.

Below is an example of a hierarchy with a task, three steps, each with a specific answer type.

BLoC Architecture

ResearchPackage follows the BLoC architecture, which is recommended by the Flutter Team. In ResearchPackage, the BlocTask is holding the StreamControllers needed for the communication.

Following the BLoC architecture, ResearchPackage uses streams and callbacks for internal communication (e.g. between Task and Steps). There is a BLoC class responsible for the communication between the task and the steps it’s containing (BlocTask). Communication between the question container and their question body is made possible via callback functions.

Style and UI Theme

Research Package is accessing the parent application’s style through Flutter’s context feature. This means that the given Theme of the application is shared also with Research Package and appears in its styling (colors, font styles…). As an example, the example application shows how the theme colors of the parent application are modified, and this is refelcted in the ResearchPackage screens.

See this article by the Flutter team on how to Theme your application.

How to set up a ResearchPackage project

Research Package is published to pub.dev and all you have to do is to add its dependency to your pubspec.yaml file.

  dependencies:
     research_package: ^{latest_version}

After you run the flutter packages get command, you are able to import and start using ResearchPackage. You can import the whole package including the Model and UI libraries:

import 'package:research_package/research_package.dart';

Or you can decide which library of the package you want to use:

import 'package:research_package/model.dart';
import 'package:research_package/ui.dart';

Limitations

Research Package currently supports only a few answer formats which can be put on separate pages or combined in one page (using a FormStep). Nonetheless, we are constantly working on the package so these features, as well as more type of questions will be implemeted in the future.