# ashermemon/meal-mash architecture

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

- Interactive diagram: https://gitdiagram.com/ashermemon/meal-mash
- Repository: https://github.com/ashermemon/meal-mash

## Overview

1. **Repository shape**
   - This is a two-tier product: a **mobile client** in `client/` and a **Python backend** in `server/`.
   - The client is the primary user-facing app; the server handles persistence and recipe generation logic.

2. **Mobile runtime and navigation**
   - The client is an **Expo/React Native** app using **TypeScript** and **Expo Router**.
   - Navigation is file-based under `client/app/`, with a root layout plus a tabbed shell in `client/app/(tabs)/`.
   - The main app surfaces are home, generation, pantry, saved recipes, profile, recipe detail, and “follow recipe” flows.

3. **Client feature boundaries**
   - UI is organized by feature under `client/components/features/`, which is the clearest architectural boundary in the frontend.
   - Major feature areas:
     - `home`: welcome, featured recipes, explore content
     - `generator`: ingredient entry, leftovers, generation preview, search
     - `pantry`: ingredient tagging and suggestions
     - `recipe`: recipe detail, progress/timer, save/follow actions
     - `saved`: saved recipe and favorite ingredient presentation
     - `auth`: login
     - `profile`: user counters / profile summary

4. **State management and cross-screen coordination**
   - Shared app state lives in `client/contexts/`.
   - These contexts indicate the app relies on **context-based global state** rather than a centralized Redux-style store.
   - Important state domains include favorites, saved recipes, generation details, leftovers, nutrients, search, notifications, and recipe state.

5. **Client data access and persistence**
   - `client/httpClient.tsx` is the main client-side network boundary, likely wrapping backend requests.
   - `client/utils/storage.ts` suggests local persistence for session-like or cached app data.
   - `client/utils/RecipeSchema.ts` implies the app validates or shapes recipe payloads before rendering or saving.
   - `client/utils/registerForPushNotificationsAsync.ts` and `scheduleDailyNotification.tsx` show the client also owns local push notification setup and scheduling.

6. **Recipe generation flow**
   - The generation workflow is split across `generator` components such as ingredient adders, leftover handling, search, preview cards, and generation details.
   - The flow likely starts with user input in the generator UI, passes through shared generation context, and then calls the backend through the HTTP client.
   - The resulting recipe preview then feeds into the recipe detail or follow-recipe screens.

7. **Recipe execution flow**
   - `client/app/followRecipe.tsx` and the `recipe` feature components indicate a guided cooking experience, not just static recipe display.
   - Components like progress bars, timers, nutrient circles, and sectioned instructions suggest a stepwise cook-along mode.
   - Saving/favoriting appears to be attached directly to recipe views via dedicated feature components and contexts.

8. **Pantry and ingredient knowledge**
   - Pantry management is a first-class feature, with tag-based ingredient UI and suggestions.
   - The client also includes local ingredient datasets in `client/ingredientDatabase/`, including `ingredientsDB.json` and `leftoversDB.json`.
   - That means some ingredient classification/suggestion behavior can happen locally without depending entirely on the server.

9. **Visual system and reusable UI**
   - Shared UI primitives live in `client/components/common/` and `client/components/universal/`.
   - These cover reusable controls like pills, sliders, checkboxes, headers, camera access, emoji/icon rendering, and modal/sheet content.
   - Styling is split between theme constants and global style definitions, which gives the app a consistent visual layer across features.

10. **Backend responsibilities**
   - The backend is a Python application in `server/`, with `app.py` as the main entrypoint.
   - `models.py` and the SQLite files under `server/instance/` indicate a small relational persistence layer.
   - `gen.py` is the main signal that recipe generation or AI-assisted content assembly happens server-side rather than only in the client.

11. **Backend deployment/runtime**
   - `requirements.txt` and `gunicorn_config.py` show the server is intended to run as a production Python service, likely behind Gunicorn.
   - The server uses SQLite for local/file-based persistence, which keeps the deployment lightweight and self-contained.

12. **Data flow across the system**
   - User actions start in the mobile app UI, move through feature-specific components and contexts, then call the backend through the HTTP client when data must be generated, saved, or retrieved.
   - The backend persists structured data in SQLite and returns recipe-related results to the client.
   - The client then renders those results into home, pantry, generation, recipe, and saved screens, with local storage and notifications supporting offline-ish or recurring-app behavior.

