# guadoesdev/lean-ledger-app architecture

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

- Interactive diagram: https://gitdiagram.com/guadoesdev/lean-ledger-app
- Repository: https://github.com/guadoesdev/lean-ledger-app

## Overview

Lean Ledger is a calorie and nutrition tracker with account-based food logging and an AI meal-chat workflow. Users enter meals manually or describe them (or add a photo) in chat; uncertain AI results prompt clarification, while confident chat results can be saved automatically. The server handles authentication and user-scoped operations, with Supabase as the private data store. README documents additional history, correction, undo, and nutrition-source capabilities; some AI route details were not excerpted, so those links rely on the README rather than unsampled implementation claims.

Main entry points: [`server.js`](https://github.com/guadoesdev/lean-ledger-app/blob/main/server.js) (Express API), [`nutrition.js`](https://github.com/guadoesdev/lean-ledger-app/blob/main/nutrition.js) (Nutrition resolution), [`ai-meals.js`](https://github.com/guadoesdev/lean-ledger-app/blob/main/ai-meals.js) (AI meal workflow), [`gemini.js`](https://github.com/guadoesdev/lean-ledger-app/blob/main/gemini.js) (Meal understanding)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and tracking"]
  node_ui["Web interface<br/>[index.html]"]
  node_api["Express API<br/>[server.js]"]
  node_auth["Account auth<br/>[server.js]"]
  node_profile["Profile and targets<br/>[server.js]"]
  node_foods["Food catalog<br/>[server.js]"]
  node_manual_log["Manual food log<br/>[server.js]"]
  node_weights["Weight tracking<br/>[server.js]"]
end

subgraph group_ai["AI meal logging"]
  node_ai_workflow["AI meal workflow<br/>[ai-meals.js]"]
  node_gemini["Meal understanding<br/>[gemini.js]"]
end

subgraph group_nutrition["Nutrition lookup"]
  node_nutrition_lookup["Nutrition resolution<br/>[nutrition.js]"]
  node_usda["USDA FoodData"]
  node_off["Open Food Facts"]
  node_optional_dbs["Optional databases"]
  node_google_search["Google Search"]
end

subgraph group_data["Persistence"]
  node_data_access["Supabase access<br/>[supabase.js]"]
  node_supabase[("Supabase store")]
end

node_user(("User"))

node_user -->|"enters meals"| node_ui
node_ui -->|"calls endpoints"| node_api
node_api -->|"handles login"| node_auth
node_api -->|"serves profile"| node_profile
node_api -->|"serves foods"| node_foods
node_api -->|"writes log"| node_manual_log
node_api -->|"serves weights"| node_weights
node_api -->|"calls storage"| node_data_access
node_api -->|"mounts routes"| node_ai_workflow
node_ai_workflow -->|"analyzes meals"| node_gemini
node_ai_workflow -->|"resolves nutrition"| node_nutrition_lookup
node_ai_workflow -->|"reads and writes"| node_data_access
node_nutrition_lookup -->|"searches first"| node_usda
node_nutrition_lookup -->|"searches labels"| node_off
node_nutrition_lookup -.->|"searches optionally"| node_optional_dbs
node_gemini -->|"grounds fallback"| node_google_search
node_nutrition_lookup -.->|"uses fallback"| node_google_search
node_nutrition_lookup -.->|"estimates fallback"| node_gemini
node_data_access -->|"queries store"| node_supabase

click node_ui "https://github.com/guadoesdev/lean-ledger-app/blob/main/public/index.html"
click node_api "https://github.com/guadoesdev/lean-ledger-app/blob/main/server.js"
click node_auth "https://github.com/guadoesdev/lean-ledger-app/blob/main/server.js"
click node_profile "https://github.com/guadoesdev/lean-ledger-app/blob/main/server.js"
click node_foods "https://github.com/guadoesdev/lean-ledger-app/blob/main/server.js"
click node_manual_log "https://github.com/guadoesdev/lean-ledger-app/blob/main/server.js"
click node_weights "https://github.com/guadoesdev/lean-ledger-app/blob/main/server.js"
click node_ai_workflow "https://github.com/guadoesdev/lean-ledger-app/blob/main/ai-meals.js"
click node_gemini "https://github.com/guadoesdev/lean-ledger-app/blob/main/gemini.js"
click node_nutrition_lookup "https://github.com/guadoesdev/lean-ledger-app/blob/main/nutrition.js"
click node_data_access "https://github.com/guadoesdev/lean-ledger-app/blob/main/supabase.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_ui,node_api,node_auth,node_profile,node_foods,node_manual_log,node_weights,node_user toneBlue
class node_ai_workflow,node_gemini toneAmber
class node_nutrition_lookup,node_usda,node_off,node_optional_dbs,node_google_search toneMint
class node_data_access,node_supabase toneRose
```

## Components

### App and tracking

- [Web interface](https://github.com/guadoesdev/lean-ledger-app/blob/main/public/index.html): `public/index.html`
- [Express API](https://github.com/guadoesdev/lean-ledger-app/blob/main/server.js): `server.js`
- [Account auth](https://github.com/guadoesdev/lean-ledger-app/blob/main/server.js): `server.js`
- [Profile and targets](https://github.com/guadoesdev/lean-ledger-app/blob/main/server.js): `server.js`
- [Food catalog](https://github.com/guadoesdev/lean-ledger-app/blob/main/server.js): `server.js`
- [Manual food log](https://github.com/guadoesdev/lean-ledger-app/blob/main/server.js): `server.js`
- [Weight tracking](https://github.com/guadoesdev/lean-ledger-app/blob/main/server.js): `server.js`

### AI meal logging

- [AI meal workflow](https://github.com/guadoesdev/lean-ledger-app/blob/main/ai-meals.js): `ai-meals.js`
- [Meal understanding](https://github.com/guadoesdev/lean-ledger-app/blob/main/gemini.js): `gemini.js`

### Nutrition lookup

- [Nutrition resolution](https://github.com/guadoesdev/lean-ledger-app/blob/main/nutrition.js): `nutrition.js`
- **USDA FoodData**
- **Open Food Facts**
- **Optional databases**
- **Google Search**

### Persistence

- [Supabase access](https://github.com/guadoesdev/lean-ledger-app/blob/main/supabase.js): `supabase.js`
- **Supabase store**

### Other components

- **User**

## Connections

- User → Web interface: enters meals (evidence: `README.md`)
- Web interface → Express API: calls endpoints (evidence: `README.md`)
- Express API → Account auth: handles login (evidence: `server.js`)
- Express API → Profile and targets: serves profile (evidence: `server.js`)
- Express API → Food catalog: serves foods (evidence: `server.js`)
- Express API → Manual food log: writes log (evidence: `server.js`)
- Express API → Weight tracking: serves weights (evidence: `server.js`)
- Express API → Supabase access: calls storage (evidence: `server.js`)
- Express API → AI meal workflow: mounts routes (evidence: `server.js`)
- AI meal workflow → Meal understanding: analyzes meals (evidence: `ai-meals.js`)
- AI meal workflow → Nutrition resolution: resolves nutrition (evidence: `ai-meals.js`)
- AI meal workflow → Supabase access: reads and writes (evidence: `ai-meals.js`)
- Nutrition resolution → USDA FoodData: searches first (evidence: `nutrition.js`)
- Nutrition resolution → Open Food Facts: searches labels (evidence: `nutrition.js`)
- Nutrition resolution → Optional databases: searches optionally (evidence: `nutrition.js`)
- Meal understanding → Google Search: grounds fallback (evidence: `gemini.js`)
- Nutrition resolution → Google Search: uses fallback (evidence: `README.md`)
- Nutrition resolution → Meal understanding: estimates fallback (evidence: `README.md`)
- Supabase access → Supabase store: queries store (evidence: `supabase.js`)