# helpwave-app/helpwave_mobile_app architecture

> Architecture diagram of the GitHub repository helpwave-app/helpwave_mobile_app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/helpwave-app/helpwave_mobile_app
- Repository: https://github.com/helpwave-app/helpwave_mobile_app

## Overview

##### Project type and purpose
- Project type: Full-stack mobile application (Android + iOS)
- Purpose: Connect users requesting help (especially seniors) with remote volunteers via video calls

##### File structure
Top-level directories:
- android/, ios/ → native platform shells (Gradle/Xcode projects, platform integration)
- lib/ → Flutter app code, organized in:
– localization (codegen, JSON files)
– src/common (themes, constants, animations, utilities, Firebase options)
– src/features (feature-based modules with application, domain, data, presentation layers)
– routing (AppRouter)
- scripts/ → CI/CD helpers (version bump, deploy)
- test/ → widget tests

##### Extract key insights from the README
- Frontend: Flutter 3.x + Riverpod/StateNotifier
- Backend: Spring Boot (Java) + PostgreSQL
- Communication & data: Firebase Auth, Firestore, Cloud Messaging
- Video: Agora Video SDK
- CI/CD: GitHub Actions, Firebase App Distribution

##### Main components
A. Mobile Client (Flutter)
1. Platform layers: Android shell, iOS shell
2. Flutter engine & Dart code
3. State management: Riverpod + StateNotifier
4. Feature modules (Auth, Availability, Gamification, Home, Language, Notifications, Profile, Reports, Reviews, Settings, Skills, Videocalls)
5. Routing layer (AppRouter)
6. Localization loader
B. External Services
1. Firebase Auth (user sign-in/up)
2. Firestore (real-time data store)
3. Firebase Cloud Messaging (push notifications)
4. Agora Video SDK (video-call sessions)
C. Backend API
1. Spring Boot REST service
2. PostgreSQL database
D. CI/CD
1. GitHub Actions workflows (build, version bump, release)
2. Firebase App Distribution

##### Relationships and data flows
- Mobile ↔ Firebase Auth: obtain JWT
- Mobile ↔ Spring Boot API: authenticated REST calls (help requests, profile, reports, gamification)
- Mobile ↔ Firestore: real-time updates (e.g., volunteer availability)
- Mobile ↔ FCM: subscribe & receive push notifications (new help request)
- Mobile ↔ Agora SDK: establish P2P video stream for calls
- Spring Boot → PostgreSQL: persistent storage of domain data
- CI/CD → GitHub → Build artifacts → Firebase App Distribution

##### Architectural patterns & design principles
- Feature-based modular structure (Clean Architecture flavor)
– Presentation (widgets/pages)
– Application (controllers/state notifiers)
– Domain (pure models/entities)
– Data (services, API clients, JSON models)
- Separation of concerns: UI vs state vs data vs domain
- Dependency injection (Riverpod providers)
- Single source of truth in Firestore + relational store in PostgreSQL for historical/reporting data

