# dilip-sheesh/anima architecture

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

- Interactive diagram: https://gitdiagram.com/dilip-sheesh/anima
- Repository: https://github.com/dilip-sheesh/anima

## Overview

1. **Repository shape**
   - This is a single Android client app under `frontend/app`, built with Kotlin and Gradle Kotlin DSL.
   - There is no backend service in the repo; the system boundary is the phone app plus external inputs from BLE hardware and Android system health APIs.

2. **App entry and presentation host**
   - `AnimaApplication` is the application-level entry point.
   - `MainActivity` is the UI host, and `presentation/navigation/AnimaNavigation.kt` wires the top-level screen flow.
   - The UI layer is Jetpack Compose + Material 3, with theming isolated in `presentation/theme`.

3. **Screen-level UI structure**
   - The app is organized into feature screens: `dashboard`, `profile`, and `suggestions`.
   - `DashboardScreen` is the main status surface and uses `DashboardViewModel` for state.
   - `ProfileScreen` has its own view model, and `SuggestionsScreen` appears to present recommendations or next actions based on detected stress state.

4. **ViewModel-driven state flow**
   - The UI follows MVVM: screens render state, while ViewModels own derived app state and coordinate data sources.
   - `Statcard.kt` is a reusable dashboard UI component rather than a subsystem boundary.

5. **BLE sensor ingestion**
   - The wearable smart glasses stream physiological data over Bluetooth Low Energy.
   - `data/bluetooth/BluetoothService.kt` is the likely connection/session layer, `BluetoothManager.kt` the orchestration layer, and `BluetoothParser.kt` the decoding layer.
   - This is the primary real-time ingestion path for multi-sensor signals such as PPG, EDA, skin temperature, IMU, and eye-tracking data.

6. **On-device health/context enrichment**
   - `data/digitalwellbeing/HealthConnectManager.kt` integrates with Android Health Connect.
   - It supplies contextual features like sleep, steps, screen time, and app usage, which augment the live sensor stream for stress analysis.

7. **Local persistence**
   - `data/local/AppDatabase.kt`, `SensorDao.kt`, and `SensorEntity.kt` indicate a Room database for storing sensor readings or derived observations.
   - `data/model/SensorData.kt` is the app’s internal data model for sensor payloads/records.
   - This local store likely supports baseline building, historical analysis, and offline continuity.

8. **ML inference boundary**
   - `domain/ml/StressModelExecutor.kt` is the main domain-layer inference wrapper.
   - The readme says inference runs fully on-device with TensorFlow Lite, using a two-stage pipeline: anomaly detection for baseline deviation and a personalization model for user-specific adaptation.
   - This keeps ML logic separate from UI and data transport.

9. **End-to-end data flow**
   - Sensor data enters from BLE, is parsed, optionally persisted locally, combined with Health Connect context, and fed into the stress inference layer.
   - The resulting stress score and related insights are pushed upward to the dashboard and suggestions screens.
   - The app is explicitly designed so no sensor data leaves the device.

10. **System boundaries and external dependencies**
   - External dependencies that materially define the architecture are: the ESP32-based glasses over BLE, Android Health Connect, and on-device TFLite execution.
   - The repo also includes standard Android test scaffolding (`androidTest`, `test`) and resource/config files, but the architectural core is the mobile app’s local sensing, inference, and visualization loop.

Main entry points: [`frontend/app/src/main/java/com/example/anima/domain/ml/StressModelExecutor.kt`](https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/domain/ml/StressModelExecutor.kt) (Stress model), [`frontend/app/src/main/java/com/example/anima/presentation/navigation/AnimaNavigation.kt`](https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/presentation/navigation/AnimaNavigation.kt) (App navigation), [`frontend/app/src/main/java/com/example/anima/presentation/screens/dashboard/DashboardScreen.kt`](https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/presentation/screens/dashboard/DashboardScreen.kt) (Dashboard), [`frontend/app/src/main/java/com/example/anima/presentation/screens/dashboard/DashboardViewModel.kt`](https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/presentation/screens/dashboard/DashboardViewModel.kt) (Dashboard VM)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["App shell"]
  node_node_application(("Anima app<br/>android app"))
  node_node_activity["Main activity<br/>ui host<br/>[MainActivity.kt]"]
end

