# rahulop11/appumangly architecture

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

- Interactive diagram: https://gitdiagram.com/rahulop11/appumangly
- Repository: https://github.com/rahulop11/appumangly

## Overview

#### 1. Purpose and Runtime
Umangly is a cross-platform Flutter/Dart mental-wellness client combining mood/diary tracking, mindfulness content, AI companions, and camera-based emotion/smile features. The primary application entry point is `lib/main.dart`; it builds for Android, iOS, web, Linux, macOS, and Windows.

#### 2. Client Navigation and Feature Surfaces
Flutter screens form the feature-oriented presentation layer, including dynamic/home flows, authentication, mood selection, diary, meditation, smile camera, and companion chat. Key user-facing orchestration paths include:
- `lib/screens/dynamic_home_screen.dart`
- `lib/screens/emotion_check_screen.dart`
- `lib/screens/virtual_friend_chat_screen.dart`

Authentication-specific screens are under `lib/screens/auth/login_screen.dart` and `lib/screens/auth/signup_screen.dart`.

#### 3. Firebase Identity and User Data Boundary
Firebase is the cloud system of record for authenticated user data, with generated app initialization options and Firestore access controls. App services should isolate Firebase reads/writes from screen code; the rules file defines the authorization boundary.
- `lib/firebase_options.dart`
- `lib/services/diary_service.dart`
- `firestore.rules`

The committed Android configuration indicates Firebase services are provisioned for Android: `android/app/google-services.json`.

#### 4. Mood, Diary, and Analytics Pipeline
Users select or derive emotional state, persist diary/mood-related records, then consume aggregation and insight views. Typed domain models separate diary, mood, meditation, smile, and companion concepts from UI/service implementations.
- `lib/models/mood_models.dart`
- `lib/models/diary_models.dart`
- `lib/services/mood_analytics_service.dart`

Primary presentation endpoints are `lib/screens/mood_selection_screen.dart`, `lib/screens/diary_screen.dart`, and `lib/screens/diary_analytics_screen.dart`.

#### 5. AI Companion Integration
The virtual-friend layer supports distinct AI providers/personas: Gemini for Meera and Dialogflow-oriented flows for Arav, with an offline fallback path. Screen code should call the service abstraction rather than provider APIs directly.
- `lib/services/virtual_friend_service.dart`
- `lib/services/gemini_ai_service.dart`
- `lib/services/dialogflow_service.dart`

Offline continuity is represented by `lib/services/offline_virtual_friend_service.dart`; companion data contracts live in `lib/models/virtual_friend_models.dart`.

#### 6. Emotion and Smile Detection Boundary
Emotion recognition is separated from the Flutter UI through detection services and camera/webview screens. The repository also contains independently runnable Python/OpenCV-oriented implementations, making this a client-to-local/HTTP detector integration boundary rather than a purely Dart model.
- `lib/services/emotion_detection_service.dart`
- `lib/services/offline_emotion_detection_service.dart`
- `web_emotion_detection/emotion_api.py`

Relevant UI routes are `lib/screens/smile_camera_screen.dart` and `lib/screens/emotion_webview_screen.dart`. Model assets include `assets/models/mock_emotion_model.tflite`.

#### 7. Mindfulness Media and Rewards
Meditation, breathing, affirmations, ambient audio, TTS, and smile rewards are local client workflows backed by service abstractions and typed meditation/smile models. Audio/content providers are external-service boundaries where configured.
- `lib/services/audio_service.dart`
- `lib/services/freesound_api_service.dart`
- `lib/services/smile_rewards_service.dart`

Core feature routes include `lib/screens/meditation_screen.dart`, `lib/screens/breathing_exercise_screen.dart`, and `lib/screens/affirmation_screen.dart`.

#### 8. Platform Integration
Flutter owns most behavior, while Android adds WebView navigation and permission handling for embedded emotion-detection experiences:
- `android/app/src/main/kotlin/com/example/umangly/MainActivity.kt`
- `android/app/src/main/kotlin/com/example/umangly/CustomWebViewClient.kt`
- `android/app/src/main/kotlin/com/example/umangly/WebViewPermissionHandler.kt`

