Skip to content
This repository has been archived by the owner on Oct 8, 2020. It is now read-only.

Latest commit

 

History

History
105 lines (62 loc) · 6.14 KB

architecture.md

File metadata and controls

105 lines (62 loc) · 6.14 KB
Raw

Architecture specification

Version number: 1.0

Authors: Krzysztof Antoniak, Robert Michna, Maciej Procyk

Changelog

  • v1.0 (2020-04-22): Initial revision (Maciej Procyk)
  • v1.1 (2020-05-05): Architecture fix (Krzysztof Antoniak, Robert Michna)

Overview

System consists of five main elements: System overview

  • Admin panel
  • Database
  • API endpoint
  • Mobile clients
  • Camera devices

Admin panel

Admin panel is generated by Django web framework based on Django's database models. It is accessed through modern js-compatible web browser on /admin. The admin panel allows admin user to interact with the database.

Database

The database for this project is PostgreSQL v. 12. It supports every basic database interaction as well as concurrency. The database will either be hosted by a cloud hosting service or by a dedicated computer. SQLite database is also supported for development purposes allowing developers to quickly install and test the server.

API Endpoint

Server and clients other than web application communicate via REST API. Methods definition (see /specs/api.yaml) conforms to Open API 2.0 Specification.

Server exposes API endpoint using Django Rest Framework extension. API definition file is generated from this implementation.

For API definition file generation drf_yasg is used from the server side.

Clients leverage OpenAPI generator to generate the API handlers. Generated classes are not included in the repository. Please see client readme for generation instructions.

Generation instructions for clients apps (Android app)

Using the generated API definition file the model and API access classes can be generated. The ready to use script can be found in /android/api_generate_kotlin.sh with its usage in README.md file.

If any other app is going to use designed API endpoint for clients then the given script can be reconfigured for other programming languages.

Server and Android app communication

App loads the data from server in the background asking only for data needed to present on current app screen. The data is refreshed on every screen change in app.

When the connection with internet is lost by the device, app is suspended and waiting screen shows while waiting for active internet connection. The possible connections type supported by app are WiFi, cellular data and VPN connections.

Mobile client architecture

Client app designed for Android devices is developed in Android Studio in Kotlin. Build process is managed by the Gradle build system. App uses AndroidX support libraries to handle android system libraries.

For concurrency purpose the standard Kotlin coroutines are used. The new approach allows to write cleaner code that does not look like the "full of callbacks code" but works as expected in background.

The app uses the OpenStreet Maps with the MapView designed in osmdroid library allowing the developers to customize the map look and easily manage the map data caching.

User interface needs also some data visualizations of all the data so the data2viz library is used to build all the needed plots and graphs from scratch in a Kotlin code and easily place them into the standard Android layouts.

For the RESTful API endpoints generation in Android app the Kotlin code generator is used.

Custom Android widgets are developed as the part of the project as well as used from open-source projects.

The client app is designed to be multilingual app to provide access to occupancy data also for foreign people. All the translations are managed via resource files with mappings for application text views.

App UI design

Android app is divided in a few activities that allows users to work with different tasks and some of them consists of a few fragments. The initially planned architecture is to use activities [A] and fragments [F] for:

  1. Hello application screen to give the user possibility to choose if he would like to use list or map search [A]

  2. Search map of canteens data [A]

  3. List search with filters of canteens data [A]

  4. Settings screen of application [A]

  5. Main application screen with presented data [A] divided into:

    • Main canteen data such as name, logo, opening hours, base stats from day, descriptions [F]
    • More stats data with a place for predictions in future releases [F]
    • Menu options screen with internal fragments for rating menu options [F]

Camera devices

Camera devices are Raspberry Pi 3B+ (or newer) boards running Raspbian Buster Lite February 2020 release. Each device is equipped with a 32GB SD card, WiFi card for internet connection and Camera Module or external USB webcam.

Camera Device Software

Device software consists of two parts:

  • setup flow for registering credentials in device memory,
  • main script for running analysis.

Both elements are Python 3.7 scripts with Python language bindings from other software like OpenCV.

Setup flow saves user credentials in an .env configuration file and makes a test connection with the server to confirm their validity. Test call is handled by a Python API client generated from API definition. These credentials will be later used to communicate with the server.

Main script starts automatically with the device and terminates if credentials are not set up. Its modules are as follows:

  • Frame ingestor: stateless service, which collects frames from Camera device, USB webcam or input video file
  • Image analysis: performs image analysis to count people coming in and out. Prediction system uses OpenCV for people detection.
  • Data batcher: Batches datapoints in preset intervals, saves batches to device memory
  • API client: automatically generated API client which uploads batches of events