Wellbeing Mapper - Architecture Overview

System Architecture Overview

Wellbeing Mapper follows a layered architecture pattern designed for maintainability, testability, and scalability. The application is built using Flutter and implements a clean separation of concerns to support mental wellbeing mapping in environmental & climate context as part of the Planet4Health research project.

The architecture includes research participation with end-to-end encryption for secure data transmission from participants’ phones to the research team.

Architectural Layers

1. Presentation Layer (ui/)

The presentation layer handles all user interface components and user interactions.

Key Components:

Responsibilities:

2. Business Logic Layer (models/, services/)

This layer contains the application’s business rules and data processing logic.

Key Components:

Responsibilities:

3. Data Layer (db/ and models/)

The data layer manages all data persistence and retrieval operations.

Key Components:

Responsibilities:

4. Platform Layer (util/ and platform services)

This layer handles platform-specific functionality and external service integration.

Key Components:

Responsibilities:

Security & Encryption Architecture

Hybrid Encryption System

The app implements a sophisticated encryption system for secure research data transmission.

Encryption Components:

Security Features:

Component Interaction Diagram

graph TB
    subgraph "Presentation Layer"
        A[ParticipationSelectionScreen]
        B[ConsentFormScreen]
        C[DataUploadScreen]
        D[HomeView]
        E[MapView]
        F[SurveyScreens]
    end
    
    subgraph "Business Logic Layer"
        G[DataUploadService]
        H[ConsentModels]
        I[SurveyModels]
        J[RouteGenerator]
        K[CustomLocation]
        L[LocationManager]
    end
    
    subgraph "Data Layer"
        K[SurveyDatabase]
        L[UnpushedLocationsDB]
        M[SharedPreferences]
        N[FileStorage]
    end
    
    subgraph "Platform Layer"
        P[BackgroundGeolocation]
        Q[Authentication]
        R[WebServices]
        S[Environment]
    end
    
    A --> F
    A --> I
    B --> G
    C --> G
    D --> H
    D --> J
    E --> H
    
    F --> K
    G --> L
    G --> M
    H --> K
    I --> P
    J --> K
    
    G --> P
    H --> R
    I --> Q
    J --> R
    
    K --> N
    L --> N
    M --> O

Data Flow Architecture

Location Tracking Flow

sequenceDiagram
    participant U as User
    participant HV as HomeView
    participant BG as BackgroundGeolocation
    participant CL as CustomLocation
    participant DB as Database
    participant MV as MapView
    
    U->>HV: Enable Tracking
    HV->>BG: Start Location Service
    BG->>BG: Background Monitoring
    BG->>CL: Location Event
    CL->>CL: Process Location Data
    CL->>DB: Store Location
    CL->>MV: Update Map Display
    MV->>U: Visual Update

App Mode Selection Flow

sequenceDiagram
    participant U as User
    participant MS as ModeSelection
    participant Config as AppConfig
    participant Prefs as SharedPreferences
    participant WV as WebView
    
    U->>MS: Select App Mode
    MS->>U: Display Mode Options
    U->>MS: Choose Research Mode
    MS->>WV: Show Consent Form
    WV->>U: Display Consent
    U->>WV: Accept Consent
    WV->>Config: Update Mode Configuration
    Config->>Prefs: Save Mode Settings
    Prefs->>MS: Confirm Update
    MS->>U: Mode Activated

Performance Considerations

Location Tracking Optimization

Database Optimization

Testing Architecture

Testing Strategy

  1. Unit Tests: Individual class and method testing
  2. Widget Tests: UI component testing
  3. Integration Tests: End-to-end workflow testing
  4. Platform Tests: Native functionality testing

Test Organization

test/
├── unit/
│   ├── models/
│   ├── services/
│   └── utils/
├── widget/
│   ├── ui/
│   └── components/
└── integration_test/
    ├── location_tracking_test.dart
    ├── project_participation_test.dart
    └── app_test.dart

Deployment Architecture

Build Configuration

Platform-Specific Considerations