# zackultima/ally architecture

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

- Interactive diagram: https://gitdiagram.com/zackultima/ally
- Repository: https://github.com/zackultima/ally

## Overview

Ally is presented as an Android companion and safety monitor, with local fall detection, consent-based expression tracking, conversation, and guardian escalation. The supplied tree primarily exposes Kotlin domain logic and Python model/data workflows rather than a complete Android integration, so the graph separates those branches. Fall-detection training and live inference are represented distinctly; companion and emotion tooling are data/model preparation components. Some product capabilities are documented but their runtime implementation is not present in the supplied tree.

Main entry points: [`app/fall/flow/src/main/kotlin/ally/fall/flow/FallFlow.kt`](https://github.com/zackultima/ally/blob/main/app/fall/flow/src/main/kotlin/ally/fall/flow/FallFlow.kt) (Fall response), [`app/emotion/levels/src/main/kotlin/ally/emotion/levels/LevelRules.kt`](https://github.com/zackultima/ally/blob/main/app/emotion/levels/src/main/kotlin/ally/emotion/levels/LevelRules.kt) (Mood check-ins), [`ml/fall/src/ally_fall/live/pipeline.py`](https://github.com/zackultima/ally/blob/main/ml/fall/src/ally_fall/live/pipeline.py) (Live fall pipeline), [`ml/fall/src/ally_fall/data.py`](https://github.com/zackultima/ally/blob/main/ml/fall/src/ally_fall/data.py) (Window data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_android["Android domain logic"]
  node_fall_flow["Fall response<br/>[FallFlow.kt]"]
  node_fall_state["Fall state<br/>[FlowState.kt]"]
  node_fall_screen["Fall screen<br/>[Screen.kt]"]
  node_call_rota["Guardian rota<br/>[CallRota.kt]"]
  node_emotion_rules["Mood check-ins<br/>[LevelRules.kt]"]
  node_expression["Expression readings<br/>[Expression.kt]"]
  node_mood_log[("Mood log<br/>[MoodLog.kt]")]
  node_phrase_check["Phrase checking<br/>[PhraseChecker.kt]"]
end

subgraph group_fallml["Fall detection"]
  node_live_app["Live monitor app<br/>[app.py]"]
  node_live_pipeline["Live fall pipeline<br/>[pipeline.py]"]
  node_keypoints["Pose keypoints<br/>[keypoints.py]"]
  node_live_alert["Alert rule<br/>[alert.py]"]
  node_omnifall["Labels and splits<br/>[omnifall.py]"]
  node_dataset_adapters["Dataset adapters"]
  node_fall_data["Window data<br/>[data.py]"]
  node_fall_model["Fall models<br/>[models.py]"]
  node_fall_train["Model training<br/>[train.py]"]
  node_fall_export["INT8 export<br/>[export.py]"]
end

subgraph group_companion["Companion data"]
  node_dialogue["Dialogue records<br/>[dialogue.py]"]
  node_room_note["Room context<br/>[roomnote.py]"]
  node_heldout["Held-out filter<br/>[heldout.py]"]
  node_companion_loaders["Dialogue loaders<br/>[loaders.py]"]
end

subgraph group_emotionml["Emotion data"]
  node_emotion_sources["Emotion datasets<br/>[utkface.py]"]
  node_emotion_convert["Dataset conversion<br/>[convert_check.py]"]
end

node_older_adult(("Older adult"))
node_guardian(("Guardian"))
node_companion_runtime["Companion conversation"]
node_object_recognition["Object recognition"]

node_older_adult -.->|"provides events"| node_fall_flow
node_fall_flow -->|"updates state"| node_fall_state
node_fall_screen -->|"reads state"| node_fall_state
node_fall_flow -->|"uses rota"| node_call_rota
node_fall_flow -.->|"notifies"| node_guardian
node_older_adult -.->|"provides replies"| node_emotion_rules
node_emotion_rules -->|"records readings"| node_expression
node_emotion_rules -.->|"stores mood data"| node_mood_log
node_older_adult -.->|"provides phrases"| node_phrase_check
node_live_app -->|"uses pipeline"| node_live_pipeline
node_live_pipeline -->|"uses points"| node_keypoints
node_live_pipeline -->|"updates alert"| node_live_alert
node_omnifall -->|"provides identities"| node_dataset_adapters
node_fall_data -.->|"uses labels"| node_omnifall
node_fall_data -->|"uses datasets"| node_dataset_adapters
node_fall_train -->|"loads windows"| node_fall_data
node_fall_train -->|"trains model"| node_fall_model
node_fall_export -->|"exports model"| node_fall_model
node_dialogue -->|"encodes context"| node_room_note
node_companion_loaders -->|"loads records"| node_dialogue
node_companion_loaders -.->|"filters training"| node_heldout
node_companion_runtime -.->|"trained from"| node_dialogue
node_emotion_sources -.->|"prepares data"| node_emotion_convert
node_older_adult -.->|"talks with"| node_companion_runtime
node_older_adult -.->|"provides view"| node_object_recognition

click node_fall_flow "https://github.com/zackultima/ally/blob/main/app/fall/flow/src/main/kotlin/ally/fall/flow/FallFlow.kt"
click node_fall_state "https://github.com/zackultima/ally/blob/main/app/fall/flow/src/main/kotlin/ally/fall/flow/FlowState.kt"
click node_fall_screen "https://github.com/zackultima/ally/blob/main/app/fall/flow/src/main/kotlin/ally/fall/flow/Screen.kt"
click node_call_rota "https://github.com/zackultima/ally/blob/main/app/fall/flow/src/main/kotlin/ally/fall/flow/CallRota.kt"
click node_emotion_rules "https://github.com/zackultima/ally/blob/main/app/emotion/levels/src/main/kotlin/ally/emotion/levels/LevelRules.kt"
click node_expression "https://github.com/zackultima/ally/blob/main/app/emotion/levels/src/main/kotlin/ally/emotion/levels/Expression.kt"
click node_mood_log "https://github.com/zackultima/ally/blob/main/app/emotion/levels/src/main/kotlin/ally/emotion/levels/MoodLog.kt"
click node_phrase_check "https://github.com/zackultima/ally/blob/main/app/speech/phrases/src/main/kotlin/ally/speech/phrases/PhraseChecker.kt"
click node_live_app "https://github.com/zackultima/ally/blob/main/ml/fall/src/ally_fall/live/app.py"
click node_live_pipeline "https://github.com/zackultima/ally/blob/main/ml/fall/src/ally_fall/live/pipeline.py"
click node_keypoints "https://github.com/zackultima/ally/blob/main/ml/fall/src/ally_fall/keypoints.py"
click node_live_alert "https://github.com/zackultima/ally/blob/main/ml/fall/src/ally_fall/live/alert.py"
click node_omnifall "https://github.com/zackultima/ally/blob/main/ml/fall/src/ally_fall/omnifall.py"
click node_dataset_adapters "https://github.com/zackultima/ally/tree/main/ml/fall/src/ally_fall/datasets"
click node_fall_data "https://github.com/zackultima/ally/blob/main/ml/fall/src/ally_fall/data.py"
click node_fall_model "https://github.com/zackultima/ally/blob/main/ml/fall/src/ally_fall/models.py"
click node_fall_train "https://github.com/zackultima/ally/blob/main/ml/fall/src/ally_fall/train.py"
click node_fall_export "https://github.com/zackultima/ally/blob/main/ml/fall/src/ally_fall/export.py"
click node_dialogue "https://github.com/zackultima/ally/blob/main/ml/companion/src/ally_companion/dialogue.py"
click node_room_note "https://github.com/zackultima/ally/blob/main/ml/companion/src/ally_companion/roomnote.py"
click node_heldout "https://github.com/zackultima/ally/blob/main/ml/companion/src/ally_companion/heldout.py"
click node_companion_loaders "https://github.com/zackultima/ally/blob/main/ml/companion/src/ally_companion/loaders.py"
click node_emotion_sources "https://github.com/zackultima/ally/blob/main/ml/emotion/src/ally_emotion/utkface.py"
click node_emotion_convert "https://github.com/zackultima/ally/blob/main/ml/emotion/src/ally_emotion/convert_check.py"

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_fall_flow,node_fall_state,node_fall_screen,node_call_rota,node_emotion_rules,node_expression,node_mood_log,node_phrase_check toneBlue
class node_live_app,node_live_pipeline,node_keypoints,node_live_alert,node_omnifall,node_dataset_adapters,node_fall_data,node_fall_model,node_fall_train,node_fall_export toneAmber
class node_dialogue,node_room_note,node_heldout,node_companion_loaders toneMint
class node_emotion_sources,node_emotion_convert toneRose
class node_older_adult,node_guardian,node_companion_runtime,node_object_recognition toneIndigo
```

## Components

### Android domain logic

- [Fall response](https://github.com/zackultima/ally/blob/main/app/fall/flow/src/main/kotlin/ally/fall/flow/FallFlow.kt): `app/fall/flow/src/main/kotlin/ally/fall/flow/FallFlow.kt`
- [Fall state](https://github.com/zackultima/ally/blob/main/app/fall/flow/src/main/kotlin/ally/fall/flow/FlowState.kt): `app/fall/flow/src/main/kotlin/ally/fall/flow/FlowState.kt`
- [Fall screen](https://github.com/zackultima/ally/blob/main/app/fall/flow/src/main/kotlin/ally/fall/flow/Screen.kt): `app/fall/flow/src/main/kotlin/ally/fall/flow/Screen.kt`
- [Guardian rota](https://github.com/zackultima/ally/blob/main/app/fall/flow/src/main/kotlin/ally/fall/flow/CallRota.kt): `app/fall/flow/src/main/kotlin/ally/fall/flow/CallRota.kt`
- [Mood check-ins](https://github.com/zackultima/ally/blob/main/app/emotion/levels/src/main/kotlin/ally/emotion/levels/LevelRules.kt): `app/emotion/levels/src/main/kotlin/ally/emotion/levels/LevelRules.kt`
- [Expression readings](https://github.com/zackultima/ally/blob/main/app/emotion/levels/src/main/kotlin/ally/emotion/levels/Expression.kt): `app/emotion/levels/src/main/kotlin/ally/emotion/levels/Expression.kt`
- [Mood log](https://github.com/zackultima/ally/blob/main/app/emotion/levels/src/main/kotlin/ally/emotion/levels/MoodLog.kt): `app/emotion/levels/src/main/kotlin/ally/emotion/levels/MoodLog.kt`
- [Phrase checking](https://github.com/zackultima/ally/blob/main/app/speech/phrases/src/main/kotlin/ally/speech/phrases/PhraseChecker.kt): `app/speech/phrases/src/main/kotlin/ally/speech/phrases/PhraseChecker.kt`

### Fall detection

- [Live monitor app](https://github.com/zackultima/ally/blob/main/ml/fall/src/ally_fall/live/app.py): `ml/fall/src/ally_fall/live/app.py`
- [Live fall pipeline](https://github.com/zackultima/ally/blob/main/ml/fall/src/ally_fall/live/pipeline.py): `ml/fall/src/ally_fall/live/pipeline.py`
- [Pose keypoints](https://github.com/zackultima/ally/blob/main/ml/fall/src/ally_fall/keypoints.py): `ml/fall/src/ally_fall/keypoints.py`
- [Alert rule](https://github.com/zackultima/ally/blob/main/ml/fall/src/ally_fall/live/alert.py): `ml/fall/src/ally_fall/live/alert.py`
- [Labels and splits](https://github.com/zackultima/ally/blob/main/ml/fall/src/ally_fall/omnifall.py): `ml/fall/src/ally_fall/omnifall.py`
- [Dataset adapters](https://github.com/zackultima/ally/tree/main/ml/fall/src/ally_fall/datasets): `ml/fall/src/ally_fall/datasets`
- [Window data](https://github.com/zackultima/ally/blob/main/ml/fall/src/ally_fall/data.py): `ml/fall/src/ally_fall/data.py`
- [Fall models](https://github.com/zackultima/ally/blob/main/ml/fall/src/ally_fall/models.py): `ml/fall/src/ally_fall/models.py`
- [Model training](https://github.com/zackultima/ally/blob/main/ml/fall/src/ally_fall/train.py): `ml/fall/src/ally_fall/train.py`
- [INT8 export](https://github.com/zackultima/ally/blob/main/ml/fall/src/ally_fall/export.py): `ml/fall/src/ally_fall/export.py`

### Companion data

- [Dialogue records](https://github.com/zackultima/ally/blob/main/ml/companion/src/ally_companion/dialogue.py): `ml/companion/src/ally_companion/dialogue.py`
- [Room context](https://github.com/zackultima/ally/blob/main/ml/companion/src/ally_companion/roomnote.py): `ml/companion/src/ally_companion/roomnote.py`
- [Held-out filter](https://github.com/zackultima/ally/blob/main/ml/companion/src/ally_companion/heldout.py): `ml/companion/src/ally_companion/heldout.py`
- [Dialogue loaders](https://github.com/zackultima/ally/blob/main/ml/companion/src/ally_companion/loaders.py): `ml/companion/src/ally_companion/loaders.py`

### Emotion data

- [Emotion datasets](https://github.com/zackultima/ally/blob/main/ml/emotion/src/ally_emotion/utkface.py): `ml/emotion/src/ally_emotion/utkface.py`
- [Dataset conversion](https://github.com/zackultima/ally/blob/main/ml/emotion/src/ally_emotion/convert_check.py): `ml/emotion/src/ally_emotion/convert_check.py`

### Other components

- **Older adult**
- **Guardian**
- **Companion conversation**
- **Object recognition**

## Connections

- Older adult → Fall response: provides events
- Fall response → Fall state: updates state (evidence: `app/fall/flow/src/main/kotlin/ally/fall/flow/FallFlow.kt`)
- Fall screen → Fall state: reads state (evidence: `app/fall/flow/src/main/kotlin/ally/fall/flow/Screen.kt`)
- Fall response → Guardian rota: uses rota (evidence: `app/fall/flow/src/main/kotlin/ally/fall/flow/FallFlow.kt`)
- Fall response → Guardian: notifies
- Older adult → Mood check-ins: provides replies
- Mood check-ins → Expression readings: records readings (evidence: `app/emotion/levels/src/main/kotlin/ally/emotion/levels/LevelRules.kt`)
- Mood check-ins → Mood log: stores mood data
- Older adult → Phrase checking: provides phrases
- Live monitor app → Live fall pipeline: uses pipeline (evidence: `ml/fall/src/ally_fall/live/app.py`)
- Live fall pipeline → Pose keypoints: uses points (evidence: `ml/fall/src/ally_fall/live/pipeline.py`)
- Live fall pipeline → Alert rule: updates alert (evidence: `ml/fall/src/ally_fall/live/pipeline.py`)
- Labels and splits → Dataset adapters: provides identities (evidence: `ml/fall/src/ally_fall/datasets/up_fall.py`)
- Window data → Labels and splits: uses labels
- Window data → Dataset adapters: uses datasets (evidence: `ml/fall/src/ally_fall/data.py`)
- Model training → Window data: loads windows (evidence: `ml/fall/src/ally_fall/train.py`)
- Model training → Fall models: trains model (evidence: `ml/fall/src/ally_fall/train.py`)
- INT8 export → Fall models: exports model (evidence: `ml/fall/src/ally_fall/export.py`)
- Dialogue records → Room context: encodes context (evidence: `ml/companion/src/ally_companion/dialogue.py`)
- Dialogue loaders → Dialogue records: loads records (evidence: `ml/companion/src/ally_companion/loaders.py`)
- Dialogue loaders → Held-out filter: filters training
- Companion conversation → Dialogue records: trained from
- Emotion datasets → Dataset conversion: prepares data
- Older adult → Companion conversation: talks with (evidence: `README.md`)
- Older adult → Object recognition: provides view (evidence: `README.md`)