##### Final checklist
[ ] All layers/components labeled
[ ] Architectural patterns (layering, feature modules) are evident
[ ] External dependencies (Firebase, Agora) visually distinct
[ ] CI/CD path from code → build → distribution included

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Mobile Client"
        direction TB
        Android["Android Shell"]:::mobile
        IOS["iOS Shell"]:::mobile
        Engine["Flutter Entry Point & Engine"]:::mobile
        State["State Management (Riverpod/StateNotifier)"]:::mobile
        Localization["Localization Loader & Resources"]:::mobile
        Routing["Routing Layer (AppRouter)"]:::mobile
        Utils["Common Utilities & Themes"]:::mobile
        subgraph "Feature Modules"
            direction TB
            Auth["Auth Module"]:::mobile
            Availability["Availability Module"]:::mobile
            Gamification["Gamification Module"]:::mobile
            Home["Home Module"]:::mobile
            Language["Language Module"]:::mobile
            Notifications["Notifications Module"]:::mobile
            Profile["Profile Module"]:::mobile
            Reports["Reports Module"]:::mobile
            Reviews["Reviews Module"]:::mobile
            Settings["Settings Module"]:::mobile
            Skills["Skills Module"]:::mobile
            Videocalls["Videocalls Module"]:::mobile
        end
    end

    subgraph "Backend & Services"
        direction TB
        API["Spring Boot API"]:::backend
        DB["PostgreSQL"]:::backend
        subgraph "Firebase Services"
            direction TB
            FA["Firebase Auth"]:::external
            FS["Firestore"]:::external
            FCM["FCM"]:::external
        end
        Agora["Agora Video SDK"]:::external
    end

    subgraph "CI/CD Pipeline"
        direction TB
        GH["GitHub Actions"]:::cicd
        Scripts["Scripts (bump_version.sh, deploy.sh)"]:::cicd
        FirebaseConf["Firebase Project Configuration"]:::cicd
        GH -->|build & release| Scripts
        Scripts -->|deploy builds| FirebaseConf
    end

    Engine --> State
    Engine --> Localization
    Engine --> Routing
    Engine --> Utils
    Engine --> Auth
    State -->|uses| Routing
    Routing -->|routes| Auth
    Engine -->|HTTPS/REST| API
    Engine -->|Realtime| FS
    Engine -->|FCM| FCM
    Engine -->|P2P Video| Agora
    Engine -->|Auth JWT| FA
    API -->|JPA/SQL| DB

    click Android "https://github.com/helpwave-app/helpwave_mobile_app/tree/main/android/"
    click IOS "https://github.com/helpwave-app/helpwave_mobile_app/tree/main/ios/"
    click Engine "https://github.com/helpwave-app/helpwave_mobile_app/blob/main/lib/main.dart"
    click State "https://github.com/helpwave-app/helpwave_mobile_app/blob/main/lib/src/common/utils/constants/providers.dart"
    click Localization "https://github.com/helpwave-app/helpwave_mobile_app/blob/main/lib/localization/codegen_loader.g.dart"
    click Routing "https://github.com/helpwave-app/helpwave_mobile_app/blob/main/lib/src/routing/app_router.dart"
    click Utils "https://github.com/helpwave-app/helpwave_mobile_app/blob/main/lib/src/common/utils/constants/app_theme.dart"
    click Utils "https://github.com/helpwave-app/helpwave_mobile_app/blob/main/lib/src/common/utils/firebase/firebase_options.dart"
    click Utils "https://github.com/helpwave-app/helpwave_mobile_app/blob/main/lib/src/common/utils/firebase/fcm_config.dart"
    click Utils "https://github.com/helpwave-app/helpwave_mobile_app/blob/main/lib/src/common/utils/permissions_helper.dart"
    click Auth "https://github.com/helpwave-app/helpwave_mobile_app/tree/main/lib/src/features/auth/application"
    click Availability "https://github.com/helpwave-app/helpwave_mobile_app/tree/main/lib/src/features/availability/application"
    click Gamification "https://github.com/helpwave-app/helpwave_mobile_app/tree/main/lib/src/features/gamification/application"
    click Home "https://github.com/helpwave-app/helpwave_mobile_app/tree/main/lib/src/features/home/application"
    click Language "https://github.com/helpwave-app/helpwave_mobile_app/tree/main/lib/src/features/language/application"
    click Notifications "https://github.com/helpwave-app/helpwave_mobile_app/tree/main/lib/src/features/notifications/presentation"
    click Profile "https://github.com/helpwave-app/helpwave_mobile_app/tree/main/lib/src/features/profile/application"
    click Reports "https://github.com/helpwave-app/helpwave_mobile_app/tree/main/lib/src/features/reports/data"
    click Reviews "https://github.com/helpwave-app/helpwave_mobile_app/tree/main/lib/src/features/reviews/application"
    click Settings "https://github.com/helpwave-app/helpwave_mobile_app/tree/main/lib/src/features/settings/presentation"
    click Skills "https://github.com/helpwave-app/helpwave_mobile_app/tree/main/lib/src/features/skills/application"
    click Videocalls "https://github.com/helpwave-app/helpwave_mobile_app/tree/main/lib/src/features/videocalls/application"
    click FA "https://github.com/helpwave-app/helpwave_mobile_app/blob/main/lib/src/common/utils/firebase/firebase_options.dart"
    click Agora "https://github.com/helpwave-app/helpwave_mobile_app/blob/main/lib/src/common/utils/constants/agora_api.dart"
    click GH "https://github.com/helpwave-app/helpwave_mobile_app/blob/main/.github/workflows/release-build.yml"
    click Scripts "https://github.com/helpwave-app/helpwave_mobile_app/blob/main/scripts/bump_version.sh"
    click Scripts "https://github.com/helpwave-app/helpwave_mobile_app/blob/main/scripts/deploy.sh"
    click FirebaseConf "https://github.com/helpwave-app/helpwave_mobile_app/blob/main/.firebaserc"

    classDef mobile fill:#D6EAF8,stroke:#2980B9,color:#1B4F72;
    classDef backend fill:#E8DAEF,stroke:#8E44AD,color:#512E5F;
    classDef external fill:#FEF9E7,stroke:#F1C40F,color:#7D6608;
    classDef cicd fill:#E8F8F5,stroke:#1ABC9C,color:#0E6251;
```
