# raj-sarkar123/nutrition-recommendation- architecture

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

- Interactive diagram: https://gitdiagram.com/raj-sarkar123/nutrition-recommendation-
- Repository: https://github.com/raj-sarkar123/nutrition-recommendation-

## Overview

#### 1. Purpose and Runtime Topology
NutriScan AI is a full-stack nutrition tracking and AI meal-analysis application. A React/Vite single-page client calls an Express REST API; the backend coordinates Supabase persistence, AI analysis, image/OCR processing, email OTP, and notifications. Frontend deployment is configured for Vercel; the README identifies Render for backend deployment.
- `frontend/src/main.jsx`
- `frontend/src/App.jsx`
- `backend/server.js`

#### 2. Client Application and Navigation
The frontend is the primary user entry point. `App.jsx` routes users through authentication, onboarding, dashboard, scan, analysis, meal tracking, insights, profile, and progress views. Shared layout/navigation separates app-shell concerns from page features.
- `frontend/src/App.jsx`
- `frontend/src/components/layout/AppLayout.jsx`
- `frontend/src/pages/ScanPage.jsx`

#### 3. Client State and API Boundary
React contexts centralize cross-page state for authentication, nutrition data, scanning, notifications, and Supabase realtime synchronization. HTTP communication is isolated through an Axios client, while browser-side Supabase access supports realtime subscriptions. This creates a boundary between UI state/realtime events and backend-owned REST workflows.
- `frontend/src/api/axios.js`
- `frontend/src/context/AuthContext.jsx`
- `frontend/src/context/RealtimeSyncContext.jsx`

#### 4. Express API Composition and Security
`backend/server.js` is the backend entry point and mounts domain route modules for auth, users, meals, scans, progress, and notifications. Controllers implement request orchestration; JWT middleware protects authenticated endpoints. CORS and multipart upload handling are explicit middleware boundaries.
- `backend/server.js`
- `backend/middleware/auth.js`
- `backend/routes/scan.routes.js`

#### 5. Identity and User Lifecycle
Authentication supports registration/login and session access through auth routes/controllers, backed by JWTs. OTP state and email delivery are implemented separately, indicating verification or password-recovery flows. User profile/onboarding information is handled as a dedicated user domain rather than embedded in meal operations.
- `backend/controllers/auth.controller.js`
- `backend/data/otpStore.js`
- `backend/services/email.service.js`

#### 6. Scan-to-Nutrition Analysis Pipeline
The scan domain accepts uploaded food/menu images, preprocesses them, extracts or parses content, calculates nutritional values, then invokes Groq-backed analysis for recommendations. Temporary uploads form a filesystem boundary before AI/nutrition processing; the trained OCR data file indicates local OCR capability.
- `backend/controllers/scan.controller.js`
- `backend/services/imagePreprocess.service.js`
- `backend/services/analysis.groq.service.js`

#### 7. Nutrition, Tracking, and Insights Flow
Meal operations persist or retrieve food-log data, while progress operations aggregate intake/goals into tracking views. The client exposes this through dashboard, tracker, progress, analysis, and smart-insights pages. Nutrition calculation is a dedicated service, keeping deterministic macro computation separate from AI-generated guidance.
- `backend/controllers/meal.controller.js`
- `backend/controllers/progress.controller.js`
- `backend/services/nutrition.calc.js`

#### 8. Persistence, Realtime, and External Services
Supabase is the database integration point in both backend and frontend. SQL files define core schema extensions and realtime notification setup. Notifications have an API/controller/service path and client subscription/UI path. External dependencies include Supabase, Groq, Gemini (per README/environment), nutrition APIs, and email infrastructure.
- `backend/config/supabase.js`
- `database/realtime_notifications_setup.sql`
- `frontend/src/lib/supabaseClient.js`

