# openwaterhealth/openlifu-3dscanner architecture

> Architecture diagram of the GitHub repository openwaterhealth/openlifu-3dscanner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openwaterhealth/openlifu-3dscanner
- Repository: https://github.com/openwaterhealth/openlifu-3dscanner

## Overview

OpenLIFU-3DScanner is an Android research-scanning app: users authenticate, identify a subject or session, capture guided photos, upload them for backend reconstruction, and inspect the resulting mesh. The README also documents face and QR analysis, offline scan storage, live progress, and automatic cleanup. The graph combines those documented capabilities with relationships visible in the sampled source; unsampled screen and service wiring is not asserted as verified.

Main entry points: [`OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/navigation/AppNavigation.kt`](https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/navigation/AppNavigation.kt) (App navigation), [`OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/repository/ReconstructionRepository.kt`](https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/repository/ReconstructionRepository.kt) (Reconstruction repository), [`OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/network/api/AuthService.kt`](https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/network/api/AuthService.kt) (Auth service), [`OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/activity/MainActivity.kt`](https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/activity/MainActivity.kt) (Android activity)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and navigation"]
  node_activity["Android activity<br/>[MainActivity.kt]"]
  node_navigation["App navigation<br/>[AppNavigation.kt]"]
  node_login["Authentication UI<br/>[LoginScreen.kt]"]
  node_home["Home dashboard<br/>[HomeScreen.kt]"]
  node_collections["Collection management"]
end

subgraph group_capture["Capture workflow"]
  node_qr["QR scanning<br/>[QrScannerScreen.kt]"]
  node_scanner["Guided scanner<br/>[ScannerScreen.kt]"]
  node_face["Face analysis<br/>[FaceAnalyzer.kt]"]
  node_scanview["Scan details and mesh<br/>[PhotoscanScreen.kt]"]
end

subgraph group_cloud["Cloud and reconstruction"]
  node_auth["Auth service<br/>[AuthService.kt]"]
  node_userrepo["User repository<br/>[UserRepository.kt]"]
  node_cloudrepo["Cloud repository<br/>[CloudRepository.kt]"]
  node_reconstruction["Reconstruction repository"]
  node_collectionapi["Collection API"]
  node_scanapi["Photoscan API"]
  node_websocket["Progress socket"]
  node_service["Foreground service"]
end

subgraph group_local["Local data and operations"]
  node_database[("Room database<br/>[AppDatabase.kt]")]
  node_ownership["Scan ownership records"]
  node_provider["Scan content provider"]
  node_cleanup["Local cleanup worker"]
  node_modelsdir["Local scan files<br/>[getModelsDir.kt]"]
end

node_user(("Scanner user"))
node_backend{{"Reconstruction backend"}}

node_user -->|"opens app"| node_activity
node_activity -->|"hosts routes"| node_navigation
node_navigation -.->|"routes to"| node_login
node_navigation -->|"routes to"| node_home
node_home -.->|"opens collections"| node_collections
node_collections -.->|"identifies session"| node_qr
node_navigation -->|"routes to"| node_scanner
node_scanner -->|"uses framing analysis"| node_face
node_navigation -->|"opens scan details"| node_scanview
node_userrepo -->|"delegates authentication"| node_auth
node_auth -.->|"authenticates remotely"| node_backend
node_auth -->|"stores tokens"| node_backend
node_cloudrepo -->|"delegates uploads"| node_reconstruction
node_reconstruction -->|"creates collections"| node_collectionapi
node_reconstruction -->|"requests scan data"| node_scanapi
node_collectionapi -->|"sends collection and photos"| node_backend
node_scanapi -->|"fetches meshes"| node_backend
node_reconstruction -->|"subscribes to progress"| node_websocket
node_websocket -->|"receives live updates"| node_backend
node_service -->|"observes upload state"| node_reconstruction
node_database -->|"persists records"| node_ownership
node_provider -.->|"exposes scan data"| node_database
node_cleanup -->|"deletes stale files"| node_modelsdir

