Gauteng Wellbeing Mapper - Research Features Summary

Overview

This document summarizes the major features of the Gauteng Wellbeing Mapper app to support research participation with end-to-end encryption. These features enable secure data collection for the research study in Gauteng, South Africa.

Key Features

1. Two-Way Participation System ✨

Users can now choose between two modes when starting the app:

Implementation:

2. End-to-End Encryption System 🔐

Hybrid Encryption Approach:

Security Features:

Implementation:

Granular User Control:

Location Clustering:

Consent Management:

Implementation:

4. Enhanced Notification System 🔔

Dual-Notification Approach:

Enhanced Testing Tools:

Platform Support:

Implementation:

5. Gauteng Research Features 🌍

Gauteng Research:

Implementation:

6. Secure Data Upload System 📤

Features:

Implementation:

6. Enhanced Database Schema 🗄️

New/Updated Tables:

Features:

Technical Architecture

Encryption Pipeline

Survey Data + Location Tracks
           ↓
    JSON Serialization
           ↓
    AES-256-GCM Encryption (random key)
           ↓
    RSA-4096-OAEP Key Encryption
           ↓
    Base64 Encoding: encrypted_key|encrypted_data
           ↓
    HTTPS POST to Research Server
           ↓
    Secure Storage (encrypted)

Multi-Site Configuration

static const Map<String, ServerConfig> _serverConfigs = {
  'gauteng': ServerConfig(
    baseUrl: 'https://gauteng-research.domain.com',
    uploadEndpoint: '/api/v1/participant-data',
    publicKey: '''-----BEGIN PUBLIC KEY-----
    [RSA-4096 PUBLIC KEY FOR GAUTENG TEAM]
    -----END PUBLIC KEY-----''',
  ),
};

Research Team Setup Instructions

1. Generate RSA Key Pairs

For each research site, generate a 4096-bit RSA key pair:

# Gauteng keys  
openssl genrsa -out gauteng_private_key.pem 4096
openssl rsa -in gauteng_private_key.pem -pubout -out gauteng_public_key.pem

2. Configure Mobile App

Update Public Keys: Edit lib/services/data_upload_service.dart and replace the public key placeholders with your generated public keys.

Update Server URLs: Replace baseUrl values with your actual research server domains.

Rebuild App:

fvm flutter clean
fvm flutter pub get
fvm flutter build apk --release

3. Set Up Research Servers

Required Components:

API Endpoint:

POST /api/v1/participant-data
Content-Type: application/json

{
  "uploadId": "uuid-v4",
  "participantUuid": "uuid-v4", 
  "researchSite": "gauteng",
  "encryptedData": "base64-encoded-payload",
  "encryptionMetadata": { ... },
  "dataPeriod": { "start": "...", "end": "..." }
}

4. Data Decryption

Server-side decryption example (Node.js):

function decryptUpload(encryptedPayload, encryptionMetadata, privateKey) {
  const [encryptedAESKey, encryptedData] = encryptedPayload.split('|');
  
  // Decrypt AES key with RSA private key
  const aesKey = crypto.privateDecrypt({
    key: privateKey,
    padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
    oaepHash: 'sha256'
  }, Buffer.from(encryptedAESKey, 'base64'));
  
  // Decrypt data with AES-256-GCM
  const iv = Buffer.from(encryptionMetadata.iv, 'base64');
  const decipher = crypto.createDecipherGCM('aes-256-gcm', aesKey);
  // ... complete decryption process
  
  return JSON.parse(decryptedData);
}

Decrypted Data Structure

After successful decryption, research teams receive:

{
  "participantUuid": "anonymous-uuid",
  "researchSite": "gauteng",
  "uploadTimestamp": "2025-07-23T10:30:00Z",
  "surveys": [
    {
      "type": "initial" | "recurring",
      "submittedAt": "2025-07-23T10:30:00Z",
      "responses": {
        "wellbeingScore": 1-10,
        "stressLevel": 1-10,
        "mood": "happy|neutral|sad|anxious|...",
        "suburb": "string",           // Gauteng only
        "generalHealth": "excellent|good|fair|poor",  // Gauteng only
        "ethnicity": "string",        // Site-specific options
        "buildingType": "string"      // Site-specific options
      }
    }
  ],
  "locationTracks": [
    {
      "timestamp": "2025-07-23T10:15:00Z",
      "latitude": -26.1076,
      "longitude": 28.0567,
      "accuracy": 10.5
    }
  ]
}

Privacy & Security Features

Data Protection

Compliance Features

User Control

Documentation

For Research Teams

For Developers

Testing & Validation

Encryption Testing

# Run encryption tests
fvm flutter test test/encryption_test.dart

# Validate key pairs
node test-encryption.js

# End-to-end validation
fvm flutter drive --target=test_driver/encryption_driver.dart

App Compilation

# Analyze code for errors
fvm flutter analyze

# Run all tests
fvm flutter test

# Build release version
fvm flutter build apk --release

Deployment Checklist

Pre-Deployment

App Release

Post-Deployment

Support

For technical issues:

  1. App Issues: Check Flutter logs and error reporting
  2. Encryption Issues: Verify key formats and server configuration
  3. Server Issues: Check API logs and database connectivity
  4. Research Questions: Contact the Planet4Health project team

Future Enhancements

Planned Features

Research Extensions