13. **Repo-level boundary summary**
   - The clearest architecture boundary is:
     - **Client**: navigation, state, UI composition, local caching, notifications, ingredient UI
     - **Server**: recipe generation and persistence
   - Supporting assets, themes, and local ingredient databases are embedded in the client, while durable app data appears to live in the server’s SQLite store.

Main entry points: [`client/app/_layout.tsx`](https://github.com/ashermemon/meal-mash/blob/main/client/app/_layout.tsx) (App shell), [`client/contexts/RecipeContext.tsx`](https://github.com/ashermemon/meal-mash/blob/main/client/contexts/RecipeContext.tsx) (App state), [`client/app/(tabs)/generationpage.tsx`](https://github.com/ashermemon/meal-mash/blob/main/client/app/(tabs)/generationpage.tsx) (Generate), [`client/app/recipe.tsx`](https://github.com/ashermemon/meal-mash/blob/main/client/app/recipe.tsx) (Recipe view)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_client_root["App shell<br/>expo-router<br/>[_layout.tsx]"]
  node_client_home["Home<br/>screen<br/>[index.tsx]"]
  node_client_generate["Generate<br/>screen<br/>[generationpage.tsx]"]
  node_client_pantry["Pantry<br/>screen<br/>[pantry.tsx]"]
  node_client_saves["Saved<br/>screen<br/>[saves.tsx]"]
  node_client_profile["Profile<br/>screen<br/>[profile.tsx]"]
  node_client_recipe["Recipe view<br/>screen<br/>[recipe.tsx]"]
  node_client_follow["Cook along<br/>screen<br/>[followRecipe.tsx]"]
  node_feat_home["Home features<br/>ui feature<br/>[Welcome.tsx]"]
  node_feat_generator["Generator features<br/>ui feature<br/>[AddIngredients.tsx]"]
  node_feat_pantry["Pantry features<br/>ui feature"]
  node_feat_recipe["Recipe features<br/>ui feature"]
  node_feat_saved["Saved features<br/>ui feature<br/>[DisplaySaved.tsx]"]
  node_contexts[("App state<br/>contexts<br/>[RecipeContext.tsx]")]
  node_http["HTTP client<br/>network<br/>[httpClient.tsx]"]
  node_storage[("Local storage<br/>persistence<br/>[storage.ts]")]
  node_ingredients_db["Ingredient DB<br/>local data<br/>[ingredientsDB.json]"]
  node_notifications["Notifications<br/>device service"]
end

subgraph group_server["Server"]
  node_server_app["API app<br/>python app<br/>[app.py]"]
  node_server_gen["Recipe gen<br/>generation<br/>[gen.py]"]
  node_server_models["Models<br/>[models.py]"]
  node_server_db[("SQLite store<br/>database<br/>[db.sqlite]")]
end

node_client_root -->|"navigates to"| node_client_home
node_client_root -->|"routes"| node_client_generate
node_client_root -->|"routes"| node_client_pantry
node_client_root -->|"routes"| node_client_saves
node_client_root -->|"routes"| node_client_profile
node_client_home -->|"uses"| node_feat_home
node_client_generate -->|"uses"| node_feat_generator
node_client_pantry -->|"uses"| node_feat_pantry
node_client_recipe -->|"uses"| node_feat_recipe
node_client_saves -->|"uses"| node_feat_saved
node_feat_generator -->|"reads/writes"| node_contexts
node_feat_recipe -->|"reads/writes"| node_contexts
node_feat_saved -->|"reads/writes"| node_contexts
node_feat_pantry -->|"consults"| node_ingredients_db
node_contexts -->|"requests"| node_http
node_http -->|"calls"| node_server_app
node_server_app -->|"delegates"| node_server_gen
node_server_app -->|"uses"| node_server_models
node_server_models -->|"persists to"| node_server_db
node_http -->|"caches"| node_storage
node_notifications -->|"supports"| node_client_root
node_client_generate -->|"opens"| node_client_recipe
node_client_recipe -->|"continues"| node_client_follow

click node_client_root "https://github.com/ashermemon/meal-mash/blob/main/client/app/_layout.tsx"
click node_client_home "https://github.com/ashermemon/meal-mash/blob/main/client/app/(tabs)/index.tsx"
click node_client_generate "https://github.com/ashermemon/meal-mash/blob/main/client/app/(tabs)/generationpage.tsx"
click node_client_pantry "https://github.com/ashermemon/meal-mash/blob/main/client/app/(tabs)/pantry.tsx"
click node_client_saves "https://github.com/ashermemon/meal-mash/blob/main/client/app/(tabs)/saves.tsx"
click node_client_profile "https://github.com/ashermemon/meal-mash/blob/main/client/app/(tabs)/profile.tsx"
click node_client_recipe "https://github.com/ashermemon/meal-mash/blob/main/client/app/recipe.tsx"
click node_client_follow "https://github.com/ashermemon/meal-mash/blob/main/client/app/followRecipe.tsx"
click node_feat_home "https://github.com/ashermemon/meal-mash/blob/main/client/components/features/home/Welcome.tsx"
click node_feat_generator "https://github.com/ashermemon/meal-mash/blob/main/client/components/features/generator/AddIngredients.tsx"
click node_feat_pantry "https://github.com/ashermemon/meal-mash/blob/main/client/components/features/pantry/AddIngredientTag.tsx"
click node_feat_recipe "https://github.com/ashermemon/meal-mash/blob/main/client/components/features/recipe/FollowRecipeHeader.tsx"
click node_feat_saved "https://github.com/ashermemon/meal-mash/blob/main/client/components/features/saved/DisplaySaved.tsx"
click node_contexts "https://github.com/ashermemon/meal-mash/blob/main/client/contexts/RecipeContext.tsx"
click node_http "https://github.com/ashermemon/meal-mash/blob/main/client/app/httpClient.tsx"
click node_storage "https://github.com/ashermemon/meal-mash/blob/main/client/utils/storage.ts"
click node_ingredients_db "https://github.com/ashermemon/meal-mash/blob/main/client/ingredientDatabase/ingredientsDB.json"
click node_notifications "https://github.com/ashermemon/meal-mash/blob/main/client/utils/registerForPushNotificationsAsync.ts"
click node_server_app "https://github.com/ashermemon/meal-mash/blob/main/server/app.py"
click node_server_gen "https://github.com/ashermemon/meal-mash/blob/main/server/gen.py"
click node_server_models "https://github.com/ashermemon/meal-mash/blob/main/server/models.py"
click node_server_db "https://github.com/ashermemon/meal-mash/blob/main/server/instance/db.sqlite"

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_client_root,node_client_home,node_client_generate,node_client_pantry,node_client_saves,node_client_profile,node_client_recipe,node_client_follow,node_feat_home,node_feat_generator,node_feat_pantry,node_feat_recipe,node_feat_saved,node_contexts,node_http,node_storage,node_ingredients_db,node_notifications toneBlue
class node_server_app,node_server_gen,node_server_models,node_server_db toneAmber
```

## Components

### Client

Expo/React Native mobile app

- [App shell](https://github.com/ashermemon/meal-mash/blob/main/client/app/_layout.tsx): expo-router · Root layout and tab navigation for the mobile app · `client/app/_layout.tsx`
- [Home](https://github.com/ashermemon/meal-mash/blob/main/client/app/(tabs)/index.tsx): screen · Entry screen with welcome, featured recipes, and explore content · `client/app/(tabs)/index.tsx`
- [Generate](https://github.com/ashermemon/meal-mash/blob/main/client/app/(tabs)/generationpage.tsx): screen · Tabbed generation page that starts recipe creation · `client/app/(tabs)/generationpage.tsx`
- [Pantry](https://github.com/ashermemon/meal-mash/blob/main/client/app/(tabs)/pantry.tsx): screen · Ingredient tagging and suggestion flow · `client/app/(tabs)/pantry.tsx`
- [Saved](https://github.com/ashermemon/meal-mash/blob/main/client/app/(tabs)/saves.tsx): screen · Saved recipes and favorite ingredient views · `client/app/(tabs)/saves.tsx`
- [Profile](https://github.com/ashermemon/meal-mash/blob/main/client/app/(tabs)/profile.tsx): screen · User counters and profile summary · `client/app/(tabs)/profile.tsx`
- [Recipe view](https://github.com/ashermemon/meal-mash/blob/main/client/app/recipe.tsx): screen · Recipe detail and save actions · `client/app/recipe.tsx`
- [Cook along](https://github.com/ashermemon/meal-mash/blob/main/client/app/followRecipe.tsx): screen · Guided follow-recipe experience with progress and timers · `client/app/followRecipe.tsx`
- [Home features](https://github.com/ashermemon/meal-mash/blob/main/client/components/features/home/Welcome.tsx): ui feature · Welcome, featured recipes, and explore components · `client/components/features/home/Welcome.tsx`
- [Generator features](https://github.com/ashermemon/meal-mash/blob/main/client/components/features/generator/AddIngredients.tsx): ui feature · Ingredient entry, leftovers, preview, and generation controls · `client/components/features/generator/AddIngredients.tsx`
- [Pantry features](https://github.com/ashermemon/meal-mash/blob/main/client/components/features/pantry/AddIngredientTag.tsx): ui feature · Tagging and ingredient suggestion components · `client/components/features/pantry/AddIngredientTag.tsx`
- [Recipe features](https://github.com/ashermemon/meal-mash/blob/main/client/components/features/recipe/FollowRecipeHeader.tsx): ui feature · Progress, timers, info tags, and save/follow controls · `client/components/features/recipe/FollowRecipeHeader.tsx`
- [Saved features](https://github.com/ashermemon/meal-mash/blob/main/client/components/features/saved/DisplaySaved.tsx): ui feature · Saved recipe and favorite ingredient presentation · `client/components/features/saved/DisplaySaved.tsx`
- [App state](https://github.com/ashermemon/meal-mash/blob/main/client/contexts/RecipeContext.tsx): contexts · Context-based global state for favorites, saved recipes, generation, search, nutrients, and recipe flow · `client/contexts/RecipeContext.tsx`
- [HTTP client](https://github.com/ashermemon/meal-mash/blob/main/client/app/httpClient.tsx): network · Main client-side backend boundary · `client/app/httpClient.tsx`
- [Local storage](https://github.com/ashermemon/meal-mash/blob/main/client/utils/storage.ts): persistence · Client-side persistence for session-like or cached data · `client/utils/storage.ts`
- [Ingredient DB](https://github.com/ashermemon/meal-mash/blob/main/client/ingredientDatabase/ingredientsDB.json): local data · Local ingredient and leftovers datasets used by pantry and generation flows · `client/ingredientDatabase/ingredientsDB.json`
- [Notifications](https://github.com/ashermemon/meal-mash/blob/main/client/utils/registerForPushNotificationsAsync.ts): device service · Push registration and daily scheduling support · `client/utils/registerForPushNotificationsAsync.ts`

### Server

Python backend service

- [API app](https://github.com/ashermemon/meal-mash/blob/main/server/app.py): python app · Backend entrypoint and service wiring · `server/app.py`
- [Recipe gen](https://github.com/ashermemon/meal-mash/blob/main/server/gen.py): generation · Server-side recipe generation logic · `server/gen.py`
- [Models](https://github.com/ashermemon/meal-mash/blob/main/server/models.py): persistence models · Structured data models for backend persistence · `server/models.py`
- [SQLite store](https://github.com/ashermemon/meal-mash/blob/main/server/instance/db.sqlite): database · File-based durable persistence · `server/instance/db.sqlite`

## Connections

- App shell → Home: navigates to · Root shell exposes the main app surfaces
- App shell → Generate: routes · Tabbed navigation includes generation
- App shell → Pantry: routes · Tabbed navigation includes pantry
- App shell → Saved: routes · Tabbed navigation includes saved items
- App shell → Profile: routes · Tabbed navigation includes profile
- Home → Home features: uses · Home screen is assembled from feature components
- Generate → Generator features: uses · Generation screen is assembled from generator components
- Pantry → Pantry features: uses · Pantry screen is assembled from pantry components
- Recipe view → Recipe features: uses · Recipe detail and cook-along views reuse recipe components
- Saved → Saved features: uses · Saved screen is assembled from saved components
- Generator features → App state: reads/writes · Generation UI coordinates through shared context state
- Recipe features → App state: reads/writes · Recipe flow uses shared state for timers, nutrients, and save/follow actions
- Saved features → App state: reads/writes · Saved views reflect shared favorites and saved-recipes state
- Pantry features → Ingredient DB: consults · Local ingredient data supports pantry suggestions and tagging
- App state → HTTP client: requests · Shared state triggers backend fetches and mutations
- HTTP client → API app: calls · Client network boundary talks to backend API
- API app → Recipe gen: delegates · API routes invoke generation logic
- API app → Models: uses · Service uses structured persistence models
- Models → SQLite store: persists to · Backend data is stored in SQLite
- HTTP client → Local storage: caches · Client persists local session or cached app data
- Notifications → App shell: supports · Device notifications complement the app shell experience
- Generate → Recipe view: opens · Generated recipes flow into detail views
- Recipe view → Cook along: continues · Recipe detail can launch guided cook-along mode