click node_activity "https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/activity/MainActivity.kt"
click node_navigation "https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/navigation/AppNavigation.kt"
click node_login "https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/screen/signin/LoginScreen.kt"
click node_home "https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/screen/home/HomeScreen.kt"
click node_collections "https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/screen/collection/CollectionsScreen.kt"
click node_qr "https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/screen/qr/QrScannerScreen.kt"
click node_scanner "https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/screen/scanner/ScannerScreen.kt"
click node_face "https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/core/FaceAnalyzer.kt"
click node_scanview "https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/screen/photoscan/PhotoscanScreen.kt"
click node_auth "https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/network/api/AuthService.kt"
click node_userrepo "https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/repository/UserRepository.kt"
click node_cloudrepo "https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/repository/CloudRepository.kt"
click node_reconstruction "https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/repository/ReconstructionRepository.kt"
click node_collectionapi "https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/network/api/PhotocollectionService.kt"
click node_scanapi "https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/network/api/PhotoscanService.kt"
click node_websocket "https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/network/api/WebsocketService.kt"
click node_service "https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/service/ReconstructionService.kt"
click node_database "https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/db/AppDatabase.kt"
click node_ownership "https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/db/ScanOwnershipEntity.kt"
click node_provider "https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/provider/PhotoscanContentProvider.kt"
click node_cleanup "https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/work/LocalScanCleanupWorker.kt"
click node_modelsdir "https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/extensions/getModelsDir.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_activity,node_navigation,node_login,node_home,node_collections,node_user toneBlue
class node_qr,node_scanner,node_face,node_scanview toneAmber
class node_auth,node_userrepo,node_cloudrepo,node_reconstruction,node_collectionapi,node_scanapi,node_websocket,node_service toneMint
class node_database,node_ownership,node_provider,node_cleanup,node_modelsdir toneRose
class node_backend toneIndigo
```

## Components

### App and navigation

- [Android activity](https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/activity/MainActivity.kt): `OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/activity/MainActivity.kt`
- [App navigation](https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/navigation/AppNavigation.kt): `OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/navigation/AppNavigation.kt`
- [Authentication UI](https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/screen/signin/LoginScreen.kt): `OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/screen/signin/LoginScreen.kt`
- [Home dashboard](https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/screen/home/HomeScreen.kt): `OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/screen/home/HomeScreen.kt`
- [Collection management](https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/screen/collection/CollectionsScreen.kt): `OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/screen/collection/CollectionsScreen.kt`

### Capture workflow

- [QR scanning](https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/screen/qr/QrScannerScreen.kt): `OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/screen/qr/QrScannerScreen.kt`
- [Guided scanner](https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/screen/scanner/ScannerScreen.kt): `OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/screen/scanner/ScannerScreen.kt`
- [Face analysis](https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/core/FaceAnalyzer.kt): `OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/core/FaceAnalyzer.kt`
- [Scan details and mesh](https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/screen/photoscan/PhotoscanScreen.kt): `OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/screen/photoscan/PhotoscanScreen.kt`

### Cloud and reconstruction

- [Auth service](https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/network/api/AuthService.kt): `OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/network/api/AuthService.kt`
- [User repository](https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/repository/UserRepository.kt): `OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/repository/UserRepository.kt`
- [Cloud repository](https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/repository/CloudRepository.kt): `OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/repository/CloudRepository.kt`
- [Reconstruction repository](https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/repository/ReconstructionRepository.kt): `OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/repository/ReconstructionRepository.kt`
- [Collection API](https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/network/api/PhotocollectionService.kt): `OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/network/api/PhotocollectionService.kt`
- [Photoscan API](https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/network/api/PhotoscanService.kt): `OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/network/api/PhotoscanService.kt`
- [Progress socket](https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/network/api/WebsocketService.kt): `OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/network/api/WebsocketService.kt`
- [Foreground service](https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/service/ReconstructionService.kt): `OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/service/ReconstructionService.kt`

### Local data and operations

- [Room database](https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/db/AppDatabase.kt): `OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/db/AppDatabase.kt`
- [Scan ownership records](https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/db/ScanOwnershipEntity.kt): `OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/db/ScanOwnershipEntity.kt`
- [Scan content provider](https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/provider/PhotoscanContentProvider.kt): `OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/provider/PhotoscanContentProvider.kt`
- [Local cleanup worker](https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/work/LocalScanCleanupWorker.kt): `OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/work/LocalScanCleanupWorker.kt`
- [Local scan files](https://github.com/openwaterhealth/openlifu-3dscanner/blob/main/OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/extensions/getModelsDir.kt): `OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/extensions/getModelsDir.kt`

### Other components

- **Scanner user**
- **Reconstruction backend**

## Connections

- Scanner user → Android activity: opens app (evidence: `README.md`)
- Android activity → App navigation: hosts routes (evidence: `OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/activity/MainActivity.kt`)
- App navigation → Authentication UI: routes to (evidence: `OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/navigation/AppNavigation.kt`)
- App navigation → Home dashboard: routes to (evidence: `OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/navigation/AppNavigation.kt`)
- Home dashboard → Collection management: opens collections
- Collection management → QR scanning: identifies session
- App navigation → Guided scanner: routes to (evidence: `README.md`)
- Guided scanner → Face analysis: uses framing analysis (evidence: `README.md`)
- App navigation → Scan details and mesh: opens scan details (evidence: `OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/navigation/AppNavigation.kt`)
- User repository → Auth service: delegates authentication (evidence: `OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/repository/UserRepository.kt`)
- Auth service → Reconstruction backend: authenticates remotely
- Auth service → Reconstruction backend: stores tokens (evidence: `OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/network/api/AuthService.kt`)
- Cloud repository → Reconstruction repository: delegates uploads (evidence: `OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/repository/CloudRepository.kt`)
- Reconstruction repository → Collection API: creates collections (evidence: `OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/repository/ReconstructionRepository.kt`)
- Reconstruction repository → Photoscan API: requests scan data (evidence: `OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/repository/ReconstructionRepository.kt`)
- Collection API → Reconstruction backend: sends collection and photos (evidence: `OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/network/api/PhotocollectionService.kt`)
- Photoscan API → Reconstruction backend: fetches meshes (evidence: `OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/network/api/PhotoscanService.kt`)
- Reconstruction repository → Progress socket: subscribes to progress (evidence: `OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/repository/ReconstructionRepository.kt`)
- Progress socket → Reconstruction backend: receives live updates (evidence: `OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/network/api/WebsocketService.kt`)
- Foreground service → Reconstruction repository: observes upload state (evidence: `OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/service/ReconstructionService.kt`)
- Room database → Scan ownership records: persists records (evidence: `OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/db/AppDatabase.kt`)
- Scan content provider → Room database: exposes scan data
- Local cleanup worker → Local scan files: deletes stale files (evidence: `OpenLIFU-3DScanner/app/src/main/java/health/openwater/openlifu3dscanner/work/LocalScanCleanupWorker.kt`)
