Client Overview

2019 status: Current

This document describes the current state of the Android client. The codebase is located at https://github.com/projectbuendia/client. If you'd like to contribute, follow our Getting Started guide.

Package layout

app module

This module contains most of the code we've written. It contains the following packages:

• data - This package contains all the code we use for data access. The data.app subpackage contains all the code used by the application for querying and modifying database data. For more information, see Client Data Architecture.
• diagnostics - This package contains automated diagnostics that run against the application in the background. These diagnostics inform the user when something might affect the application's ability to function correctly. For more information, see Client Troubleshooter.
• events - This package contains Event Bus event objects, which are mostly POJOs, and a couple of Event Bus helper classes. For more information, see Event Bus.
• filter - This package contains filters for database queries (the db subpackage) and for filtering in-memory data (the matchers subpackage).
• inject - This package contains classes that support Dagger dependency injection.
• model - This package contains constants related to locations, concepts, etc. This package should be removed and replaced with an abstraction.
• net - This package contains classes for communicating with the server. For more information on the server API, see Buendia REST API Spec.
• prefs - This package contains classes that deal with SharedPreferences.
• sync - This package contains both our sync framework implementation and our database logic. For more information, see Client Sync.
• ui - This package contains our Activities, Fragments, and several helper classes.
• updater - This package contains classes that manage the application's auto-update mechanism.
• user - This package contains classes that manage the current active and known users.
• utils - This package contains random utility classes.
• widget - This package contains custom and composite views.

odkcollect module

The ODK Collect codebase was developed by the OpenDataKit team, and we've largely stayed away from refactoring the code.

We mostly care about the following classes:

• android/activities/FormEntryActivity.java - This class is responsible for displaying a form and saving it to disk.
• android/views/ODKView.java - This class is responsible for displaying an individual group (or individual question).
• android/widgets/* - These classes are the widgets for each type of field to be displayed--for example, DateTimeWidget allows the edit of a date and time.
• android/widgets2/* - These classes are widgets that we have built to handle special rendering or processing needed by our forms. Because they're designed a bit differently, we've put them in a separate package.

Code Quality

Overall, code quality has improved significantly since December 2014 due to a slowed pace of feature development and several concerted refactoring efforts. Some quality highlights:

• UI tests have been created for the most common user scenarios, such as creating a new patient or assigning him to a location.
• UI classes (Activities and Fragments) now have a proper MVC implementation that significantly improves testability.
• Most application data access now goes through a single asynchronous data model abstraction.
• Most asynchronous communication between application components occurs through an EventBus, which both improves testability and keeps code short.
• Dependency injection with Dagger decouples many application components and improves testability.

Some places for improvement:

• Due to rolling refactoring, lots of dead code exists throughout the application and lots of abstractions aren't fully utilized.
• Resources (such as strings or color constants) are scattered all over the place, both in XML and in code.
• Even though it's much better than before, some unnecessary work is still happening on the UI thread.

For more information, see MVC in Android Client, Client Refactoring, and Client Testing Strategy.

It's also worth noting that while we have invested a lot of effort into improving code quality in app, we have not really done so in odkcollect, nor do we plan to.

Libraries

We use a number of different libraries; of particular note are:

• Guava - A wide range of Google-developed java utilities.
• Joda-Time - A better date and time library.
• ButterKnife - A view "injection" framework that gets rid of findViewById boilerplate.
• Volley - An HTTP library.
• Event Bus - An event bus for async communication.
• Gson - JSON parser
• Iconify - Drawables from FontAwesome glyphs
• Espresso - UI testing

Build Configuration

The Android application has a customized build.gradle build script that has the following features: Provides different application IDs for dev ('org.projectbuendia.client.dev') and release ('org.projectbuendia.client').

• Generates an Android version number (e.g., '2100') from major, minor, and build version parts (e.g., '0.2.1').
• Configures several resource values differently for debug and release builds.
• Defines a script that asks a user for the signing key password when assembling a release build (see Releasing a Client Build).

Linting and Testing

Client code should be checked for style with Android Studio's built-in linter. Check the Android Studio lint documentation for more information, or the Android Style Guide for more info on the exact styles used in the project.

Various tests have been written, all of which use the Espresso test framework (even if they are not UI tests). These tests are not automatically run before submission but are instead triggered after submission using our Jenkins server.