subgraph group_group_presentation["Presentation"]
  node_node_navigation["App navigation<br/>compose nav<br/>[AnimaNavigation.kt]"]
  node_node_theme["Theme<br/>[Theme.kt]"]
  node_node_dashboard_screen["Dashboard<br/>screen<br/>[DashboardScreen.kt]"]
  node_node_dashboard_vm["Dashboard VM<br/>viewmodel"]
  node_node_statcard["Stat card<br/>ui component<br/>[Statcard.kt]"]
  node_node_profile_screen["Profile<br/>screen<br/>[ProfileScreen.kt]"]
  node_node_profile_vm["Profile VM<br/>viewmodel<br/>[ProfleViewModel.kt]"]
  node_node_suggestions_screen["Suggestions<br/>screen"]
end

subgraph group_group_data["Data"]
  node_node_bluetooth_manager["BLE manager<br/>orchestrator"]
  node_node_bluetooth_service["BLE service<br/>connection layer"]
  node_node_bluetooth_parser["Parser<br/>decoder<br/>[BluetoothParser.kt]"]
  node_node_health_connect["Health Connect<br/>context adapter"]
  node_node_database[("App database<br/>room db<br/>[AppDatabase.kt]")]
  node_node_sensor_dao["Sensor DAO<br/>[SensorDao.kt]"]
  node_node_sensor_entity["Sensor entity<br/>db entity<br/>[SensorEntity.kt]"]
  node_node_sensor_model["Sensor data<br/>model<br/>[SensorData.kt]"]
end

subgraph group_group_domain["Domain"]
  node_node_stress_model{{"Stress model<br/>tflite executor"}}
end

subgraph group_group_external["External systems"]
  node_node_glasses(("Smart glasses<br/>ble device"))
  node_node_android_health(("Android health APIs<br/>platform api"))
  node_node_tflite(("TFLite runtime<br/>ml runtime"))
end

node_node_application -->|"launches"| node_node_activity
node_node_activity -->|"hosts"| node_node_navigation
node_node_navigation -->|"routes to"| node_node_dashboard_screen
node_node_navigation -->|"routes to"| node_node_profile_screen
node_node_navigation -->|"routes to"| node_node_suggestions_screen
node_node_dashboard_screen -->|"observes"| node_node_dashboard_vm
node_node_profile_screen -->|"observes"| node_node_profile_vm
node_node_dashboard_screen -->|"uses"| node_node_statcard
node_node_dashboard_screen -->|"styled by"| node_node_theme
node_node_profile_screen -->|"styled by"| node_node_theme
node_node_suggestions_screen -->|"styled by"| node_node_theme
node_node_bluetooth_manager -->|"coordinates"| node_node_bluetooth_service
node_node_bluetooth_service -->|"feeds"| node_node_bluetooth_parser
node_node_bluetooth_service -->|"connects to"| node_node_glasses
node_node_bluetooth_parser -->|"produces"| node_node_sensor_model
node_node_health_connect -->|"reads from"| node_node_android_health
node_node_sensor_model -->|"persists to"| node_node_database
node_node_database -->|"exposes"| node_node_sensor_dao
node_node_sensor_dao -->|"stores"| node_node_sensor_entity
node_node_sensor_model -->|"analyzed by"| node_node_stress_model
node_node_health_connect -->|"augments"| node_node_stress_model
node_node_stress_model -->|"executes on"| node_node_tflite
node_node_stress_model -->|"publishes"| node_node_dashboard_vm
node_node_stress_model -->|"drives"| node_node_suggestions_screen
node_node_stress_model -->|"personalizes"| node_node_profile_vm
node_node_dashboard_vm -->|"consumes"| node_node_bluetooth_manager
node_node_dashboard_vm -->|"consumes"| node_node_health_connect
node_node_profile_vm -->|"reads/writes"| node_node_database

