# mehedihasan3000/flavor-ai architecture

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

- Interactive diagram: https://gitdiagram.com/mehedihasan3000/flavor-ai
- Repository: https://github.com/mehedihasan3000/flavor-ai

## Overview

FlavorAI is a recipe-sharing and AI-assisted meal-planning application. A user interacts with the Next.js pages, which call the Express API; the API authenticates requests, applies domain logic, and persists account and cooking data in MongoDB. The core journey spans pantry and preference input, recipe or weekly-plan generation, shopping-list creation, and pantry updates. Community recipes, nutrition analysis, diet planning, chat assistance, and administration are distinct capabilities. The README documents the product scope; sampled source supports key meal-plan, grocery, pantry, auth, and server boundaries, while unsampled feature wiring is shown only where directory structure and module roles support it.

Main entry points: [`backend/src/routes/v1.ts`](https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/routes/v1.ts) (API v1 routes), [`backend/src/models/Recipe.ts`](https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/models/Recipe.ts) (Recipe records), [`backend/src/controllers/groceryController.ts`](https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/controllers/groceryController.ts) (Shopping-list controller), [`backend/src/services/mealPlanService.ts`](https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/services/mealPlanService.ts) (Plan generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webpages["Product pages"]
  node_authpages["Sign-in pages"]
  node_client["API client<br/>[api.ts]"]
  node_assistantui["Assistant page<br/>[page.tsx]"]
  node_chatstorage[("Chat session storage")]
  node_authroutes["Auth proxy routes"]
end

subgraph group_api["API boundary"]
  node_server["Express app<br/>[server.ts]"]
  node_routes["API v1 routes<br/>[v1.ts]"]
  node_authctrl["Auth controller<br/>[authController.ts]"]
  node_aictrl["AI controller<br/>[aiController.ts]"]
  node_assistantctrl["Assistant controller"]
end

subgraph group_food["Cooking workflows"]
  node_pantryctrl["Pantry controller"]
  node_pantryservice["Pantry operations<br/>[pantryService.ts]"]
  node_pantry[("Pantry records<br/>[PantryItem.ts]")]
  node_mealctrl["Meal-plan controller"]
  node_mealservice["Plan generation<br/>[mealPlanService.ts]"]
  node_mealplans[("Meal plans<br/>[MealPlan.ts]")]
  node_groceryctrl["Shopping-list controller"]
  node_groceryservice["List calculations<br/>[groceryService.ts]"]
  node_grocery[("Grocery lists<br/>[GroceryList.ts]")]
  node_aiservice["AI generation<br/>[aiService.ts]"]
  node_assistantservice["Assistant context and chat"]
  node_dietservice["Diet planning<br/>[dietService.ts]"]
end

subgraph group_community["Recipes and community"]
  node_recipectrl["Recipe controller"]
  node_communityctrl["Community actions"]
  node_recipe[("Recipe records<br/>[Recipe.ts]")]
  node_socialrecords[("Ratings and saves<br/>[Rating.ts]")]
end

subgraph group_platform["Identity and data"]
  node_user[("User profiles<br/>[User.ts]")]
end

node_cook(("Home cook"))
node_mongodb[("MongoDB")]
node_groq{{"Groq AI"}}
node_imgbb{{"ImgBB images"}}
node_google{{"Google identity"}}

node_cook -->|"uses"| node_webpages
node_cook -->|"signs in"| node_authpages
node_webpages -->|"requests data"| node_client
node_assistantui -->|"sends chat"| node_client
node_assistantui -->|"persists turns"| node_chatstorage
node_authpages -->|"submits credentials"| node_authroutes
node_authroutes -->|"verifies account"| node_authctrl
node_authroutes -.->|"verifies token"| node_google
node_client -->|"calls API"| node_server
node_server -->|"dispatches"| node_routes
node_routes -->|"dispatches"| node_authctrl
node_routes -->|"dispatches"| node_recipectrl
node_routes -->|"dispatches"| node_communityctrl
node_routes -->|"dispatches"| node_pantryctrl
node_routes -->|"dispatches"| node_mealctrl
node_routes -->|"dispatches"| node_groceryctrl
node_routes -->|"dispatches"| node_aictrl
node_routes -->|"dispatches"| node_assistantctrl
node_recipectrl -->|"reads/writes"| node_recipe
node_communityctrl -->|"reads/writes"| node_socialrecords
node_communityctrl -->|"references"| node_recipe
node_pantryctrl -->|"reads/writes"| node_pantry
node_pantryctrl -->|"uses"| node_pantryservice
node_mealctrl -->|"generates or swaps"| node_mealservice
node_mealctrl -->|"reads/writes"| node_mealplans
node_mealctrl -->|"loads recipe cards"| node_recipe
node_mealservice -->|"reads stock"| node_pantryservice
node_mealservice -->|"persists plans"| node_mealplans
node_mealservice -->|"selects recipes"| node_recipe
node_mealservice -->|"requests generation"| node_groq
node_groceryctrl -->|"reads plan"| node_mealplans
node_groceryctrl -->|"loads ingredients"| node_recipe
node_groceryctrl -->|"reads or updates stock"| node_pantryservice
node_groceryctrl -->|"calculates requirements"| node_groceryservice
node_groceryctrl -->|"reads/writes"| node_grocery
node_aictrl -->|"requests AI work"| node_aiservice
node_aiservice -->|"requests generation"| node_groq
node_assistantctrl -->|"handles chat"| node_assistantservice
node_assistantservice -->|"uses kitchen context"| node_pantryservice
node_assistantservice -->|"reads preferences"| node_user
node_assistantservice -->|"reads saved recipes"| node_recipe
node_assistantservice -->|"requests response"| node_groq
node_dietservice -->|"uses profile"| node_user
node_authctrl -->|"reads/writes"| node_user
node_user -->|"persists"| node_mongodb
node_recipe -->|"persists"| node_mongodb
node_socialrecords -->|"persists"| node_mongodb
node_pantry -->|"persists"| node_mongodb

click node_webpages "https://github.com/mehedihasan3000/flavor-ai/tree/main/frontend/src/app"
click node_authpages "https://github.com/mehedihasan3000/flavor-ai/tree/main/frontend/src/app/(auth)"
click node_client "https://github.com/mehedihasan3000/flavor-ai/blob/main/frontend/src/lib/api.ts"
click node_assistantui "https://github.com/mehedihasan3000/flavor-ai/blob/main/frontend/src/app/assistant/page.tsx"
click node_chatstorage "https://github.com/mehedihasan3000/flavor-ai/blob/main/frontend/src/lib/assistant-storage.ts"
click node_authroutes "https://github.com/mehedihasan3000/flavor-ai/tree/main/frontend/src/app/api/auth"
click node_server "https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/server.ts"
click node_routes "https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/routes/v1.ts"
click node_authctrl "https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/controllers/authController.ts"
click node_recipectrl "https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/controllers/recipeController.ts"
click node_communityctrl "https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/controllers/commentController.ts"
click node_recipe "https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/models/Recipe.ts"
click node_socialrecords "https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/models/Rating.ts"
click node_pantryctrl "https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/controllers/pantryController.ts"
click node_pantryservice "https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/services/pantryService.ts"
click node_pantry "https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/models/PantryItem.ts"
click node_mealctrl "https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/controllers/mealPlanController.ts"
click node_mealservice "https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/services/mealPlanService.ts"
click node_mealplans "https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/models/MealPlan.ts"
click node_groceryctrl "https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/controllers/groceryController.ts"
click node_groceryservice "https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/services/groceryService.ts"
click node_grocery "https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/models/GroceryList.ts"
click node_aictrl "https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/controllers/aiController.ts"
click node_aiservice "https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/services/aiService.ts"
click node_assistantctrl "https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/controllers/assistantController.ts"
click node_assistantservice "https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/services/assistantService.ts"
click node_dietservice "https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/services/dietService.ts"
click node_user "https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/models/User.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_webpages,node_authpages,node_client,node_assistantui,node_chatstorage,node_authroutes toneBlue
class node_server,node_routes,node_authctrl,node_aictrl,node_assistantctrl,node_mongodb toneAmber
class node_pantryctrl,node_pantryservice,node_pantry,node_mealctrl,node_mealservice,node_mealplans,node_groceryctrl,node_groceryservice,node_grocery,node_aiservice,node_assistantservice,node_dietservice toneMint
class node_recipectrl,node_communityctrl,node_recipe,node_socialrecords toneRose
class node_user,node_cook,node_groq,node_imgbb,node_google toneIndigo
```

## Components

### Web experience

- [Product pages](https://github.com/mehedihasan3000/flavor-ai/tree/main/frontend/src/app): `frontend/src/app`
- [Sign-in pages](https://github.com/mehedihasan3000/flavor-ai/tree/main/frontend/src/app/(auth)): `frontend/src/app/(auth)`
- [API client](https://github.com/mehedihasan3000/flavor-ai/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [Assistant page](https://github.com/mehedihasan3000/flavor-ai/blob/main/frontend/src/app/assistant/page.tsx): `frontend/src/app/assistant/page.tsx`
- [Chat session storage](https://github.com/mehedihasan3000/flavor-ai/blob/main/frontend/src/lib/assistant-storage.ts): `frontend/src/lib/assistant-storage.ts`
- [Auth proxy routes](https://github.com/mehedihasan3000/flavor-ai/tree/main/frontend/src/app/api/auth): `frontend/src/app/api/auth`

### API boundary

- [Express app](https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/server.ts): `backend/src/server.ts`
- [API v1 routes](https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/routes/v1.ts): `backend/src/routes/v1.ts`
- [Auth controller](https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/controllers/authController.ts): `backend/src/controllers/authController.ts`
- [AI controller](https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/controllers/aiController.ts): `backend/src/controllers/aiController.ts`
- [Assistant controller](https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/controllers/assistantController.ts): `backend/src/controllers/assistantController.ts`

### Cooking workflows

- [Pantry controller](https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/controllers/pantryController.ts): `backend/src/controllers/pantryController.ts`
- [Pantry operations](https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/services/pantryService.ts): `backend/src/services/pantryService.ts`
- [Pantry records](https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/models/PantryItem.ts): `backend/src/models/PantryItem.ts`
- [Meal-plan controller](https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/controllers/mealPlanController.ts): `backend/src/controllers/mealPlanController.ts`
- [Plan generation](https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/services/mealPlanService.ts): `backend/src/services/mealPlanService.ts`
- [Meal plans](https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/models/MealPlan.ts): `backend/src/models/MealPlan.ts`
- [Shopping-list controller](https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/controllers/groceryController.ts): `backend/src/controllers/groceryController.ts`
- [List calculations](https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/services/groceryService.ts): `backend/src/services/groceryService.ts`
- [Grocery lists](https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/models/GroceryList.ts): `backend/src/models/GroceryList.ts`
- [AI generation](https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/services/aiService.ts): `backend/src/services/aiService.ts`
- [Assistant context and chat](https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/services/assistantService.ts): `backend/src/services/assistantService.ts`
- [Diet planning](https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/services/dietService.ts): `backend/src/services/dietService.ts`

### Recipes and community

- [Recipe controller](https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/controllers/recipeController.ts): `backend/src/controllers/recipeController.ts`
- [Community actions](https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/controllers/commentController.ts): `backend/src/controllers/commentController.ts`
- [Recipe records](https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/models/Recipe.ts): `backend/src/models/Recipe.ts`
- [Ratings and saves](https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/models/Rating.ts): `backend/src/models/Rating.ts`

### Identity and data

- [User profiles](https://github.com/mehedihasan3000/flavor-ai/blob/main/backend/src/models/User.ts): `backend/src/models/User.ts`

### Other components

- **Home cook**
- **MongoDB**
- **Groq AI**
- **ImgBB images**
- **Google identity**

## Connections

- Home cook → Product pages: uses
- Home cook → Sign-in pages: signs in
- Product pages → API client: requests data
- Assistant page → API client: sends chat
- Assistant page → Chat session storage: persists turns
- Sign-in pages → Auth proxy routes: submits credentials
- Auth proxy routes → Auth controller: verifies account
- Auth proxy routes → Google identity: verifies token
- API client → Express app: calls API
- Express app → API v1 routes: dispatches
- API v1 routes → Auth controller: dispatches
- API v1 routes → Recipe controller: dispatches
- API v1 routes → Community actions: dispatches
- API v1 routes → Pantry controller: dispatches
- API v1 routes → Meal-plan controller: dispatches
- API v1 routes → Shopping-list controller: dispatches
- API v1 routes → AI controller: dispatches
- API v1 routes → Assistant controller: dispatches
- Recipe controller → Recipe records: reads/writes
- Community actions → Ratings and saves: reads/writes
- Community actions → Recipe records: references
- Pantry controller → Pantry records: reads/writes
- Pantry controller → Pantry operations: uses
- Meal-plan controller → Plan generation: generates or swaps
- Meal-plan controller → Meal plans: reads/writes
- Meal-plan controller → Recipe records: loads recipe cards
- Plan generation → Pantry operations: reads stock
- Plan generation → Meal plans: persists plans
- Plan generation → Recipe records: selects recipes
- Plan generation → Groq AI: requests generation
- Shopping-list controller → Meal plans: reads plan
- Shopping-list controller → Recipe records: loads ingredients
- Shopping-list controller → Pantry operations: reads or updates stock
- Shopping-list controller → List calculations: calculates requirements
- Shopping-list controller → Grocery lists: reads/writes
- AI controller → AI generation: requests AI work
- AI generation → Groq AI: requests generation
- Assistant controller → Assistant context and chat: handles chat
- Assistant context and chat → Pantry operations: uses kitchen context
- Assistant context and chat → User profiles: reads preferences
- Assistant context and chat → Recipe records: reads saved recipes
- Assistant context and chat → Groq AI: requests response
- Diet planning → User profiles: uses profile
- Auth controller → User profiles: reads/writes
- User profiles → MongoDB: persists
- Recipe records → MongoDB: persists
- Ratings and saves → MongoDB: persists
- Pantry records → MongoDB: persists