# punypeony/healthwatch architecture

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

- Interactive diagram: https://gitdiagram.com/punypeony/healthwatch
- Repository: https://github.com/punypeony/healthwatch

## Overview

This is a caregiver-facing food-consumption health monitor: caregivers register, manage dependents and dietary profiles, scan food, review risk alerts and intake/history, and record grams eaten. The Expo client routes authenticated users through dependent tabs and calls a FastAPI API; the backend resolves food, evaluates risk, persists meal and alert records, and serves summaries. The graph preserves documented capabilities whose implementation was not sampled. Some service-to-service links rely on SOURCE INDEX references or README statements rather than full excerpts.

Main entry points: [`backend/app/routes.py`](https://github.com/punypeony/healthwatch/blob/main/backend/app/routes.py) (API routes), [`backend/app/scan.py`](https://github.com/punypeony/healthwatch/blob/main/backend/app/scan.py) (Scan workflow), [`backend/app/models.py`](https://github.com/punypeony/healthwatch/blob/main/backend/app/models.py) (Domain records), [`mobile/src/api.ts`](https://github.com/punypeony/healthwatch/blob/main/mobile/src/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Mobile client"]
  node_mobileapp["Expo app<br/>[App.tsx]"]
  node_session["Session and auth<br/>[SessionContext.tsx]"]
  node_navigation["App navigation<br/>[RootNavigator.tsx]"]
  node_screens["Care screens"]
  node_api_client["API client<br/>[api.ts]"]
  node_query["Query cache<br/>[queryCache.ts]"]
end

subgraph group_api["API and access"]
  node_routes["API routes<br/>[routes.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_dependents["Dependent management<br/>[dependents.py]"]
end

subgraph group_assessment["Food assessment"]
  node_scan["Scan workflow<br/>[scan.py]"]
  node_food["Food lookup and cache<br/>[food_lookup.py]"]
  node_risk["Risk prediction<br/>[predict.py]"]
  node_targets["Nutrition targets<br/>[targets.py]"]
  node_training["Risk model training"]
end

subgraph group_records["Health records"]
  node_intake["Daily intake<br/>[intake.py]"]
  node_summary["Weekly summary<br/>[summary.py]"]
  node_schema[("Domain records<br/>[models.py]")]
  node_database[("PostgreSQL access<br/>[database.py]")]
end

subgraph group_integrations["External services"]
  node_off["Open Food Facts"]
end

node_caregiver(("Caregiver"))

node_caregiver -->|"uses"| node_mobileapp
node_mobileapp -->|"provides session"| node_session
node_mobileapp -->|"mounts"| node_navigation
node_session -->|"authenticates through"| node_api_client
node_navigation -->|"routes to"| node_screens
node_screens -.->|"requests data"| node_api_client
node_api_client -->|"uses cache"| node_query
node_api_client -->|"calls API"| node_routes
node_routes -->|"delegates auth"| node_auth
node_routes -->|"delegates ownership"| node_dependents
node_routes -->|"invokes scan"| node_scan
node_routes -->|"requests intake"| node_intake
node_routes -->|"requests summary"| node_summary
node_routes -->|"queries records"| node_schema
node_scan -->|"resolves product"| node_food
node_scan -->|"predicts risk"| node_risk
node_scan -.->|"calculates percentages"| node_targets
node_scan -.->|"stores meal and alert"| node_schema
node_food -->|"looks up barcode"| node_off
node_food -->|"caches products"| node_database
node_intake -->|"reads meal logs"| node_schema
node_intake -->|"uses targets"| node_targets
node_summary -->|"reads records"| node_schema
node_schema -->|"maps persistence"| node_database
node_training -.->|"produces model artifact"| node_risk
node_routes -->|"resolves dishes"| node_food

click node_mobileapp "https://github.com/punypeony/healthwatch/blob/main/mobile/App.tsx"
click node_session "https://github.com/punypeony/healthwatch/blob/main/mobile/src/auth/SessionContext.tsx"
click node_navigation "https://github.com/punypeony/healthwatch/blob/main/mobile/src/navigation/RootNavigator.tsx"
click node_screens "https://github.com/punypeony/healthwatch/tree/main/mobile/src/screens"
click node_api_client "https://github.com/punypeony/healthwatch/blob/main/mobile/src/api.ts"
click node_query "https://github.com/punypeony/healthwatch/blob/main/mobile/src/utils/queryCache.ts"
click node_routes "https://github.com/punypeony/healthwatch/blob/main/backend/app/routes.py"
click node_auth "https://github.com/punypeony/healthwatch/blob/main/backend/app/auth.py"
click node_dependents "https://github.com/punypeony/healthwatch/blob/main/backend/app/dependents.py"
click node_scan "https://github.com/punypeony/healthwatch/blob/main/backend/app/scan.py"
click node_food "https://github.com/punypeony/healthwatch/blob/main/backend/app/food_lookup.py"
click node_risk "https://github.com/punypeony/healthwatch/blob/main/backend/app/ml/predict.py"
click node_targets "https://github.com/punypeony/healthwatch/blob/main/backend/app/targets.py"
click node_intake "https://github.com/punypeony/healthwatch/blob/main/backend/app/intake.py"
click node_summary "https://github.com/punypeony/healthwatch/blob/main/backend/app/summary.py"
click node_schema "https://github.com/punypeony/healthwatch/blob/main/backend/app/models.py"
click node_database "https://github.com/punypeony/healthwatch/blob/main/backend/app/database.py"
click node_training "https://github.com/punypeony/healthwatch/blob/main/backend/ml/train_risk_model.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_mobileapp,node_session,node_navigation,node_screens,node_api_client,node_query toneBlue
class node_routes,node_auth,node_dependents toneAmber
class node_scan,node_food,node_risk,node_targets,node_training toneMint
class node_intake,node_summary,node_schema,node_database toneRose
class node_off,node_caregiver toneIndigo
```

## Components

### Mobile client

- [Expo app](https://github.com/punypeony/healthwatch/blob/main/mobile/App.tsx): `mobile/App.tsx`
- [Session and auth](https://github.com/punypeony/healthwatch/blob/main/mobile/src/auth/SessionContext.tsx): `mobile/src/auth/SessionContext.tsx`
- [App navigation](https://github.com/punypeony/healthwatch/blob/main/mobile/src/navigation/RootNavigator.tsx): `mobile/src/navigation/RootNavigator.tsx`
- [Care screens](https://github.com/punypeony/healthwatch/tree/main/mobile/src/screens): `mobile/src/screens`
- [API client](https://github.com/punypeony/healthwatch/blob/main/mobile/src/api.ts): `mobile/src/api.ts`
- [Query cache](https://github.com/punypeony/healthwatch/blob/main/mobile/src/utils/queryCache.ts): `mobile/src/utils/queryCache.ts`

### API and access

- [API routes](https://github.com/punypeony/healthwatch/blob/main/backend/app/routes.py): `backend/app/routes.py`
- [Authentication](https://github.com/punypeony/healthwatch/blob/main/backend/app/auth.py): `backend/app/auth.py`
- [Dependent management](https://github.com/punypeony/healthwatch/blob/main/backend/app/dependents.py): `backend/app/dependents.py`

### Food assessment

- [Scan workflow](https://github.com/punypeony/healthwatch/blob/main/backend/app/scan.py): `backend/app/scan.py`
- [Food lookup and cache](https://github.com/punypeony/healthwatch/blob/main/backend/app/food_lookup.py): `backend/app/food_lookup.py`
- [Risk prediction](https://github.com/punypeony/healthwatch/blob/main/backend/app/ml/predict.py): `backend/app/ml/predict.py`
- [Nutrition targets](https://github.com/punypeony/healthwatch/blob/main/backend/app/targets.py): `backend/app/targets.py`
- [Risk model training](https://github.com/punypeony/healthwatch/blob/main/backend/ml/train_risk_model.py): `backend/ml/train_risk_model.py`

### Health records

- [Daily intake](https://github.com/punypeony/healthwatch/blob/main/backend/app/intake.py): `backend/app/intake.py`
- [Weekly summary](https://github.com/punypeony/healthwatch/blob/main/backend/app/summary.py): `backend/app/summary.py`
- [Domain records](https://github.com/punypeony/healthwatch/blob/main/backend/app/models.py): `backend/app/models.py`
- [PostgreSQL access](https://github.com/punypeony/healthwatch/blob/main/backend/app/database.py): `backend/app/database.py`

### External services

- **Open Food Facts**

### Other components

- **Caregiver**

## Connections

- Caregiver → Expo app: uses (evidence: `README.md`)
- Expo app → Session and auth: provides session (evidence: `mobile/App.tsx`)
- Expo app → App navigation: mounts (evidence: `mobile/App.tsx`)
- Session and auth → API client: authenticates through (evidence: `mobile/src/auth/SessionContext.tsx`)
- App navigation → Care screens: routes to (evidence: `mobile/src/navigation/RootNavigator.tsx`)
- Care screens → API client: requests data
- API client → Query cache: uses cache (evidence: `mobile/src/api.ts`)
- API client → API routes: calls API (evidence: `README.md`)
- API routes → Authentication: delegates auth (evidence: `backend/app/routes.py`)
- API routes → Dependent management: delegates ownership (evidence: `backend/app/routes.py`)
- API routes → Scan workflow: invokes scan (evidence: `backend/app/routes.py`)
- API routes → Daily intake: requests intake (evidence: `backend/app/routes.py`)
- API routes → Weekly summary: requests summary (evidence: `backend/app/routes.py`)
- API routes → Domain records: queries records (evidence: `backend/app/routes.py`)
- Scan workflow → Food lookup and cache: resolves product (evidence: `backend/app/scan.py`)
- Scan workflow → Risk prediction: predicts risk (evidence: `backend/app/scan.py`)
- Scan workflow → Nutrition targets: calculates percentages (evidence: `backend/app/scan.py`)
- Scan workflow → Domain records: stores meal and alert (evidence: `backend/app/scan.py`)
- Food lookup and cache → Open Food Facts: looks up barcode (evidence: `backend/app/food_lookup.py`)
- Food lookup and cache → PostgreSQL access: caches products (evidence: `backend/app/food_lookup.py`)
- Daily intake → Domain records: reads meal logs (evidence: `backend/app/intake.py`)
- Daily intake → Nutrition targets: uses targets (evidence: `backend/app/intake.py`)
- Weekly summary → Domain records: reads records (evidence: `backend/app/summary.py`)
- Domain records → PostgreSQL access: maps persistence (evidence: `backend/app/models.py`)
- Risk model training → Risk prediction: produces model artifact
- API routes → Food lookup and cache: resolves dishes (evidence: `backend/app/routes.py`)
