# kingpinlab/optimeal architecture

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

- Interactive diagram: https://gitdiagram.com/kingpinlab/optimeal
- Repository: https://github.com/kingpinlab/optimeal

## Overview

OptiMeal is a nutrition and wellness tracking app: users scan meals for AI-assisted nutrition estimates, review and confirm meals, and track daily health data, goals, progress, and coaching. The Next.js app combines a client UI and API routes, with Prisma-backed persistence. The documented meal flow runs from image scan and preview to explicit meal confirmation; scanning itself does not save. Several UI routes and integrations were not sampled, so their internal wiring is omitted where not evidenced.

Main entry points: [`src/hooks/useApi.ts`](https://github.com/kingpinlab/optimeal/blob/main/src/hooks/useApi.ts) (API query hooks), [`src/lib/prisma.ts`](https://github.com/kingpinlab/optimeal/blob/main/src/lib/prisma.ts) (Application database), [`src/app/api/scan/route.ts`](https://github.com/kingpinlab/optimeal/blob/main/src/app/api/scan/route.ts) (Meal scan API), [`src/app/api/meals/route.ts`](https://github.com/kingpinlab/optimeal/blob/main/src/app/api/meals/route.ts) (Meal records API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client experience"]
  node_home["Home screen<br/>[HomeScreen.tsx]"]
  node_scanui["Scan screen<br/>[ScanScreen.tsx]"]
  node_coachui["Coach screen<br/>[CoachScreen.tsx]"]
  node_profileui["Profile screen<br/>[ProfileScreen.tsx]"]
  node_calendarui["Calendar screen<br/>[CalendarScreen.tsx]"]
  node_api_hooks["API query hooks<br/>[useApi.ts]"]
  node_client_api["API client<br/>[api.ts]"]
  node_ui_primitives["UI primitives<br/>[primitives.tsx]"]
end

subgraph group_nutrition["Meal nutrition"]
  node_scan_route["Meal scan API<br/>[route.ts]"]
  node_vision["Food detection<br/>[vision.ts]"]
  node_nutrition_calc["Nutrition optimizer<br/>[nutrition.ts]"]
  node_food_lookup["Food macro lookup<br/>[food-database.ts]"]
  node_meal_routes["Meal records API<br/>[route.ts]"]
  node_meal_item["Meal item API<br/>[route.ts]"]
end

subgraph group_tracking["Health tracking"]
  node_tracking_routes["Health log APIs"]
end

subgraph group_insights["Guidance and insights"]
  node_stats_route["Progress stats API<br/>[route.ts]"]
  node_achievements["Achievement rules<br/>[achievements.ts]"]
  node_coach_route["Coach chat API<br/>[route.ts]"]
  node_coach_logic["Coach responses<br/>[coach.ts]"]
  node_report_route["PDF report API<br/>[route.ts]"]
  node_report_doc["Report document<br/>[ReportDocument.tsx]"]
end

subgraph group_platform["Identity and platform"]
  node_auth_api["Authentication routes"]
  node_auth_logic["Token and user auth<br/>[auth.ts]"]
  node_store["App state<br/>[useStore.ts]"]
  node_prisma[("Application database<br/>[prisma.ts]")]
  node_cloudinary["Image storage<br/>[cloudinary.ts]"]
end

node_person(("App user"))
node_gemini{{"Gemini model"}}
node_usda{{"USDA FoodData"}}

node_person -->|"captures photo"| node_scanui
node_scanui -->|"starts scan"| node_api_hooks
node_api_hooks -->|"fetches API"| node_client_api
node_client_api -->|"posts image"| node_scan_route
node_scan_route -->|"uploads image"| node_cloudinary
node_scan_route -->|"detects foods"| node_vision
node_vision -.->|"queries model"| node_gemini
node_scan_route -->|"estimates and scores"| node_nutrition_calc
node_nutrition_calc -->|"looks up macros"| node_food_lookup
node_food_lookup -.->|"queries nutrition"| node_usda
node_person -->|"confirms meal"| node_meal_routes
node_api_hooks -->|"posts confirmation"| node_meal_routes
node_meal_routes -->|"saves meals"| node_prisma
node_meal_routes -->|"checks unlocks"| node_achievements
node_api_hooks -->|"logs health data"| node_tracking_routes
node_tracking_routes -.->|"reads and writes"| node_prisma
node_api_hooks -->|"requests charts"| node_stats_route
node_stats_route -->|"reads totals"| node_prisma
node_person -->|"asks coach"| node_coachui
node_api_hooks -->|"posts message"| node_coach_route
node_coach_route -->|"requests reply"| node_coach_logic
node_coach_route -->|"loads context and saves chat"| node_prisma
node_api_hooks -.->|"requests report"| node_report_route
node_report_route -->|"renders PDF"| node_report_doc
node_report_route -->|"reads report data"| node_prisma
node_person -->|"signs in"| node_auth_api
node_auth_api -.->|"verifies identity"| node_auth_logic
node_auth_logic -->|"loads user"| node_prisma
node_api_hooks -->|"reads token"| node_store
node_home -->|"renders components"| node_ui_primitives

click node_home "https://github.com/kingpinlab/optimeal/blob/main/src/components/screens/HomeScreen.tsx"
click node_scanui "https://github.com/kingpinlab/optimeal/blob/main/src/components/screens/ScanScreen.tsx"
click node_coachui "https://github.com/kingpinlab/optimeal/blob/main/src/components/screens/CoachScreen.tsx"
click node_profileui "https://github.com/kingpinlab/optimeal/blob/main/src/components/screens/ProfileScreen.tsx"
click node_calendarui "https://github.com/kingpinlab/optimeal/blob/main/src/components/screens/CalendarScreen.tsx"
click node_api_hooks "https://github.com/kingpinlab/optimeal/blob/main/src/hooks/useApi.ts"
click node_client_api "https://github.com/kingpinlab/optimeal/blob/main/src/lib/api.ts"
click node_ui_primitives "https://github.com/kingpinlab/optimeal/blob/main/src/components/ui/primitives.tsx"
click node_scan_route "https://github.com/kingpinlab/optimeal/blob/main/src/app/api/scan/route.ts"
click node_vision "https://github.com/kingpinlab/optimeal/blob/main/src/lib/ai/vision.ts"
click node_nutrition_calc "https://github.com/kingpinlab/optimeal/blob/main/src/lib/nutrition.ts"
click node_food_lookup "https://github.com/kingpinlab/optimeal/blob/main/src/lib/food-database.ts"
click node_meal_routes "https://github.com/kingpinlab/optimeal/blob/main/src/app/api/meals/route.ts"
click node_meal_item "https://github.com/kingpinlab/optimeal/blob/main/src/app/api/meals/%5Bid%5D/route.ts"
click node_tracking_routes "https://github.com/kingpinlab/optimeal/tree/main/src/app/api"
click node_stats_route "https://github.com/kingpinlab/optimeal/blob/main/src/app/api/stats/route.ts"
click node_achievements "https://github.com/kingpinlab/optimeal/blob/main/src/lib/achievements.ts"
click node_coach_route "https://github.com/kingpinlab/optimeal/blob/main/src/app/api/coach/route.ts"
click node_coach_logic "https://github.com/kingpinlab/optimeal/blob/main/src/lib/ai/coach.ts"
click node_report_route "https://github.com/kingpinlab/optimeal/blob/main/src/app/api/report/route.ts"
click node_report_doc "https://github.com/kingpinlab/optimeal/blob/main/src/lib/pdf/ReportDocument.tsx"
click node_auth_api "https://github.com/kingpinlab/optimeal/tree/main/src/app/api/auth"
click node_auth_logic "https://github.com/kingpinlab/optimeal/blob/main/src/lib/auth.ts"
click node_store "https://github.com/kingpinlab/optimeal/blob/main/src/store/useStore.ts"
click node_prisma "https://github.com/kingpinlab/optimeal/blob/main/src/lib/prisma.ts"
click node_cloudinary "https://github.com/kingpinlab/optimeal/blob/main/src/lib/cloudinary.ts"

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_home,node_scanui,node_coachui,node_profileui,node_calendarui,node_api_hooks,node_client_api,node_ui_primitives,node_person toneBlue
class node_scan_route,node_vision,node_nutrition_calc,node_food_lookup,node_meal_routes,node_meal_item toneAmber
class node_tracking_routes toneMint
class node_stats_route,node_achievements,node_coach_route,node_coach_logic,node_report_route,node_report_doc toneRose
class node_auth_api,node_auth_logic,node_store,node_prisma,node_cloudinary,node_gemini,node_usda toneIndigo
```

## Components

### Client experience

- [Home screen](https://github.com/kingpinlab/optimeal/blob/main/src/components/screens/HomeScreen.tsx): `src/components/screens/HomeScreen.tsx`
- [Scan screen](https://github.com/kingpinlab/optimeal/blob/main/src/components/screens/ScanScreen.tsx): `src/components/screens/ScanScreen.tsx`
- [Coach screen](https://github.com/kingpinlab/optimeal/blob/main/src/components/screens/CoachScreen.tsx): `src/components/screens/CoachScreen.tsx`
- [Profile screen](https://github.com/kingpinlab/optimeal/blob/main/src/components/screens/ProfileScreen.tsx): `src/components/screens/ProfileScreen.tsx`
- [Calendar screen](https://github.com/kingpinlab/optimeal/blob/main/src/components/screens/CalendarScreen.tsx): `src/components/screens/CalendarScreen.tsx`
- [API query hooks](https://github.com/kingpinlab/optimeal/blob/main/src/hooks/useApi.ts): `src/hooks/useApi.ts`
- [API client](https://github.com/kingpinlab/optimeal/blob/main/src/lib/api.ts): `src/lib/api.ts`
- [UI primitives](https://github.com/kingpinlab/optimeal/blob/main/src/components/ui/primitives.tsx): `src/components/ui/primitives.tsx`

### Meal nutrition

- [Meal scan API](https://github.com/kingpinlab/optimeal/blob/main/src/app/api/scan/route.ts): `src/app/api/scan/route.ts`
- [Food detection](https://github.com/kingpinlab/optimeal/blob/main/src/lib/ai/vision.ts): `src/lib/ai/vision.ts`
- [Nutrition optimizer](https://github.com/kingpinlab/optimeal/blob/main/src/lib/nutrition.ts): `src/lib/nutrition.ts`
- [Food macro lookup](https://github.com/kingpinlab/optimeal/blob/main/src/lib/food-database.ts): `src/lib/food-database.ts`
- [Meal records API](https://github.com/kingpinlab/optimeal/blob/main/src/app/api/meals/route.ts): `src/app/api/meals/route.ts`
- [Meal item API](https://github.com/kingpinlab/optimeal/blob/main/src/app/api/meals/%5Bid%5D/route.ts): `src/app/api/meals/[id]/route.ts`

### Health tracking

- [Health log APIs](https://github.com/kingpinlab/optimeal/tree/main/src/app/api): `src/app/api`

### Guidance and insights

- [Progress stats API](https://github.com/kingpinlab/optimeal/blob/main/src/app/api/stats/route.ts): `src/app/api/stats/route.ts`
- [Achievement rules](https://github.com/kingpinlab/optimeal/blob/main/src/lib/achievements.ts): `src/lib/achievements.ts`
- [Coach chat API](https://github.com/kingpinlab/optimeal/blob/main/src/app/api/coach/route.ts): `src/app/api/coach/route.ts`
- [Coach responses](https://github.com/kingpinlab/optimeal/blob/main/src/lib/ai/coach.ts): `src/lib/ai/coach.ts`
- [PDF report API](https://github.com/kingpinlab/optimeal/blob/main/src/app/api/report/route.ts): `src/app/api/report/route.ts`
- [Report document](https://github.com/kingpinlab/optimeal/blob/main/src/lib/pdf/ReportDocument.tsx): `src/lib/pdf/ReportDocument.tsx`

### Identity and platform

- [Authentication routes](https://github.com/kingpinlab/optimeal/tree/main/src/app/api/auth): `src/app/api/auth`
- [Token and user auth](https://github.com/kingpinlab/optimeal/blob/main/src/lib/auth.ts): `src/lib/auth.ts`
- [App state](https://github.com/kingpinlab/optimeal/blob/main/src/store/useStore.ts): `src/store/useStore.ts`
- [Application database](https://github.com/kingpinlab/optimeal/blob/main/src/lib/prisma.ts): `src/lib/prisma.ts`
- [Image storage](https://github.com/kingpinlab/optimeal/blob/main/src/lib/cloudinary.ts): `src/lib/cloudinary.ts`

### Other components

- **App user**
- **Gemini model**
- **USDA FoodData**

## Connections

- App user → Scan screen: captures photo
- Scan screen → API query hooks: starts scan (evidence: `src/hooks/useApi.ts`)
- API query hooks → API client: fetches API (evidence: `src/hooks/useApi.ts`)
- API client → Meal scan API: posts image
- Meal scan API → Image storage: uploads image (evidence: `src/app/api/scan/route.ts`)
- Meal scan API → Food detection: detects foods (evidence: `src/app/api/scan/route.ts`)
- Food detection → Gemini model: queries model
- Meal scan API → Nutrition optimizer: estimates and scores (evidence: `src/app/api/scan/route.ts`)
- Nutrition optimizer → Food macro lookup: looks up macros (evidence: `src/lib/nutrition.ts`)
- Food macro lookup → USDA FoodData: queries nutrition
- App user → Meal records API: confirms meal
- API query hooks → Meal records API: posts confirmation (evidence: `src/hooks/useApi.ts`)
- Meal records API → Application database: saves meals (evidence: `src/app/api/meals/route.ts`)
- Meal records API → Achievement rules: checks unlocks (evidence: `src/app/api/meals/route.ts`)
- API query hooks → Health log APIs: logs health data (evidence: `src/hooks/useApi.ts`)
- Health log APIs → Application database: reads and writes (evidence: `src/app/api/meals/route.ts`)
- API query hooks → Progress stats API: requests charts (evidence: `src/hooks/useApi.ts`)
- Progress stats API → Application database: reads totals (evidence: `src/app/api/stats/route.ts`)
- App user → Coach screen: asks coach
- API query hooks → Coach chat API: posts message (evidence: `src/hooks/useApi.ts`)
- Coach chat API → Coach responses: requests reply (evidence: `src/app/api/coach/route.ts`)
- Coach chat API → Application database: loads context and saves chat (evidence: `src/app/api/coach/route.ts`)
- API query hooks → PDF report API: requests report
- PDF report API → Report document: renders PDF (evidence: `src/app/api/report/route.ts`)
- PDF report API → Application database: reads report data (evidence: `src/app/api/report/route.ts`)
- App user → Authentication routes: signs in
- Authentication routes → Token and user auth: verifies identity
- Token and user auth → Application database: loads user (evidence: `src/lib/auth.ts`)
- API query hooks → App state: reads token (evidence: `src/hooks/useApi.ts`)
- Home screen → UI primitives: renders components (evidence: `src/components/screens/HomeScreen.tsx`)