GeoSenEsm (Geolocation and sensor data supported ESM) is a tool developed for research using Experience Sampling Method. It was created as a part of a UrbEaT project.
GeoSenEsm offers a ready mobile application for Android and iPhones and simple DYI setup instructions for server side admin portal. The application is shared under MIT license and is free to use. Study administrators install server side admin portal on their own server allowing them to retain independence and full control over data and study design.
Project repository: https://github.com/geosenesm
Project user guide: User Guide
Contact: Put an issue request in github or through https://urbeat.site/kontakt/
GeoSenEsm mobile app belongs to AMU Adam Mickiewicz University (to maintain mobile app for research in EU) and Institute of Atmospheric Physics, Chinese Academy of Sciences (IAP/CAS) (to maintain mobile app for research in China)Authors: Mateusz Dokowicz, Paweł Felcyn, Mikołaj Gawor, Wiktoria Grzesik, Marcin Witkowski
Simple design inclusive for older respondents - main screen of the application is only dedicated to surveys. Surveys display only one question at a time and support large fonts.
Data security - all data is sent to and stored in one place only - researcher own server. The researcher is the only one who has access to all data.
Scheduling and notifications - set up start and finish time for your surveys, repeat them multiple times a day, respondents will be notified on survey start and when it comes to an end.
Fully operational offline - all surveys and responses are saved locally in the app and saved data are cached and will be uploaded as soon as there is an internet connection.
Admin portal - setup surveys and review results during the study using the admin portal. All study data can be exported to csv format.
Location and sensor data - enrich survey data with geolocation and readings from a growing library of Bluetooth sensors (Xiaomi, Kestrel, Ruuvi, and more). Study administrators can add further sensor types themselves from the admin panel, no app update required. Limit the study to specific geographical region.
Open source and anonymous - setup your own server following our guideline, collect data with our mobile app, generate anonymous accounts for respondents. Researcher have full control over access to study.
Multiple question types and conditional routes - delegate question to subgroup from your study, setup conditional routes in survey, use one of six types of questions in your survey.
Privacy and data sharing - respondents have access to shared sensor readings and locations and can limit the location sharing to specific hours of the day. Location data are shared with a one day delay to avoid live tracing the respondents movements.
This repository (GeoSenEsm/.github) holds organization-level GitHub
configuration and documentation for the GeoSenEsm platform. It is not an
application codebase.
| Default branch | main |
| Role | Org profile, shared docs, release notes at the organization level |
| Product repos | survey-api, survey-admin-panel, mobile-app, devops |
| Path | Purpose |
|---|---|
README.md |
This file — org overview for developers |
profile/README.md |
GitHub organization profile (rendered on the org home page) |
profile/GeoSenEsm__User_Guide.pdf |
End-user / administrator guide |
profile/AddingSensor.pdf |
Guide for adding a new sensor type via the admin panel's profile-driven GATT engine |
profile/geosenesm.png |
Branding asset for the org profile |
LICENSE |
License for materials in this repository |
.github/ (cloned locally as githubDocs/)
├── README.md
├── LICENSE
└── profile/
├── README.md # org landing page content
├── GeoSenEsm__User_Guide.pdf
├── AddingSensor.pdf
└── geosenesm.png
| Repository | Default branch | Role |
|---|---|---|
| GeoSenEsm/survey-api | master |
Spring Boot REST API (Java 17). Primary SQL Server + MongoDB response documents. |
| GeoSenEsm/survey-admin-panel | master |
Angular 17 admin portal for researchers. |
| GeoSenEsm/mobile-app | master |
Flutter respondent app (Android / iOS), white-label geosenesm / urbeat. |
| GeoSenEsm/devops | master |
Ubuntu production setup: Nginx, TLS, privacy policy, Docker Compose (API + admin + MongoDB; SQL Server optional in-compose). |
The three application repositories share one REST contract. Changes that
alter HTTP shape, DTOs, or auth must be coordinated across
survey-api, survey-admin-panel, and mobile-app.
devops is deployment documentation only — it does not contain application
source. It tells operators how to run published GHCR images
(ghcr.io/geosenesm/survey-api:prod,
ghcr.io/geosenesm/survey-admin-panel:prod) behind Nginx on Ubuntu, with
two SQL Server layouts (MongoDB runs in Docker on the app host in both):
| Variant | When to use |
|---|---|
variants/separate_mssql |
App server + separate MSSQL host; Mongo in Compose |
variants/no_separate_mssql |
Single server; MSSQL + Mongo in Docker on the same VM |
Typical host mapping after setup: public api.* → local 8083, public
admin.* → local 8084. Privacy-policy HTML is served from
/var/www/html/privacy-policy for the mobile app’s first-login consent flow.
Prefer annotated tags for releases (for example v1.0.0, v2.0.0).
Check each product repository for the tags currently published.
CI workflows live under .github/workflows/ in each application
repository (survey-api, survey-admin-panel, mobile-app) — not in this
org docs repo and not in devops. Pipelines typically run against the
default branch, build container images, and publish them to the organization
container registry (for example GHCR / GitHub Packages).
Consult the workflow files in survey-api and survey-admin-panel for the
exact registry, image names, and tag strategy. Use
GeoSenEsm/devops for how those
published images are deployed on a production Ubuntu host.
- User guide (PDF): profile/GeoSenEsm__User_Guide.pdf
- Org profile content: profile/README.md
- Per-repo developer notes: README in each of
survey-api,survey-admin-panel, andmobile-app - Production server setup: GeoSenEsm/devops README and
variants/