Native runners in `ios/`, `web/`, `linux/`, `macos/`, and `windows/` are platform shells rather than separate application architectures.

Main entry points: [`lib/screens/dynamic_home_screen.dart`](https://github.com/rahulop11/appumangly/blob/main/lib/screens/dynamic_home_screen.dart) (Feature screens), [`lib/services/virtual_friend_service.dart`](https://github.com/rahulop11/appumangly/blob/main/lib/services/virtual_friend_service.dart) (Virtual friend service), [`lib/screens/smile_camera_screen.dart`](https://github.com/rahulop11/appumangly/blob/main/lib/screens/smile_camera_screen.dart) (Camera and webview UI), [`lib/screens/mood_selection_screen.dart`](https://github.com/rahulop11/appumangly/blob/main/lib/screens/mood_selection_screen.dart) (Mood and diary views)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Flutter client"]
  node_app["App bootstrap<br/>Flutter entry point<br/>[main.dart]"]
  node_screens["Feature screens<br/>Flutter presentation"]
  node_companion_screen["Companion chat<br/>Flutter screen"]
  node_mood_diary_screens["Mood and diary views<br/>Flutter screens"]
  node_domain_models["Mood and diary models<br/>Dart domain models<br/>[mood_models.dart]"]
  node_analytics["Mood analytics<br/>analytics service"]
end

subgraph group_cloud["Firebase boundary"]
  node_diary_service["Diary data service<br/>Firebase data service<br/>[diary_service.dart]"]
  node_firebase[("Firebase<br/>identity and datastore")]
  node_firestore_rules["Firestore rules<br/>authorization policy<br/>[firestore.rules]"]
end

subgraph group_ai["AI companions"]
  node_virtual_friend["Virtual friend service<br/>AI abstraction"]
  node_gemini["Gemini / Meera<br/>AI provider service"]
  node_dialogflow["Dialogflow / Arav<br/>AI provider service"]
  node_offline_friend["Offline companion<br/>fallback service"]
end

subgraph group_emotion["Emotion detection"]
  node_emotion_screens["Camera and webview UI<br/>Flutter screens"]
  node_emotion_service["Emotion detection service<br/>detector abstraction"]
  node_python_detector{{"Python emotion API<br/>local or HTTP detector<br/>[emotion_api.py]"}}
  node_native_webview["Android WebView integration<br/>native platform bridge<br/>[MainActivity.kt]"]
end

subgraph group_wellness["Mindfulness media"]
  node_mindfulness_screens["Meditation and breathing UI<br/>Flutter screens"]
  node_audio_service["Audio service<br/>media service<br/>[audio_service.dart]"]
  node_freesound{{"Freesound API<br/>external content service"}}
  node_smile_rewards["Smile rewards<br/>reward service"]
end

node_app -->|"starts"| node_screens
node_screens -->|"navigates to"| node_mood_diary_screens
node_screens -->|"navigates to"| node_companion_screen
node_screens -->|"navigates to"| node_emotion_screens
node_screens -->|"navigates to"| node_mindfulness_screens
node_mood_diary_screens -->|"persists records"| node_diary_service
node_mood_diary_screens -->|"requests insights"| node_analytics
node_diary_service -->|"maps records"| node_domain_models
node_analytics -->|"aggregates"| node_domain_models
node_diary_service -->|"reads and writes"| node_firebase
node_firestore_rules -.->|"authorizes access"| node_firebase
node_companion_screen -->|"sends chat"| node_virtual_friend
node_virtual_friend -->|"Meera requests"| node_gemini
node_virtual_friend -->|"Arav requests"| node_dialogflow
node_virtual_friend -.->|"fallback"| node_offline_friend
node_emotion_screens -->|"submits capture"| node_emotion_service
node_emotion_screens -->|"uses embedded detector"| node_native_webview
node_emotion_service -->|"detects emotion"| node_python_detector
node_mindfulness_screens -->|"plays media"| node_audio_service
node_audio_service -->|"fetches content"| node_freesound
node_emotion_screens -->|"awards smiles"| node_smile_rewards

click node_app "https://github.com/rahulop11/appumangly/blob/main/lib/main.dart"
click node_screens "https://github.com/rahulop11/appumangly/blob/main/lib/screens/dynamic_home_screen.dart"
click node_companion_screen "https://github.com/rahulop11/appumangly/blob/main/lib/screens/virtual_friend_chat_screen.dart"
click node_mood_diary_screens "https://github.com/rahulop11/appumangly/blob/main/lib/screens/mood_selection_screen.dart"
click node_emotion_screens "https://github.com/rahulop11/appumangly/blob/main/lib/screens/smile_camera_screen.dart"
click node_domain_models "https://github.com/rahulop11/appumangly/blob/main/lib/models/mood_models.dart"
click node_diary_service "https://github.com/rahulop11/appumangly/blob/main/lib/services/diary_service.dart"
click node_analytics "https://github.com/rahulop11/appumangly/blob/main/lib/services/mood_analytics_service.dart"
click node_firebase "https://github.com/rahulop11/appumangly/blob/main/lib/firebase_options.dart"
click node_firestore_rules "https://github.com/rahulop11/appumangly/blob/main/firestore.rules"
click node_virtual_friend "https://github.com/rahulop11/appumangly/blob/main/lib/services/virtual_friend_service.dart"
click node_gemini "https://github.com/rahulop11/appumangly/blob/main/lib/services/gemini_ai_service.dart"
click node_dialogflow "https://github.com/rahulop11/appumangly/blob/main/lib/services/dialogflow_service.dart"
click node_offline_friend "https://github.com/rahulop11/appumangly/blob/main/lib/services/offline_virtual_friend_service.dart"
click node_emotion_service "https://github.com/rahulop11/appumangly/blob/main/lib/services/emotion_detection_service.dart"
click node_python_detector "https://github.com/rahulop11/appumangly/blob/main/web_emotion_detection/emotion_api.py"
click node_native_webview "https://github.com/rahulop11/appumangly/blob/main/android/app/src/main/kotlin/com/example/umangly/MainActivity.kt"
click node_mindfulness_screens "https://github.com/rahulop11/appumangly/blob/main/lib/screens/meditation_screen.dart"
click node_audio_service "https://github.com/rahulop11/appumangly/blob/main/lib/services/audio_service.dart"
click node_freesound "https://github.com/rahulop11/appumangly/blob/main/lib/services/freesound_api_service.dart"
click node_smile_rewards "https://github.com/rahulop11/appumangly/blob/main/lib/services/smile_rewards_service.dart"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_screens,node_companion_screen,node_mood_diary_screens,node_domain_models,node_analytics toneBlue
class node_diary_service,node_firebase,node_firestore_rules toneAmber
class node_virtual_friend,node_gemini,node_dialogflow,node_offline_friend toneMint
class node_emotion_screens,node_emotion_service,node_python_detector,node_native_webview toneRose
class node_mindfulness_screens,node_audio_service,node_freesound,node_smile_rewards toneIndigo
```

## Components

### Flutter client

- [App bootstrap](https://github.com/rahulop11/appumangly/blob/main/lib/main.dart): Flutter entry point · Builds the cross-platform client. · `lib/main.dart`
- [Feature screens](https://github.com/rahulop11/appumangly/blob/main/lib/screens/dynamic_home_screen.dart): Flutter presentation · Home, auth, mood, diary, and mindfulness routes. · `lib/screens/dynamic_home_screen.dart`
- [Companion chat](https://github.com/rahulop11/appumangly/blob/main/lib/screens/virtual_friend_chat_screen.dart): Flutter screen · `lib/screens/virtual_friend_chat_screen.dart`
- [Mood and diary views](https://github.com/rahulop11/appumangly/blob/main/lib/screens/mood_selection_screen.dart): Flutter screens · Selection, entry, and analytics views. · `lib/screens/mood_selection_screen.dart`
- [Mood and diary models](https://github.com/rahulop11/appumangly/blob/main/lib/models/mood_models.dart): Dart domain models · `lib/models/mood_models.dart`
- [Mood analytics](https://github.com/rahulop11/appumangly/blob/main/lib/services/mood_analytics_service.dart): analytics service · Aggregates persisted mood and diary records. · `lib/services/mood_analytics_service.dart`

### Firebase boundary

- [Diary data service](https://github.com/rahulop11/appumangly/blob/main/lib/services/diary_service.dart): Firebase data service · Isolates diary reads and writes from screens. · `lib/services/diary_service.dart`
- [Firebase](https://github.com/rahulop11/appumangly/blob/main/lib/firebase_options.dart): identity and datastore · System of record for authenticated user data. · `lib/firebase_options.dart`
- [Firestore rules](https://github.com/rahulop11/appumangly/blob/main/firestore.rules): authorization policy · Defines Firestore access controls. · `firestore.rules`

### AI companions

- [Virtual friend service](https://github.com/rahulop11/appumangly/blob/main/lib/services/virtual_friend_service.dart): AI abstraction · Routes persona requests without exposing providers to UI. · `lib/services/virtual_friend_service.dart`
- [Gemini / Meera](https://github.com/rahulop11/appumangly/blob/main/lib/services/gemini_ai_service.dart): AI provider service · `lib/services/gemini_ai_service.dart`
- [Dialogflow / Arav](https://github.com/rahulop11/appumangly/blob/main/lib/services/dialogflow_service.dart): AI provider service · `lib/services/dialogflow_service.dart`
- [Offline companion](https://github.com/rahulop11/appumangly/blob/main/lib/services/offline_virtual_friend_service.dart): fallback service · `lib/services/offline_virtual_friend_service.dart`

### Emotion detection

- [Camera and webview UI](https://github.com/rahulop11/appumangly/blob/main/lib/screens/smile_camera_screen.dart): Flutter screens · `lib/screens/smile_camera_screen.dart`
- [Emotion detection service](https://github.com/rahulop11/appumangly/blob/main/lib/services/emotion_detection_service.dart): detector abstraction · Bridges Flutter UI to detector implementations. · `lib/services/emotion_detection_service.dart`
- [Python emotion API](https://github.com/rahulop11/appumangly/blob/main/web_emotion_detection/emotion_api.py): local or HTTP detector · Independently runnable OpenCV-oriented detector. · `web_emotion_detection/emotion_api.py`
- [Android WebView integration](https://github.com/rahulop11/appumangly/blob/main/android/app/src/main/kotlin/com/example/umangly/MainActivity.kt): native platform bridge · Handles embedded navigation and permissions. · `android/app/src/main/kotlin/com/example/umangly/MainActivity.kt`

### Mindfulness media

- [Meditation and breathing UI](https://github.com/rahulop11/appumangly/blob/main/lib/screens/meditation_screen.dart): Flutter screens · Meditation, breathing, and affirmation workflows. · `lib/screens/meditation_screen.dart`
- [Audio service](https://github.com/rahulop11/appumangly/blob/main/lib/services/audio_service.dart): media service · `lib/services/audio_service.dart`
- [Freesound API](https://github.com/rahulop11/appumangly/blob/main/lib/services/freesound_api_service.dart): external content service · `lib/services/freesound_api_service.dart`
- [Smile rewards](https://github.com/rahulop11/appumangly/blob/main/lib/services/smile_rewards_service.dart): reward service · `lib/services/smile_rewards_service.dart`

## Connections

- App bootstrap → Feature screens: starts
- Feature screens → Mood and diary views: navigates to
- Feature screens → Companion chat: navigates to
- Feature screens → Camera and webview UI: navigates to
- Feature screens → Meditation and breathing UI: navigates to
- Mood and diary views → Diary data service: persists records
- Mood and diary views → Mood analytics: requests insights
- Diary data service → Mood and diary models: maps records
- Mood analytics → Mood and diary models: aggregates
- Diary data service → Firebase: reads and writes
- Firestore rules → Firebase: authorizes access
- Companion chat → Virtual friend service: sends chat
- Virtual friend service → Gemini / Meera: Meera requests
- Virtual friend service → Dialogflow / Arav: Arav requests
- Virtual friend service → Offline companion: fallback
- Camera and webview UI → Emotion detection service: submits capture
- Camera and webview UI → Android WebView integration: uses embedded detector
- Emotion detection service → Python emotion API: detects emotion
- Meditation and breathing UI → Audio service: plays media
- Audio service → Freesound API: fetches content
- Camera and webview UI → Smile rewards: awards smiles