# utsapoddar/pcos-scanner architecture

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

- Interactive diagram: https://gitdiagram.com/utsapoddar/pcos-scanner
- Repository: https://github.com/utsapoddar/pcos-scanner
- Video tour (about a minute): https://gitdiagram.com/utsapoddar/pcos-scanner/video

## Overview

PCOS Food Scanner is a Streamlit prototype for turning packaged-food scans or meal photos into deterministic nutrition scores and profile-aware guidance, with saved foods and PCOS profile management. The app coordinates both scan routes and meal estimation, then applies scoring and optional personalization. Supabase stores profiles, saved foods, and cached guidance; startup also runs SQL migrations. The graph reflects the documented capabilities and sampled call sites; some UI implementation is excerpted, so uncertain wiring is omitted.

Main entry points: [`app.py`](https://github.com/utsapoddar/pcos-scanner/blob/main/app.py) (Streamlit app), [`core/personalize.py`](https://github.com/utsapoddar/pcos-scanner/blob/main/core/personalize.py) (Score personalization), [`core/db.py`](https://github.com/utsapoddar/pcos-scanner/blob/main/core/db.py) (Supabase data access), [`core/food_photo.py`](https://github.com/utsapoddar/pcos-scanner/blob/main/core/food_photo.py) (Meal photo estimator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["App and inputs"]
  node_app["Streamlit app<br/>[app.py]"]
  node_barcode["Barcode decoder<br/>[barcode.py]"]
  node_labelvision["Label extraction<br/>[vision.py]"]
  node_mealphoto["Meal photo estimator<br/>[food_photo.py]"]
end

subgraph group_analysis["Nutrition analysis"]
  node_mealaggregate["Meal aggregation<br/>[food_photo.py]"]
  node_scoring["Rule-based scoring<br/>[scoring.py]"]
end

subgraph group_guidance["Profile guidance"]
  node_personalize["Score personalization<br/>[personalize.py]"]
  node_guidelines["PCOS guidelines<br/>[pcos_guidelines.md]"]
  node_profile["PCOS profile model<br/>[profile.py]"]
end

subgraph group_persistence["Data persistence"]
  node_db["Supabase data access<br/>[db.py]"]
  node_supabase[("Supabase database")]
  node_migrationrunner["Startup migrations<br/>[migrations.py]"]
  node_migrations["SQL migrations"]
end

node_user(("Scanner user"))
node_off["Open Food Facts"]
node_usda["USDA FoodData Central"]
node_nvidia["NVIDIA model API"]

node_user -->|"uses"| node_app
node_app -.->|"decodes image"| node_barcode
node_app -->|"fetches barcode product"| node_off
node_app -->|"extracts label"| node_labelvision
node_app -->|"estimates meal"| node_mealphoto
node_mealphoto -->|"identifies foods"| node_nvidia
node_mealphoto -->|"looks up nutrients"| node_usda
node_app -->|"aggregates portions"| node_mealaggregate
node_app -->|"scores nutrients"| node_scoring
node_app -->|"requests guidance"| node_personalize
node_personalize -->|"personalizes score"| node_nvidia
node_personalize -->|"references guidance"| node_guidelines
node_personalize -->|"reads or caches"| node_db
node_db -->|"converts profile"| node_profile
node_app -->|"loads and saves"| node_db
node_db -->|"reads and writes"| node_supabase
node_app -->|"runs at startup"| node_migrationrunner
node_migrationrunner -->|"loads SQL"| node_migrations
node_migrationrunner -->|"applies schema"| node_supabase

click node_app "https://github.com/utsapoddar/pcos-scanner/blob/main/app.py"
click node_barcode "https://github.com/utsapoddar/pcos-scanner/blob/main/core/barcode.py"
click node_labelvision "https://github.com/utsapoddar/pcos-scanner/blob/main/core/vision.py"
click node_mealphoto "https://github.com/utsapoddar/pcos-scanner/blob/main/core/food_photo.py"
click node_mealaggregate "https://github.com/utsapoddar/pcos-scanner/blob/main/core/food_photo.py"
click node_scoring "https://github.com/utsapoddar/pcos-scanner/blob/main/core/scoring.py"
click node_personalize "https://github.com/utsapoddar/pcos-scanner/blob/main/core/personalize.py"
click node_guidelines "https://github.com/utsapoddar/pcos-scanner/blob/main/knowledge/pcos_guidelines.md"
click node_profile "https://github.com/utsapoddar/pcos-scanner/blob/main/core/profile.py"
click node_db "https://github.com/utsapoddar/pcos-scanner/blob/main/core/db.py"
click node_migrationrunner "https://github.com/utsapoddar/pcos-scanner/blob/main/core/migrations.py"
click node_migrations "https://github.com/utsapoddar/pcos-scanner/tree/main/migrations"

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_barcode,node_labelvision,node_mealphoto,node_user toneBlue
class node_mealaggregate,node_scoring toneAmber
class node_personalize,node_guidelines,node_profile,node_nvidia toneMint
class node_db,node_supabase,node_migrationrunner,node_migrations toneRose
class node_off,node_usda toneIndigo
```

## Components

### App and inputs

- [Streamlit app](https://github.com/utsapoddar/pcos-scanner/blob/main/app.py): `app.py`
- [Barcode decoder](https://github.com/utsapoddar/pcos-scanner/blob/main/core/barcode.py): `core/barcode.py`
- [Label extraction](https://github.com/utsapoddar/pcos-scanner/blob/main/core/vision.py): `core/vision.py`
- [Meal photo estimator](https://github.com/utsapoddar/pcos-scanner/blob/main/core/food_photo.py): `core/food_photo.py`

### Nutrition analysis

- [Meal aggregation](https://github.com/utsapoddar/pcos-scanner/blob/main/core/food_photo.py): `core/food_photo.py`
- [Rule-based scoring](https://github.com/utsapoddar/pcos-scanner/blob/main/core/scoring.py): `core/scoring.py`

### Profile guidance

- [Score personalization](https://github.com/utsapoddar/pcos-scanner/blob/main/core/personalize.py): `core/personalize.py`
- [PCOS guidelines](https://github.com/utsapoddar/pcos-scanner/blob/main/knowledge/pcos_guidelines.md): `knowledge/pcos_guidelines.md`
- [PCOS profile model](https://github.com/utsapoddar/pcos-scanner/blob/main/core/profile.py): `core/profile.py`

### Data persistence

- [Supabase data access](https://github.com/utsapoddar/pcos-scanner/blob/main/core/db.py): `core/db.py`
- **Supabase database**
- [Startup migrations](https://github.com/utsapoddar/pcos-scanner/blob/main/core/migrations.py): `core/migrations.py`
- [SQL migrations](https://github.com/utsapoddar/pcos-scanner/tree/main/migrations): `migrations`

### Other components

- **Scanner user**
- **Open Food Facts**
- **USDA FoodData Central**
- **NVIDIA model API**

## Connections

- Scanner user → Streamlit app: uses
- Streamlit app → Barcode decoder: decodes image
- Streamlit app → Open Food Facts: fetches barcode product
- Streamlit app → Label extraction: extracts label
- Streamlit app → Meal photo estimator: estimates meal
- Meal photo estimator → NVIDIA model API: identifies foods
- Meal photo estimator → USDA FoodData Central: looks up nutrients
- Streamlit app → Meal aggregation: aggregates portions
- Streamlit app → Rule-based scoring: scores nutrients
- Streamlit app → Score personalization: requests guidance
- Score personalization → NVIDIA model API: personalizes score
- Score personalization → PCOS guidelines: references guidance
- Score personalization → Supabase data access: reads or caches
- Supabase data access → PCOS profile model: converts profile
- Streamlit app → Supabase data access: loads and saves
- Supabase data access → Supabase database: reads and writes
- Streamlit app → Startup migrations: runs at startup
- Startup migrations → SQL migrations: loads SQL
- Startup migrations → Supabase database: applies schema