Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Iris Msg App

This repo is the app for, an sms donation platform. It lets your sign up, create organisations, send messages and processes donations. It's a native Android app, written in Kotlin using Android Jetpack, Retrofit & Dagger

Iris Msg is developed by Open Lab at Newcastle University as an Open source project.


There are two users of this app. A coordinator manages an organisation and sends messages to it's subscribers. A donor uses their sms to forward those messages through the app.

A coordinator can also be a donor for their organisation, but can remove themselves when more donors are added.


  • Sign up in the app and verify their phone number
  • Accept app permissions to send SMS
  • Create an organisation and add subscribers
  • Invite donors to the app who're sent an SMS
  • Compose & send messages to the organisation's subscribers


  • Receive an donation invite sms
  • Accept app permissions to send SMS
  • Get notifications when a message is sent, asking for donations
  • Have the control to send as many / few messages as they want
  • Can opt-out whenever they want

Code Structure

Folder Contents
activity The app's Activities
api Classes for accessing the Iris Msg api
common Common utilities, types & functions
di The Dagger dependancy injection modules & components
jwt Logic related to json web tokens
model The models returned from the api
receiver Broadcast receivers to handle app messages i.e. sms sent
repo Repositories for ViewModel's to get their data from, uses the api
service External services, i.e. for handling firebase messages
ui Fragments rendered by activities
viewmodel ViewModels for accessing api data

Libraries used


Mock api

The api can be swapped for a fake implementation for development, see AppModule

View Transitions

A small Finite State Machine (fsm) is used to handle multiple views in a single activity. The activity will have an enterState() method which transitions the state and ActivityName.State associated enum to define what states the views can be in.

Api Logic

Api-related logic should not be in the fragments, instead it bubbles up events or messages for the activity to handle it.

Event bus

An event bus is used to communicate between some classes, i.e. Activities and BroadcastReceivers.


Follow these steps to create and deploy a new release.

Generating an APK

Make sure there are no unstaged changes

  1. Edit app/build.gradle to update the versionName and increment the versionCode
  2. Perform a gradle sync
  3. Build a signed APK: Build > Generate Signed APK / Bundle
    1. Select APK
    2. Select the signing certificate, the credentials are in the Open Lab vault at devops/iris/app-signing-key
  4. Wait for the build to complete
  5. Add changes to git git add app/build.gradle app/release/output.log
  6. Commit the changes with the version number and a preceeding v, e.g. git commit -m 'v1.2'
  7. Tag the commit with the version, e.g. git tag 1.2

Uploading an APK

# cd /to/the/repo/root
# where $VERSION is the desired version

# Upload the archive
scp app/release/app-release.apk$VERSION.apk

# Update the symlink
cd /srv/files/
rm latest.apk
ln -s iris-msg-$VERSION.apk latest.apk

Updating the Api

You'll need to update the server stack to tell it the new version


A Kotlin Android app for Iris Msg







No packages published