click node_node_application "https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/AnimaApplication.kt"
click node_node_activity "https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/MainActivity.kt"
click node_node_navigation "https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/presentation/navigation/AnimaNavigation.kt"
click node_node_theme "https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/presentation/theme/Theme.kt"
click node_node_dashboard_screen "https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/presentation/screens/dashboard/DashboardScreen.kt"
click node_node_dashboard_vm "https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/presentation/screens/dashboard/DashboardViewModel.kt"
click node_node_statcard "https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/presentation/screens/dashboard/components/Statcard.kt"
click node_node_profile_screen "https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/presentation/screens/profile/ProfileScreen.kt"
click node_node_profile_vm "https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/presentation/screens/profile/ProfleViewModel.kt"
click node_node_suggestions_screen "https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/presentation/screens/suggestions/SuggestionsScreen.kt"
click node_node_bluetooth_manager "https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/data/bluetooth/BluetoothManager.kt"
click node_node_bluetooth_service "https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/data/bluetooth/BluetoothService.kt"
click node_node_bluetooth_parser "https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/data/bluetooth/BluetoothParser.kt"
click node_node_health_connect "https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/data/digitalwellbeing/HealthConnectManager.kt"
click node_node_database "https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/data/local/AppDatabase.kt"
click node_node_sensor_dao "https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/data/local/SensorDao.kt"
click node_node_sensor_entity "https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/data/local/SensorEntity.kt"
click node_node_sensor_model "https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/data/model/SensorData.kt"
click node_node_stress_model "https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/domain/ml/StressModelExecutor.kt"

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_node_application,node_node_activity toneBlue
class node_node_navigation,node_node_theme,node_node_dashboard_screen,node_node_dashboard_vm,node_node_statcard,node_node_profile_screen,node_node_profile_vm,node_node_suggestions_screen toneAmber
class node_node_bluetooth_manager,node_node_bluetooth_service,node_node_bluetooth_parser,node_node_health_connect,node_node_database,node_node_sensor_dao,node_node_sensor_entity,node_node_sensor_model toneMint
class node_node_stress_model toneRose
class node_node_glasses,node_node_android_health,node_node_tflite toneIndigo
```

## Components

### App shell

Android entrypoints and hosting activity

- [Anima app](https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/AnimaApplication.kt): android app · Application entrypoint for process-wide initialization · `frontend/app/src/main/java/com/example/anima/AnimaApplication.kt`
- [Main activity](https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/MainActivity.kt): ui host · Android activity that hosts the Compose UI · `frontend/app/src/main/java/com/example/anima/MainActivity.kt`

### Presentation

Compose UI, navigation, screens, and theming

- [App navigation](https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/presentation/navigation/AnimaNavigation.kt): compose nav · Top-level screen flow and route wiring · `frontend/app/src/main/java/com/example/anima/presentation/navigation/AnimaNavigation.kt`
- [Theme](https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/presentation/theme/Theme.kt): ui theme · Material 3 styling, colors, and background treatment · `frontend/app/src/main/java/com/example/anima/presentation/theme/Theme.kt`
- [Dashboard](https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/presentation/screens/dashboard/DashboardScreen.kt): screen · Primary status surface for live stress and sensor state · `frontend/app/src/main/java/com/example/anima/presentation/screens/dashboard/DashboardScreen.kt`
- [Dashboard VM](https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/presentation/screens/dashboard/DashboardViewModel.kt): viewmodel · Owns dashboard state and derived presentation data · `frontend/app/src/main/java/com/example/anima/presentation/screens/dashboard/DashboardViewModel.kt`
- [Stat card](https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/presentation/screens/dashboard/components/Statcard.kt): ui component · Reusable dashboard metric component · `frontend/app/src/main/java/com/example/anima/presentation/screens/dashboard/components/Statcard.kt`
- [Profile](https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/presentation/screens/profile/ProfileScreen.kt): screen · User profile and personalization surface · `frontend/app/src/main/java/com/example/anima/presentation/screens/profile/ProfileScreen.kt`
- [Profile VM](https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/presentation/screens/profile/ProfleViewModel.kt): viewmodel · Manages profile state and user-specific inputs · `frontend/app/src/main/java/com/example/anima/presentation/screens/profile/ProfleViewModel.kt`
- [Suggestions](https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/presentation/screens/suggestions/SuggestionsScreen.kt): screen · Recommendations and next actions based on stress state · `frontend/app/src/main/java/com/example/anima/presentation/screens/suggestions/SuggestionsScreen.kt`

### Data

BLE ingestion, Health Connect context, and local persistence

- [BLE manager](https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/data/bluetooth/BluetoothManager.kt): orchestrator · Coordinates Bluetooth session handling and sensor stream flow · `frontend/app/src/main/java/com/example/anima/data/bluetooth/BluetoothManager.kt`
- [BLE service](https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/data/bluetooth/BluetoothService.kt): connection layer · Bluetooth Low Energy connection and data transport layer · `frontend/app/src/main/java/com/example/anima/data/bluetooth/BluetoothService.kt`
- [Parser](https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/data/bluetooth/BluetoothParser.kt): decoder · Decodes raw BLE payloads into structured sensor records · `frontend/app/src/main/java/com/example/anima/data/bluetooth/BluetoothParser.kt`
- [Health Connect](https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/data/digitalwellbeing/HealthConnectManager.kt): context adapter · Reads sleep, steps, screen time, and app usage context · `frontend/app/src/main/java/com/example/anima/data/digitalwellbeing/HealthConnectManager.kt`
- [App database](https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/data/local/AppDatabase.kt): room db · Local Room database for sensor history and derived observations · `frontend/app/src/main/java/com/example/anima/data/local/AppDatabase.kt`
- [Sensor DAO](https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/data/local/SensorDao.kt): dao · Database access for sensor records · `frontend/app/src/main/java/com/example/anima/data/local/SensorDao.kt`
- [Sensor entity](https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/data/local/SensorEntity.kt): db entity · Persisted sensor reading or observation row · `frontend/app/src/main/java/com/example/anima/data/local/SensorEntity.kt`
- [Sensor data](https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/data/model/SensorData.kt): model · Internal sensor payload model used across the app · `frontend/app/src/main/java/com/example/anima/data/model/SensorData.kt`

### Domain

On-device inference and business logic

- [Stress model](https://github.com/dilip-sheesh/anima/blob/master/frontend/app/src/main/java/com/example/anima/domain/ml/StressModelExecutor.kt): tflite executor · On-device stress inference wrapper with anomaly and personalization stages · `frontend/app/src/main/java/com/example/anima/domain/ml/StressModelExecutor.kt`

### External systems

Device and platform dependencies outside the repo

- **Smart glasses**: ble device · ESP32-based wearable sensor source over Bluetooth Low Energy
- **Android health APIs**: platform api · External Android Health Connect capability consumed by the app
- **TFLite runtime**: ml runtime · On-device TensorFlow Lite inference engine

## Connections

- Anima app → Main activity: launches · Application starts the main UI host
- Main activity → App navigation: hosts · Main activity sets up top-level navigation
- App navigation → Dashboard: routes to · Navigation includes the dashboard surface
- App navigation → Profile: routes to · Navigation includes the profile surface
- App navigation → Suggestions: routes to · Navigation includes the suggestions surface
- Dashboard → Dashboard VM: observes · Dashboard renders view model state
- Profile → Profile VM: observes · Profile renders view model state
- Dashboard → Stat card: uses · Dashboard composes reusable stat cards
- Dashboard → Theme: styled by · Compose UI uses shared theme tokens
- Profile → Theme: styled by · Profile UI uses shared theme tokens
- Suggestions → Theme: styled by · Suggestions UI uses shared theme tokens
- BLE manager → BLE service: coordinates · Manager controls connection/session behavior
- BLE service → Parser: feeds · Raw BLE payloads are decoded into sensor data
- BLE service → Smart glasses: connects to · Bluetooth transport connects to wearable glasses
- Parser → Sensor data: produces · Decoded readings become internal sensor records
- Health Connect → Android health APIs: reads from · Health context comes from Android Health Connect
- Sensor data → App database: persists to · Sensor records can be stored locally
- App database → Sensor DAO: exposes · Room database provides DAO access
- Sensor DAO → Sensor entity: stores · DAO reads and writes sensor entities
- Sensor data → Stress model: analyzed by · Sensor stream and context feed inference
- Health Connect → Stress model: augments · Context features enrich stress analysis
- Stress model → TFLite runtime: executes on · Inference runs fully on-device in TensorFlow Lite
- Stress model → Dashboard VM: publishes · Stress outputs flow upward to dashboard state
- Stress model → Suggestions: drives · Stress insights inform recommendations
- Stress model → Profile VM: personalizes · User-specific adaptation can use profile state
- Dashboard VM → BLE manager: consumes · Dashboard state may reflect live sensor ingestion
- Dashboard VM → Health Connect: consumes · Dashboard may include contextual health signals
- Profile VM → App database: reads/writes · Profile state may be stored or retrieved locally
