# hany-r-mahmoud/wajba architecture

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

- Interactive diagram: https://gitdiagram.com/hany-r-mahmoud/wajba
- Repository: https://github.com/hany-r-mahmoud/wajba

## Overview

Wajba is a local-first bilingual meal-planning app. Users explore a static recipe catalog, assign meals to weekly or monthly plans (including Ramadan slots), then use aggregated grocery lists and pantry matching to shop; cooking timers support preparation. Browser storage keeps plans and preferences, with backup/restore and optional family synchronization. The graph includes the documented public recipe/SEO and PWA capabilities. Some subsystem links are documented rather than verified from sampled call sites; those edges are dashed where implementation details are unavailable.

Main entry points: [`src/App.tsx`](https://github.com/hany-r-mahmoud/wajba/blob/main/src/App.tsx) (Application), [`src/components/RecipeExplorer.tsx`](https://github.com/hany-r-mahmoud/wajba/blob/main/src/components/RecipeExplorer.tsx) (Recipe explorer), [`src/components/GroceryListView.tsx`](https://github.com/hany-r-mahmoud/wajba/blob/main/src/components/GroceryListView.tsx) (Grocery list), [`src/components/FamilySyncModal.tsx`](https://github.com/hany-r-mahmoud/wajba/blob/main/src/components/FamilySyncModal.tsx) (Family sync)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_planning["Meal planning"]
  node_weekly["Weekly planner"]
  node_monthly["Monthly planner"]
  node_meal_controls["Meal controls"]
  node_timer["Cooking timers"]
end

subgraph group_recipes["Recipe experience"]
  node_catalog["Recipe catalog<br/>[recipes.ts]"]
  node_explorer["Recipe explorer<br/>[RecipeExplorer.tsx]"]
  node_recipe_detail["Recipe details"]
  node_recipe_card["Recipe card<br/>[RecipeCard.tsx]"]
end

subgraph group_shopping["Shopping tools"]
  node_grocery_view["Grocery list"]
  node_aggregation["Ingredient aggregation<br/>[aggregator.ts]"]
  node_pantry["Pantry matching<br/>[PantryView.tsx]"]
end

subgraph group_persistence["User data"]
  node_storage[("Browser persistence<br/>[storage.ts]")]
  node_family_sync["Family sync"]
  node_sheets["Apps Script sync<br/>[sheets.ts]"]
  node_settings["Settings and backup<br/>[SettingsView.tsx]"]
end

subgraph group_platform["Web platform"]
  node_public_recipe["Public recipe page"]
  node_seo["SEO metadata<br/>[seo.ts]"]
  node_pwa_context["PWA state<br/>[PwaContext.tsx]"]
  node_pwa_logic["Install and platform logic<br/>[pwa.ts]"]
  node_install_action["Install action"]
end

node_user(("Home cook"))
node_app["Application<br/>[App.tsx]"]

node_user -->|"uses"| node_app
node_app -->|"loads recipes"| node_catalog
node_app -->|"renders"| node_explorer
node_app -->|"renders"| node_weekly
node_app -->|"renders"| node_monthly
node_app -->|"renders"| node_grocery_view
node_app -->|"renders"| node_timer
node_app -->|"renders"| node_family_sync
node_app -->|"renders"| node_settings
node_app -->|"saves state"| node_storage
node_app -->|"generates list"| node_aggregation
node_explorer -->|"renders"| node_recipe_card
node_explorer -.->|"opens details"| node_recipe_detail
node_explorer -.->|"filters recipes"| node_catalog
node_recipe_detail -->|"renders"| node_recipe_card
node_weekly -->|"uses controls"| node_meal_controls
node_monthly -->|"uses controls"| node_meal_controls
node_grocery_view -->|"aggregates ingredients"| node_aggregation
node_pantry -->|"matches quantities"| node_aggregation
node_grocery_view -.->|"syncs list"| node_sheets
node_family_sync -->|"syncs family data"| node_sheets
node_family_sync -->|"reads settings"| node_storage
node_settings -->|"loads preferences"| node_storage
node_public_recipe -.->|"sets metadata"| node_seo
node_app -.->|"serves recipe pages"| node_public_recipe
node_app -->|"provides install state"| node_pwa_context
node_pwa_context -->|"delegates platform logic"| node_pwa_logic
node_install_action -->|"requests install"| node_pwa_context
node_app -.->|"renders"| node_install_action

click node_app "https://github.com/hany-r-mahmoud/wajba/blob/main/src/App.tsx"
click node_catalog "https://github.com/hany-r-mahmoud/wajba/blob/main/src/data/recipes.ts"
click node_explorer "https://github.com/hany-r-mahmoud/wajba/blob/main/src/components/RecipeExplorer.tsx"
click node_recipe_detail "https://github.com/hany-r-mahmoud/wajba/blob/main/src/components/RecipeDetailModal.tsx"
click node_recipe_card "https://github.com/hany-r-mahmoud/wajba/blob/main/src/components/RecipeCard.tsx"
click node_weekly "https://github.com/hany-r-mahmoud/wajba/blob/main/src/components/WeeklyPlannerView.tsx"
click node_monthly "https://github.com/hany-r-mahmoud/wajba/blob/main/src/components/MonthlyCalendarView.tsx"
click node_meal_controls "https://github.com/hany-r-mahmoud/wajba/blob/main/src/components/MealDisplayControls.tsx"
click node_grocery_view "https://github.com/hany-r-mahmoud/wajba/blob/main/src/components/GroceryListView.tsx"
click node_aggregation "https://github.com/hany-r-mahmoud/wajba/blob/main/src/utils/aggregator.ts"
click node_pantry "https://github.com/hany-r-mahmoud/wajba/blob/main/src/components/PantryView.tsx"
click node_timer "https://github.com/hany-r-mahmoud/wajba/blob/main/src/components/CookingTimerBar.tsx"
click node_storage "https://github.com/hany-r-mahmoud/wajba/blob/main/src/utils/storage.ts"
click node_family_sync "https://github.com/hany-r-mahmoud/wajba/blob/main/src/components/FamilySyncModal.tsx"
click node_sheets "https://github.com/hany-r-mahmoud/wajba/blob/main/src/utils/sheets.ts"
click node_settings "https://github.com/hany-r-mahmoud/wajba/blob/main/src/components/SettingsView.tsx"
click node_public_recipe "https://github.com/hany-r-mahmoud/wajba/blob/main/src/components/PublicRecipePage.tsx"
click node_seo "https://github.com/hany-r-mahmoud/wajba/blob/main/src/utils/seo.ts"
click node_pwa_context "https://github.com/hany-r-mahmoud/wajba/blob/main/src/pwa/PwaContext.tsx"
click node_pwa_logic "https://github.com/hany-r-mahmoud/wajba/blob/main/src/pwa/pwa.ts"
click node_install_action "https://github.com/hany-r-mahmoud/wajba/blob/main/src/components/PwaInstallMenuAction.tsx"

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_weekly,node_monthly,node_meal_controls,node_timer toneBlue
class node_catalog,node_explorer,node_recipe_detail,node_recipe_card toneAmber
class node_grocery_view,node_aggregation,node_pantry toneMint
class node_storage,node_family_sync,node_sheets,node_settings toneRose
class node_public_recipe,node_seo,node_pwa_context,node_pwa_logic,node_install_action,node_user toneIndigo
class node_app toneTeal
```

## Components

### Meal planning

- [Weekly planner](https://github.com/hany-r-mahmoud/wajba/blob/main/src/components/WeeklyPlannerView.tsx): `src/components/WeeklyPlannerView.tsx`
- [Monthly planner](https://github.com/hany-r-mahmoud/wajba/blob/main/src/components/MonthlyCalendarView.tsx): `src/components/MonthlyCalendarView.tsx`
- [Meal controls](https://github.com/hany-r-mahmoud/wajba/blob/main/src/components/MealDisplayControls.tsx): `src/components/MealDisplayControls.tsx`
- [Cooking timers](https://github.com/hany-r-mahmoud/wajba/blob/main/src/components/CookingTimerBar.tsx): `src/components/CookingTimerBar.tsx`

### Recipe experience

- [Recipe catalog](https://github.com/hany-r-mahmoud/wajba/blob/main/src/data/recipes.ts): `src/data/recipes.ts`
- [Recipe explorer](https://github.com/hany-r-mahmoud/wajba/blob/main/src/components/RecipeExplorer.tsx): `src/components/RecipeExplorer.tsx`
- [Recipe details](https://github.com/hany-r-mahmoud/wajba/blob/main/src/components/RecipeDetailModal.tsx): `src/components/RecipeDetailModal.tsx`
- [Recipe card](https://github.com/hany-r-mahmoud/wajba/blob/main/src/components/RecipeCard.tsx): `src/components/RecipeCard.tsx`

### Shopping tools

- [Grocery list](https://github.com/hany-r-mahmoud/wajba/blob/main/src/components/GroceryListView.tsx): `src/components/GroceryListView.tsx`
- [Ingredient aggregation](https://github.com/hany-r-mahmoud/wajba/blob/main/src/utils/aggregator.ts): `src/utils/aggregator.ts`
- [Pantry matching](https://github.com/hany-r-mahmoud/wajba/blob/main/src/components/PantryView.tsx): `src/components/PantryView.tsx`

### User data

- [Browser persistence](https://github.com/hany-r-mahmoud/wajba/blob/main/src/utils/storage.ts): `src/utils/storage.ts`
- [Family sync](https://github.com/hany-r-mahmoud/wajba/blob/main/src/components/FamilySyncModal.tsx): `src/components/FamilySyncModal.tsx`
- [Apps Script sync](https://github.com/hany-r-mahmoud/wajba/blob/main/src/utils/sheets.ts): `src/utils/sheets.ts`
- [Settings and backup](https://github.com/hany-r-mahmoud/wajba/blob/main/src/components/SettingsView.tsx): `src/components/SettingsView.tsx`

### Web platform

- [Public recipe page](https://github.com/hany-r-mahmoud/wajba/blob/main/src/components/PublicRecipePage.tsx): `src/components/PublicRecipePage.tsx`
- [SEO metadata](https://github.com/hany-r-mahmoud/wajba/blob/main/src/utils/seo.ts): `src/utils/seo.ts`
- [PWA state](https://github.com/hany-r-mahmoud/wajba/blob/main/src/pwa/PwaContext.tsx): `src/pwa/PwaContext.tsx`
- [Install and platform logic](https://github.com/hany-r-mahmoud/wajba/blob/main/src/pwa/pwa.ts): `src/pwa/pwa.ts`
- [Install action](https://github.com/hany-r-mahmoud/wajba/blob/main/src/components/PwaInstallMenuAction.tsx): `src/components/PwaInstallMenuAction.tsx`

### Other components

- **Home cook**
- [Application](https://github.com/hany-r-mahmoud/wajba/blob/main/src/App.tsx): `src/App.tsx`

## Connections

- Home cook → Application: uses
- Application → Recipe catalog: loads recipes (evidence: `src/App.tsx`)
- Application → Recipe explorer: renders (evidence: `src/App.tsx`)
- Application → Weekly planner: renders (evidence: `src/App.tsx`)
- Application → Monthly planner: renders (evidence: `src/App.tsx`)
- Application → Grocery list: renders (evidence: `src/App.tsx`)
- Application → Cooking timers: renders (evidence: `src/App.tsx`)
- Application → Family sync: renders (evidence: `src/App.tsx`)
- Application → Settings and backup: renders (evidence: `src/App.tsx`)
- Application → Browser persistence: saves state (evidence: `src/App.tsx`)
- Application → Ingredient aggregation: generates list (evidence: `src/App.tsx`)
- Recipe explorer → Recipe card: renders (evidence: `src/components/RecipeExplorer.tsx`)
- Recipe explorer → Recipe details: opens details
- Recipe explorer → Recipe catalog: filters recipes
- Recipe details → Recipe card: renders (evidence: `src/components/RecipeDetailModal.tsx`)
- Weekly planner → Meal controls: uses controls (evidence: `src/components/WeeklyPlannerView.tsx`)
- Monthly planner → Meal controls: uses controls (evidence: `src/components/MonthlyCalendarView.tsx`)
- Grocery list → Ingredient aggregation: aggregates ingredients (evidence: `src/components/GroceryListView.tsx`)
- Pantry matching → Ingredient aggregation: matches quantities (evidence: `src/components/PantryView.tsx`)
- Grocery list → Apps Script sync: syncs list (evidence: `src/components/GroceryListView.tsx`)
- Family sync → Apps Script sync: syncs family data (evidence: `src/components/FamilySyncModal.tsx`)
- Family sync → Browser persistence: reads settings (evidence: `src/components/FamilySyncModal.tsx`)
- Settings and backup → Browser persistence: loads preferences (evidence: `src/components/SettingsView.tsx`)
- Public recipe page → SEO metadata: sets metadata
- Application → Public recipe page: serves recipe pages (evidence: `src/App.tsx`)
- Application → PWA state: provides install state (evidence: `src/main.tsx`)
- PWA state → Install and platform logic: delegates platform logic (evidence: `src/pwa/PwaContext.tsx`)
- Install action → PWA state: requests install (evidence: `src/components/PwaInstallMenuAction.tsx`)
- Application → Install action: renders
