# yolalee96/pantrysentry architecture

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

- Interactive diagram: https://gitdiagram.com/yolalee96/pantrysentry
- Repository: https://github.com/yolalee96/pantrysentry

## Overview

PantrySentry is a household food-inventory and waste-reduction app. The principal workflow is managing household stock, then using it for expiry reminders, recipe suggestions and cooking, donations, and environmental-impact tracking. Its Flutter client communicates with an Express API; the API’s domain routes use MySQL and shared authorization and product-matching utilities. Recognition and AI recipes use Gemini. The README content was not provided, so coverage follows the source index and tree; frontend details and unsampled route behavior are represented only at subsystem level.

Main entry points: [`pantrysentry-backend/src/app.js`](https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/app.js) (HTTP routing), [`pantrysentry-backend/src/db.js`](https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/db.js) (MySQL connection), [`pantrysentry-backend/src/routes/recipes.js`](https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/routes/recipes.js) (Recipes and cooking), [`pantrysentry-backend/src/util/household_access.js`](https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/util/household_access.js) (Membership checks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Mobile client"]
  node_frontend["PantrySentry app<br/>[main.dart]"]
end

subgraph group_api["API domains"]
  node_api_entry["API entry<br/>[index.js]"]
  node_app["HTTP routing<br/>[app.js]"]
  node_auth_routes["Accounts and auth<br/>[auth.js]"]
  node_households["Households<br/>[households.js]"]
  node_inventory["Food inventory<br/>[inventory.js]"]
  node_recognition["Food recognition<br/>[recognition.js]"]
  node_shelf_life["Shelf life<br/>[shelf_life.js]"]
  node_reminders["Expiry reminders<br/>[reminders.js]"]
  node_activity["Activity history<br/>[activity.js]"]
  node_recipes["Recipes and cooking<br/>[recipes.js]"]
  node_donations["Food donations<br/>[donations.js]"]
  node_impact["Environmental impact"]
  node_auth_util["Token authorization<br/>[auth.js]"]
  node_household_access["Membership checks"]
end

subgraph group_intelligence["Matching and AI"]
  node_gemini["Gemini integration<br/>[gemini.js]"]
  node_product_reference["Product matching"]
  node_recipe_matching["Recipe matching<br/>[recipe_matching.js]"]
  node_ai_recipes["AI recipe validation<br/>[ai_recipes.js]"]
  node_waste_impact["Waste assessment<br/>[waste_impact.js]"]
  node_factor_matching["Emission factor matching<br/>[factor_matching.js]"]
end

subgraph group_storage["Persistence"]
  node_db_pool["MySQL connection<br/>[db.js]"]
  node_database[("PantrySentry database")]
end

node_user(("Household user"))
node_gemini_service{{"Google Gemini"}}

node_user -->|"uses"| node_frontend
node_frontend -.->|"API requests"| node_api_entry
node_api_entry -->|"loads"| node_app
node_app -->|"mounts public auth"| node_auth_routes
node_app -->|"mounts routes"| node_households
node_app -->|"mounts routes"| node_inventory
node_app -->|"mounts routes"| node_recognition
node_app -->|"mounts routes"| node_shelf_life
node_app -->|"mounts routes"| node_reminders
node_app -->|"mounts routes"| node_activity
node_app -->|"mounts routes"| node_recipes
node_app -->|"mounts routes"| node_donations
node_app -->|"mounts routes"| node_impact
node_app -->|"protects routes"| node_auth_util
node_auth_routes -->|"queries"| node_db_pool
node_auth_routes -->|"signs and verifies tokens"| node_auth_util
node_db_pool -->|"connects to"| node_database
node_households -->|"queries"| node_db_pool
node_inventory -->|"queries"| node_db_pool
node_recognition -->|"queries"| node_db_pool
node_shelf_life -->|"queries"| node_db_pool
node_reminders -->|"queries"| node_db_pool
node_activity -->|"queries"| node_db_pool
node_recipes -->|"queries"| node_db_pool
node_donations -->|"queries"| node_db_pool
node_impact -->|"queries"| node_db_pool
node_households -->|"checks membership"| node_household_access
node_inventory -->|"checks membership"| node_household_access
node_recipes -->|"checks membership"| node_household_access
node_donations -->|"checks membership"| node_household_access
node_impact -->|"checks membership"| node_household_access
node_household_access -->|"checks membership in"| node_db_pool
node_recipes -->|"matches inventory"| node_product_reference
node_recipes -->|"ranks suggestions"| node_recipe_matching
node_recipes -->|"validates AI recipes"| node_ai_recipes
node_recipes -->|"requests suggestions"| node_gemini
node_gemini -->|"calls API"| node_gemini_service
node_recognition -->|"uses generation"| node_gemini
node_recognition -->|"matches products"| node_product_reference
node_ai_recipes -->|"matches products"| node_product_reference
node_inventory -->|"resolves products"| node_product_reference
node_impact -->|"assesses discards"| node_waste_impact
node_waste_impact -->|"resolves references"| node_product_reference
node_waste_impact -->|"matches factors"| node_factor_matching

click node_frontend "https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-frontend/lib/main.dart"
click node_api_entry "https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/api/index.js"
click node_app "https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/app.js"
click node_auth_routes "https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/routes/auth.js"
click node_households "https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/routes/households.js"
click node_inventory "https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/routes/inventory.js"
click node_recognition "https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/routes/recognition.js"
click node_shelf_life "https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/routes/shelf_life.js"
click node_reminders "https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/routes/reminders.js"
click node_activity "https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/routes/activity.js"
click node_recipes "https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/routes/recipes.js"
click node_donations "https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/routes/donations.js"
click node_impact "https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/routes/environmental_impact.js"
click node_gemini "https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/recipe_sources/gemini.js"
click node_product_reference "https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/util/product_reference.js"
click node_recipe_matching "https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/util/recipe_matching.js"
click node_ai_recipes "https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/util/ai_recipes.js"
click node_waste_impact "https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/util/waste_impact.js"
click node_factor_matching "https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/util/factor_matching.js"
click node_auth_util "https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/util/auth.js"
click node_household_access "https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/util/household_access.js"
click node_db_pool "https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/db.js"

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_frontend,node_user toneBlue
class node_api_entry,node_app,node_auth_routes,node_households,node_inventory,node_recognition,node_shelf_life,node_reminders,node_activity,node_recipes,node_donations,node_impact,node_auth_util,node_household_access toneAmber
class node_gemini,node_product_reference,node_recipe_matching,node_ai_recipes,node_waste_impact,node_factor_matching toneMint
class node_db_pool,node_database toneRose
class node_gemini_service toneIndigo
```

## Components

### Mobile client

- [PantrySentry app](https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-frontend/lib/main.dart): `pantrysentry-frontend/lib/main.dart`

### API domains

- [API entry](https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/api/index.js): `pantrysentry-backend/api/index.js`
- [HTTP routing](https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/app.js): `pantrysentry-backend/src/app.js`
- [Accounts and auth](https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/routes/auth.js): `pantrysentry-backend/src/routes/auth.js`
- [Households](https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/routes/households.js): `pantrysentry-backend/src/routes/households.js`
- [Food inventory](https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/routes/inventory.js): `pantrysentry-backend/src/routes/inventory.js`
- [Food recognition](https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/routes/recognition.js): `pantrysentry-backend/src/routes/recognition.js`
- [Shelf life](https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/routes/shelf_life.js): `pantrysentry-backend/src/routes/shelf_life.js`
- [Expiry reminders](https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/routes/reminders.js): `pantrysentry-backend/src/routes/reminders.js`
- [Activity history](https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/routes/activity.js): `pantrysentry-backend/src/routes/activity.js`
- [Recipes and cooking](https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/routes/recipes.js): `pantrysentry-backend/src/routes/recipes.js`
- [Food donations](https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/routes/donations.js): `pantrysentry-backend/src/routes/donations.js`
- [Environmental impact](https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/routes/environmental_impact.js): `pantrysentry-backend/src/routes/environmental_impact.js`
- [Token authorization](https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/util/auth.js): `pantrysentry-backend/src/util/auth.js`
- [Membership checks](https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/util/household_access.js): `pantrysentry-backend/src/util/household_access.js`

### Matching and AI

- [Gemini integration](https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/recipe_sources/gemini.js): `pantrysentry-backend/src/recipe_sources/gemini.js`
- [Product matching](https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/util/product_reference.js): `pantrysentry-backend/src/util/product_reference.js`
- [Recipe matching](https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/util/recipe_matching.js): `pantrysentry-backend/src/util/recipe_matching.js`
- [AI recipe validation](https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/util/ai_recipes.js): `pantrysentry-backend/src/util/ai_recipes.js`
- [Waste assessment](https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/util/waste_impact.js): `pantrysentry-backend/src/util/waste_impact.js`
- [Emission factor matching](https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/util/factor_matching.js): `pantrysentry-backend/src/util/factor_matching.js`

### Persistence

- [MySQL connection](https://github.com/yolalee96/pantrysentry/blob/main/pantrysentry-backend/src/db.js): `pantrysentry-backend/src/db.js`
- **PantrySentry database**

### Other components

- **Household user**
- **Google Gemini**

## Connections

- Household user → PantrySentry app: uses
- PantrySentry app → API entry: API requests
- API entry → HTTP routing: loads (evidence: `pantrysentry-backend/api/index.js`)
- HTTP routing → Accounts and auth: mounts public auth (evidence: `pantrysentry-backend/src/app.js`)
- HTTP routing → Households: mounts routes (evidence: `pantrysentry-backend/src/app.js`)
- HTTP routing → Food inventory: mounts routes (evidence: `pantrysentry-backend/src/app.js`)
- HTTP routing → Food recognition: mounts routes (evidence: `pantrysentry-backend/src/app.js`)
- HTTP routing → Shelf life: mounts routes (evidence: `pantrysentry-backend/src/app.js`)
- HTTP routing → Expiry reminders: mounts routes (evidence: `pantrysentry-backend/src/app.js`)
- HTTP routing → Activity history: mounts routes (evidence: `pantrysentry-backend/src/app.js`)
- HTTP routing → Recipes and cooking: mounts routes (evidence: `pantrysentry-backend/src/app.js`)
- HTTP routing → Food donations: mounts routes (evidence: `pantrysentry-backend/src/app.js`)
- HTTP routing → Environmental impact: mounts routes (evidence: `pantrysentry-backend/src/app.js`)
- HTTP routing → Token authorization: protects routes (evidence: `pantrysentry-backend/src/app.js`)
- Accounts and auth → MySQL connection: queries (evidence: `pantrysentry-backend/src/routes/auth.js`)
- Accounts and auth → Token authorization: signs and verifies tokens (evidence: `pantrysentry-backend/src/routes/auth.js`)
- MySQL connection → PantrySentry database: connects to (evidence: `pantrysentry-backend/src/db.js`)
- Households → MySQL connection: queries (evidence: `pantrysentry-backend/src/routes/households.js`)
- Food inventory → MySQL connection: queries (evidence: `pantrysentry-backend/src/routes/inventory.js`)
- Food recognition → MySQL connection: queries (evidence: `pantrysentry-backend/src/routes/recognition.js`)
- Shelf life → MySQL connection: queries (evidence: `pantrysentry-backend/src/routes/shelf_life.js`)
- Expiry reminders → MySQL connection: queries (evidence: `pantrysentry-backend/src/routes/reminders.js`)
- Activity history → MySQL connection: queries (evidence: `pantrysentry-backend/src/routes/activity.js`)
- Recipes and cooking → MySQL connection: queries (evidence: `pantrysentry-backend/src/routes/recipes.js`)
- Food donations → MySQL connection: queries (evidence: `pantrysentry-backend/src/routes/donations.js`)
- Environmental impact → MySQL connection: queries (evidence: `pantrysentry-backend/src/routes/environmental_impact.js`)
- Households → Membership checks: checks membership (evidence: `pantrysentry-backend/src/routes/households.js`)
- Food inventory → Membership checks: checks membership (evidence: `pantrysentry-backend/src/routes/inventory.js`)
- Recipes and cooking → Membership checks: checks membership (evidence: `pantrysentry-backend/src/routes/recipes.js`)
- Food donations → Membership checks: checks membership (evidence: `pantrysentry-backend/src/routes/donations.js`)
- Environmental impact → Membership checks: checks membership (evidence: `pantrysentry-backend/src/routes/environmental_impact.js`)
- Membership checks → MySQL connection: checks membership in (evidence: `pantrysentry-backend/src/util/household_access.js`)
- Recipes and cooking → Product matching: matches inventory (evidence: `pantrysentry-backend/src/routes/recipes.js`)
- Recipes and cooking → Recipe matching: ranks suggestions (evidence: `pantrysentry-backend/src/routes/recipes.js`)
- Recipes and cooking → AI recipe validation: validates AI recipes (evidence: `pantrysentry-backend/src/routes/recipes.js`)
- Recipes and cooking → Gemini integration: requests suggestions (evidence: `pantrysentry-backend/src/routes/recipes.js`)
- Gemini integration → Google Gemini: calls API (evidence: `pantrysentry-backend/src/recipe_sources/gemini.js`)
- Food recognition → Gemini integration: uses generation (evidence: `pantrysentry-backend/src/routes/recognition.js`)
- Food recognition → Product matching: matches products (evidence: `pantrysentry-backend/src/routes/recognition.js`)
- AI recipe validation → Product matching: matches products (evidence: `pantrysentry-backend/src/util/ai_recipes.js`)
- Food inventory → Product matching: resolves products (evidence: `pantrysentry-backend/src/routes/inventory.js`)
- Environmental impact → Waste assessment: assesses discards (evidence: `pantrysentry-backend/src/routes/environmental_impact.js`)
- Waste assessment → Product matching: resolves references (evidence: `pantrysentry-backend/src/util/waste_impact.js`)
- Waste assessment → Emission factor matching: matches factors (evidence: `pantrysentry-backend/src/util/waste_impact.js`)