Main entry points: [`backend/server.js`](https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/backend/server.js) (Express server), [`backend/controllers/auth.controller.js`](https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/backend/controllers/auth.controller.js) (Auth controller), [`backend/config/supabase.js`](https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/backend/config/supabase.js) (Backend Supabase client), [`frontend/src/App.jsx`](https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/frontend/src/App.jsx) (App router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React Client"]
  node_app["App router<br/>React routing<br/>[App.jsx]"]
  node_layout["App layout<br/>shared UI shell<br/>[AppLayout.jsx]"]
  node_scan_page["Scan page<br/>scan UI<br/>[ScanPage.jsx]"]
  node_auth_context["Auth context<br/>client state<br/>[AuthContext.jsx]"]
  node_realtime_context["Realtime sync context<br/>client state"]
  node_axios["Axios API client<br/>HTTP boundary<br/>[axios.js]"]
  node_browser_supabase["Browser Supabase client<br/>realtime client<br/>[supabaseClient.js]"]
end

subgraph group_api["Express API"]
  node_server["Express server<br/>API entry point<br/>[server.js]"]
  node_auth_middleware["JWT middleware<br/>API security<br/>[auth.js]"]
  node_scan_routes["Scan routes<br/>multipart routes<br/>[scan.routes.js]"]
  node_auth_controller["Auth controller<br/>identity orchestration<br/>[auth.controller.js]"]
  node_scan_controller["Scan controller<br/>scan orchestration<br/>[scan.controller.js]"]
  node_meal_controller["Meal controller<br/>food-log API<br/>[meal.controller.js]"]
  node_progress_controller["Progress controller<br/>tracking API"]
end

subgraph group_services["Processing Services"]
  node_image_preprocess["Image preprocessing<br/>image/OCR stage"]
  node_nutrition_calc["Nutrition calculator<br/>deterministic nutrition<br/>[nutrition.calc.js]"]
  node_groq_analysis{{"Groq analysis<br/>AI guidance"}}
  node_otp_store["OTP store<br/>verification state<br/>[otpStore.js]"]
  node_email_service["Email service<br/>OTP delivery<br/>[email.service.js]"]
end

subgraph group_data["Data &amp; External Systems"]
  node_backend_supabase["Backend Supabase client<br/>persistence adapter<br/>[supabase.js]"]
  node_supabase[("Supabase<br/>database and realtime")]
  node_realtime_schema["Realtime notification setup<br/>SQL schema"]
end

node_app -->|"renders"| node_layout
node_app -->|"routes to"| node_scan_page
node_app -->|"uses"| node_auth_context
node_scan_page -->|"submits scans"| node_axios
node_realtime_context -->|"subscribes through"| node_browser_supabase
node_axios -->|"REST requests"| node_server
node_server -->|"protects endpoints"| node_auth_middleware
node_server -->|"mounts"| node_scan_routes
node_server -->|"auth requests"| node_auth_controller
node_server -->|"meal requests"| node_meal_controller
node_server -->|"progress requests"| node_progress_controller
node_scan_routes -->|"dispatches"| node_scan_controller
node_scan_controller -->|"preprocesses upload"| node_image_preprocess
node_image_preprocess -->|"extracts food input"| node_nutrition_calc
node_nutrition_calc -->|"provides nutrition context"| node_groq_analysis
node_scan_controller -->|"requests recommendations"| node_groq_analysis
node_meal_controller -->|"calculates macros"| node_nutrition_calc
node_auth_controller -->|"manages OTPs"| node_otp_store
node_auth_controller -->|"sends verification email"| node_email_service
node_auth_controller -->|"persists users"| node_backend_supabase
node_meal_controller -->|"reads and writes logs"| node_backend_supabase
node_progress_controller -->|"reads intake and goals"| node_backend_supabase
node_backend_supabase -->|"connects to"| node_supabase
node_browser_supabase -->|"realtime subscriptions"| node_supabase
node_realtime_schema -.->|"configures notifications"| node_supabase

click node_app "https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/frontend/src/App.jsx"
click node_layout "https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/frontend/src/components/layout/AppLayout.jsx"
click node_scan_page "https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/frontend/src/pages/ScanPage.jsx"
click node_auth_context "https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/frontend/src/context/AuthContext.jsx"
click node_realtime_context "https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/frontend/src/context/RealtimeSyncContext.jsx"
click node_axios "https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/frontend/src/api/axios.js"
click node_browser_supabase "https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/frontend/src/lib/supabaseClient.js"
click node_server "https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/backend/server.js"
click node_auth_middleware "https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/backend/middleware/auth.js"
click node_scan_routes "https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/backend/routes/scan.routes.js"
click node_auth_controller "https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/backend/controllers/auth.controller.js"
click node_scan_controller "https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/backend/controllers/scan.controller.js"
click node_meal_controller "https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/backend/controllers/meal.controller.js"
click node_progress_controller "https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/backend/controllers/progress.controller.js"
click node_image_preprocess "https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/backend/services/imagePreprocess.service.js"
click node_nutrition_calc "https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/backend/services/nutrition.calc.js"
click node_groq_analysis "https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/backend/services/analysis.groq.service.js"
click node_otp_store "https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/backend/data/otpStore.js"
click node_email_service "https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/backend/services/email.service.js"
click node_backend_supabase "https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/backend/config/supabase.js"
click node_realtime_schema "https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/database/realtime_notifications_setup.sql"

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_layout,node_scan_page,node_auth_context,node_realtime_context,node_axios,node_browser_supabase toneBlue
class node_server,node_auth_middleware,node_scan_routes,node_auth_controller,node_scan_controller,node_meal_controller,node_progress_controller toneAmber
class node_image_preprocess,node_nutrition_calc,node_groq_analysis,node_otp_store,node_email_service toneMint
class node_backend_supabase,node_supabase,node_realtime_schema toneRose
```

## Components

### React Client

- [App router](https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/frontend/src/App.jsx): React routing · Routes authentication and nutrition-tracking views. · `frontend/src/App.jsx`
- [App layout](https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/frontend/src/components/layout/AppLayout.jsx): shared UI shell · `frontend/src/components/layout/AppLayout.jsx`
- [Scan page](https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/frontend/src/pages/ScanPage.jsx): scan UI · `frontend/src/pages/ScanPage.jsx`
- [Auth context](https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/frontend/src/context/AuthContext.jsx): client state · `frontend/src/context/AuthContext.jsx`
- [Realtime sync context](https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/frontend/src/context/RealtimeSyncContext.jsx): client state · `frontend/src/context/RealtimeSyncContext.jsx`
- [Axios API client](https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/frontend/src/api/axios.js): HTTP boundary · `frontend/src/api/axios.js`
- [Browser Supabase client](https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/frontend/src/lib/supabaseClient.js): realtime client · `frontend/src/lib/supabaseClient.js`

### Express API

- [Express server](https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/backend/server.js): API entry point · Composes domain routes and middleware. · `backend/server.js`
- [JWT middleware](https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/backend/middleware/auth.js): API security · `backend/middleware/auth.js`
- [Scan routes](https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/backend/routes/scan.routes.js): multipart routes · `backend/routes/scan.routes.js`
- [Auth controller](https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/backend/controllers/auth.controller.js): identity orchestration · `backend/controllers/auth.controller.js`
- [Scan controller](https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/backend/controllers/scan.controller.js): scan orchestration · `backend/controllers/scan.controller.js`
- [Meal controller](https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/backend/controllers/meal.controller.js): food-log API · `backend/controllers/meal.controller.js`
- [Progress controller](https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/backend/controllers/progress.controller.js): tracking API · `backend/controllers/progress.controller.js`

### Processing Services

- [Image preprocessing](https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/backend/services/imagePreprocess.service.js): image/OCR stage · Processes uploaded food or menu images before analysis. · `backend/services/imagePreprocess.service.js`
- [Nutrition calculator](https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/backend/services/nutrition.calc.js): deterministic nutrition · `backend/services/nutrition.calc.js`
- [Groq analysis](https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/backend/services/analysis.groq.service.js): AI guidance · `backend/services/analysis.groq.service.js`
- [OTP store](https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/backend/data/otpStore.js): verification state · `backend/data/otpStore.js`
- [Email service](https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/backend/services/email.service.js): OTP delivery · `backend/services/email.service.js`

### Data & External Systems

- [Backend Supabase client](https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/backend/config/supabase.js): persistence adapter · `backend/config/supabase.js`
- **Supabase**: database and realtime · Shared persistence and realtime platform.
- [Realtime notification setup](https://github.com/raj-sarkar123/nutrition-recommendation-/blob/main/database/realtime_notifications_setup.sql): SQL schema · `database/realtime_notifications_setup.sql`

## Connections

- App router → App layout: renders
- App router → Scan page: routes to
- App router → Auth context: uses
- Scan page → Axios API client: submits scans
- Realtime sync context → Browser Supabase client: subscribes through
- Axios API client → Express server: REST requests
- Express server → JWT middleware: protects endpoints
- Express server → Scan routes: mounts
- Express server → Auth controller: auth requests
- Express server → Meal controller: meal requests
- Express server → Progress controller: progress requests
- Scan routes → Scan controller: dispatches
- Scan controller → Image preprocessing: preprocesses upload
- Image preprocessing → Nutrition calculator: extracts food input
- Nutrition calculator → Groq analysis: provides nutrition context
- Scan controller → Groq analysis: requests recommendations
- Meal controller → Nutrition calculator: calculates macros
- Auth controller → OTP store: manages OTPs
- Auth controller → Email service: sends verification email
- Auth controller → Backend Supabase client: persists users
- Meal controller → Backend Supabase client: reads and writes logs
- Progress controller → Backend Supabase client: reads intake and goals
- Backend Supabase client → Supabase: connects to
- Browser Supabase client → Supabase: realtime subscriptions
- Realtime notification setup → Supabase: configures notifications