Technical Specifications Server

Summary

The Amber's server application exposes a web services API only. This application manages the data model of Amber, persisted in a database, and requires proper authentication and authorization.

The data model includes:

• users
• participants/patients
• projects/studies
• questionnaire forms
• interviews
• ...

Rational

The architecture of Amber aims at being scalable, thus the separation of the web services from the user interface applications. An API-oriented architecture can also allow to extend capabilities in the future, with the addition of microservices.

User Stories

Amber is an electronic data collection system. The data collection use cases are that will be supported are:

1. Assisted case report, when an interviewer reports observations, possibly by asking questions to the Participant,
2. Self-report, when the Participant reports own observations.

Reporting observation is done by filling a form. This form should:

• Capture a wide variety of data types,
• Be user friendly and efficient,
• Support question conditions and data validations,
• Can be paused and reinstated,
• Can be designed without programming skills.

The context of the form will be minimally described: purpose of the study, population profile, data collection time frame. A graphical form builder will be used to design the forms.

All operations must be auditable, i.e. authentication and authorization applies.

#	Who	What	How	Result
1
2
...

Scope

Backend components: database, server application, file store etc.

Design and Implementation Plan

The implementation will use the Node.js stack (for scalability and modularity), more specifically the Feathers one, for rapid development of realtime services API, with built-in authentication support. The Feathers ecosystem will be a source of useful extensions and inspirations.

The API server will be designed as promoted by Feathersjs (see Design patterns for modern web APIs), with a services oriented multi-layer architecture.

Domain

The domain is similar to the one of Maelstrom's as implemented in Mica:

• Participant: can be walk-in or seeded or self-registered
• Consent: ignored for now
• Study: research objectives
  • Population: partition of the Participants
    • Data Collection Event: data collection flow that applies to a Population
• CaseReport: participant data captured using a Form during a Data Collection Event. If the User is the Participant, it is a self-report. Preliminary is to identify the Participant with an ID.
• Form: questionnaire form for data capture. Data collected are stored within a CaseReport.
• Dataset: data captured (list of CaseRecords) using a Form during a Data Collection Event. Dataset instances are extracted from the CaseReport and can be exported in varous formats.
• Interview: a set of interdependent and ordered Forms. When a applied to a participant, a list of CaseReport is associated to an Interview.
• User: with roles admin (all permissions), manager (CRUD studies), interviewer (collect data), participant (own data access)

For the phase 1 of development the data model will be limited to:

• Study
  • Population: walk-in participants only, no Participant registration is required
    • Data Collection Event
• Form
• CaseReport
• Dataset
• User: with roles admin (all permissions), manager (CRUD studies), interviewer (collect data)

Sequence Diagrams

Amber Collect Initialization

The goal of the initialization phase is to:

• authenticate the user,
• get up-to-date Studies with their active Forms.

This phase requires a working connexion with the server.

Amber Collect Data Capture

Once the initialization phase is achieved, collecting data can be done offline (fallback strategy required when an autocomplete field cannot lookup an external service). The data captured are automatically stored locally. Once completed, the data are submitted to the server, with no possibility of update (?). The list of collected CaseRecords can be seen in the Amber Studio application, for data curation.

Technical Features

Scalability

The system should be able to support a lot of simultaneous connections: stateless API will allow replicating several server nodes. The database used will be MongoDB.

Authentication and Authorization

In Feathers, multiple authentication strategies can be defined:

• local
• oauth

Internationalization

Error messages can be internationalized, using i18next. Supported languages and i18n files need to be configurable.

Mailer

Some emails will need to be sent, for user management mainly (reset password etc.). Use nodemailer with a template engine (email templates needs to be configurable).

Web Services

The web services operations:

• CRUD operations on the data model
• data exports
• user management

CRUD Services

The CRUD services are inteded to be used by the Amber-Admin front end.

Path	Description
/users	Users management
/studies	Studies management
/forms	Forms management
/datasets	Datasets management
/files	File store for attachments

• Study: required field: name
  • creation: for phase 1, the default population will have an undefined participants selection rule, for walk-in participants.
  • deletion: remove associated documents (forms, permissions etc.). Datasets are not deleted (unless explicitly).
• Form: required field: name
  • creation: enabled is false
  • deletion: Datasets are not deleted (unless explicitly).
  • update:
    • status: draft (being developped, available for testing by advanced users), published (available for data collection), pause (), archived ()
    • versioning?
• Dataset: required field: formId, studyId, populationId and dceId

General note: the owner of an entity (study, form) will be user at creation time.

Data Collection Services

Path	Description
/dataset/:datasetId/records	Dataset records management
/dataset/:datasetId/variables	Dataset data dictionary management (driven by associated Form)
/dataset/:datasetId/_export?format=:format	Dataset export

Test/Demo Plan

How can the feature be tested or demonstrated. It is important to describe this in fairly great details so anyone can perform the demo or test.

Unresolved Issues

• Forms have versions.