# sinful1992/shopping-list-app architecture

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

- Interactive diagram: https://gitdiagram.com/sinful1992/shopping-list-app
- Repository: https://github.com/sinful1992/shopping-list-app

## Overview

Family Shopping List is an Android family shopping app centered on shared, offline-capable lists and receipt-backed spending history. Members join or create a family, add/check items, sync changes, and can photograph a receipt for OCR and later history, budget, and price analysis. The graph preserves authentication, urgent-item notifications, subscription/ads, analytics, and receipt capabilities documented by the README. Some branches are represented by exact directories because their implementation files were not sampled; those links are omitted where call ownership is not evidenced.

Main entry points: [`App.tsx`](https://github.com/sinful1992/shopping-list-app/blob/master/App.tsx) (App navigation), [`src/services/LocalStorageManager.ts`](https://github.com/sinful1992/shopping-list-app/blob/master/src/services/LocalStorageManager.ts) (Local storage facade), [`src/screens/lists`](https://github.com/sinful1992/shopping-list-app/tree/master/src/screens/lists) (List screens), [`src/services/ItemManager.ts`](https://github.com/sinful1992/shopping-list-app/blob/master/src/services/ItemManager.ts) (Item management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Mobile app"]
  node_app_shell["App navigation<br/>[App.tsx]"]
  node_auth["Authentication and family"]
  node_login_ui["Sign-in and family screens"]
  node_settings["Settings"]
end

subgraph group_lists["Shared shopping"]
  node_list_ui["List screens"]
  node_list_manager["List management"]
  node_item_manager["Item management<br/>[ItemManager.ts]"]
  node_list_hook["List subscriptions"]
  node_sync["Offline sync engine<br/>[SyncEngine.ts]"]
  node_sync_listener["Realtime sync listener"]
  node_local_storage["Local storage facade"]
  node_sqlite[("Local database<br/>[database.ts]")]
  node_urgent["Urgent items"]
end

subgraph group_money["Receipts and spending"]
  node_receipt_capture["Receipt capture"]
  node_receipt_ocr["Receipt OCR"]
  node_receipt_ui["Receipt screens"]
  node_image_storage["Receipt image storage"]
  node_history["Shopping history"]
  node_price_history["Price history"]
  node_budget["Budget analysis"]
  node_analytics["Spending analytics"]
end

subgraph group_platform["Cloud and services"]
  node_notifications["Notifications"]
  node_supabase["Supabase edge functions"]
  node_firebase[("Firebase backend")]
end

subgraph group_monetization["Plans and ads"]
  node_subscriptions["Subscription management"]
  node_ads["Ads and consent<br/>[AdMobContext.tsx]"]
end

node_member(("Family member"))

node_member -->|"uses"| node_app_shell
node_app_shell -->|"initializes"| node_auth
node_app_shell -->|"routes to"| node_login_ui
node_app_shell -->|"routes to"| node_list_ui
node_list_ui -->|"subscribes via"| node_list_hook
node_list_ui -->|"manages items"| node_item_manager
node_list_ui -->|"manages lists"| node_list_manager
node_list_hook -->|"loads lists"| node_list_manager
node_list_hook -->|"subscribes to"| node_sync_listener
node_list_hook -->|"uses"| node_image_storage
node_list_manager -->|"persists lists"| node_local_storage
node_list_manager -->|"queues sync"| node_sync
node_item_manager -->|"persists items"| node_local_storage
node_item_manager -->|"queues sync"| node_sync
node_item_manager -->|"records prices"| node_price_history
node_sync -->|"reads queue data"| node_local_storage
node_local_storage -->|"uses database"| node_sqlite
node_urgent -.->|"stores urgent items"| node_local_storage
node_urgent -.->|"upserts urgent"| node_supabase
node_supabase -.->|"sends alerts"| node_notifications
node_app_shell -->|"initializes"| node_notifications
node_receipt_ui -.->|"captures receipt"| node_receipt_capture
node_receipt_ui -.->|"requests OCR"| node_receipt_ocr
node_receipt_ui -.->|"stores image"| node_image_storage
node_receipt_ocr -.->|"uses OCR proxy"| node_supabase
node_image_storage -->|"uploads image"| node_firebase
node_history -.->|"reads history"| node_local_storage
node_budget -.->|"analyzes spending"| node_analytics
node_analytics -.->|"uses price data"| node_price_history
node_app_shell -->|"provides context"| node_subscriptions
node_subscriptions -->|"reads family tier"| node_firebase
node_subscriptions -.->|"uses client"| node_supabase
node_app_shell -->|"provides context"| node_ads
node_ads -->|"checks subscription"| node_subscriptions
node_app_shell -->|"routes to"| node_settings

click node_app_shell "https://github.com/sinful1992/shopping-list-app/blob/master/App.tsx"
click node_auth "https://github.com/sinful1992/shopping-list-app/blob/master/src/services/AuthenticationModule.ts"
click node_login_ui "https://github.com/sinful1992/shopping-list-app/tree/master/src/screens/auth"
click node_list_ui "https://github.com/sinful1992/shopping-list-app/tree/master/src/screens/lists"
click node_list_manager "https://github.com/sinful1992/shopping-list-app/blob/master/src/services/ShoppingListManager.ts"
click node_item_manager "https://github.com/sinful1992/shopping-list-app/blob/master/src/services/ItemManager.ts"
click node_list_hook "https://github.com/sinful1992/shopping-list-app/blob/master/src/hooks/useShoppingLists.ts"
click node_sync "https://github.com/sinful1992/shopping-list-app/blob/master/src/services/SyncEngine.ts"
click node_sync_listener "https://github.com/sinful1992/shopping-list-app/blob/master/src/services/FirebaseSyncListener.ts"
click node_local_storage "https://github.com/sinful1992/shopping-list-app/blob/master/src/services/LocalStorageManager.ts"
click node_sqlite "https://github.com/sinful1992/shopping-list-app/blob/master/src/services/storage/database.ts"
click node_urgent "https://github.com/sinful1992/shopping-list-app/blob/master/src/services/UrgentItemManager.ts"
click node_notifications "https://github.com/sinful1992/shopping-list-app/blob/master/src/services/NotificationManager.ts"
click node_receipt_capture "https://github.com/sinful1992/shopping-list-app/blob/master/src/services/ReceiptCaptureModule.ts"
click node_receipt_ocr "https://github.com/sinful1992/shopping-list-app/blob/master/src/services/ReceiptOCRService.ts"
click node_receipt_ui "https://github.com/sinful1992/shopping-list-app/tree/master/src/screens/receipts"
click node_image_storage "https://github.com/sinful1992/shopping-list-app/blob/master/src/services/ImageStorageManager.ts"
click node_history "https://github.com/sinful1992/shopping-list-app/tree/master/src/screens/history"
click node_price_history "https://github.com/sinful1992/shopping-list-app/blob/master/src/services/PriceHistoryService.ts"
click node_budget "https://github.com/sinful1992/shopping-list-app/tree/master/src/screens/budget"
click node_analytics "https://github.com/sinful1992/shopping-list-app/tree/master/src/screens/analytics"
click node_supabase "https://github.com/sinful1992/shopping-list-app/tree/master/supabase/functions"
click node_subscriptions "https://github.com/sinful1992/shopping-list-app/blob/master/src/contexts/RevenueCatContext.tsx"
click node_ads "https://github.com/sinful1992/shopping-list-app/blob/master/src/contexts/AdMobContext.tsx"
click node_settings "https://github.com/sinful1992/shopping-list-app/tree/master/src/screens/settings"

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_shell,node_auth,node_login_ui,node_settings toneBlue
class node_list_ui,node_list_manager,node_item_manager,node_list_hook,node_sync,node_sync_listener,node_local_storage,node_sqlite,node_urgent toneAmber
class node_receipt_capture,node_receipt_ocr,node_receipt_ui,node_image_storage,node_history,node_price_history,node_budget,node_analytics toneMint
class node_notifications,node_supabase,node_firebase toneRose
class node_subscriptions,node_ads,node_member toneIndigo
```

## Components

### Mobile app

- [App navigation](https://github.com/sinful1992/shopping-list-app/blob/master/App.tsx): `App.tsx`
- [Authentication and family](https://github.com/sinful1992/shopping-list-app/blob/master/src/services/AuthenticationModule.ts): `src/services/AuthenticationModule.ts`
- [Sign-in and family screens](https://github.com/sinful1992/shopping-list-app/tree/master/src/screens/auth): `src/screens/auth`
- [Settings](https://github.com/sinful1992/shopping-list-app/tree/master/src/screens/settings): `src/screens/settings`

### Shared shopping

- [List screens](https://github.com/sinful1992/shopping-list-app/tree/master/src/screens/lists): `src/screens/lists`
- [List management](https://github.com/sinful1992/shopping-list-app/blob/master/src/services/ShoppingListManager.ts): `src/services/ShoppingListManager.ts`
- [Item management](https://github.com/sinful1992/shopping-list-app/blob/master/src/services/ItemManager.ts): `src/services/ItemManager.ts`
- [List subscriptions](https://github.com/sinful1992/shopping-list-app/blob/master/src/hooks/useShoppingLists.ts): `src/hooks/useShoppingLists.ts`
- [Offline sync engine](https://github.com/sinful1992/shopping-list-app/blob/master/src/services/SyncEngine.ts): `src/services/SyncEngine.ts`
- [Realtime sync listener](https://github.com/sinful1992/shopping-list-app/blob/master/src/services/FirebaseSyncListener.ts): `src/services/FirebaseSyncListener.ts`
- [Local storage facade](https://github.com/sinful1992/shopping-list-app/blob/master/src/services/LocalStorageManager.ts): `src/services/LocalStorageManager.ts`
- [Local database](https://github.com/sinful1992/shopping-list-app/blob/master/src/services/storage/database.ts): `src/services/storage/database.ts`
- [Urgent items](https://github.com/sinful1992/shopping-list-app/blob/master/src/services/UrgentItemManager.ts): `src/services/UrgentItemManager.ts`

### Receipts and spending

- [Receipt capture](https://github.com/sinful1992/shopping-list-app/blob/master/src/services/ReceiptCaptureModule.ts): `src/services/ReceiptCaptureModule.ts`
- [Receipt OCR](https://github.com/sinful1992/shopping-list-app/blob/master/src/services/ReceiptOCRService.ts): `src/services/ReceiptOCRService.ts`
- [Receipt screens](https://github.com/sinful1992/shopping-list-app/tree/master/src/screens/receipts): `src/screens/receipts`
- [Receipt image storage](https://github.com/sinful1992/shopping-list-app/blob/master/src/services/ImageStorageManager.ts): `src/services/ImageStorageManager.ts`
- [Shopping history](https://github.com/sinful1992/shopping-list-app/tree/master/src/screens/history): `src/screens/history`
- [Price history](https://github.com/sinful1992/shopping-list-app/blob/master/src/services/PriceHistoryService.ts): `src/services/PriceHistoryService.ts`
- [Budget analysis](https://github.com/sinful1992/shopping-list-app/tree/master/src/screens/budget): `src/screens/budget`
- [Spending analytics](https://github.com/sinful1992/shopping-list-app/tree/master/src/screens/analytics): `src/screens/analytics`

### Cloud and services

- [Notifications](https://github.com/sinful1992/shopping-list-app/blob/master/src/services/NotificationManager.ts): `src/services/NotificationManager.ts`
- [Supabase edge functions](https://github.com/sinful1992/shopping-list-app/tree/master/supabase/functions): `supabase/functions`
- **Firebase backend**

### Plans and ads

- [Subscription management](https://github.com/sinful1992/shopping-list-app/blob/master/src/contexts/RevenueCatContext.tsx): `src/contexts/RevenueCatContext.tsx`
- [Ads and consent](https://github.com/sinful1992/shopping-list-app/blob/master/src/contexts/AdMobContext.tsx): `src/contexts/AdMobContext.tsx`

### Other components

- **Family member**

## Connections

- Family member → App navigation: uses (evidence: `README.md`)
- App navigation → Authentication and family: initializes (evidence: `App.tsx`)
- App navigation → Sign-in and family screens: routes to (evidence: `App.tsx`)
- App navigation → List screens: routes to (evidence: `App.tsx`)
- List screens → List subscriptions: subscribes via (evidence: `src/screens/lists/ListDetailScreen.tsx`)
- List screens → Item management: manages items (evidence: `src/screens/lists/ListDetailScreen.tsx`)
- List screens → List management: manages lists (evidence: `src/screens/lists/ListDetailScreen.tsx`)
- List subscriptions → List management: loads lists (evidence: `src/hooks/useShoppingLists.ts`)
- List subscriptions → Realtime sync listener: subscribes to (evidence: `src/hooks/useShoppingLists.ts`)
- List subscriptions → Receipt image storage: uses (evidence: `src/hooks/useShoppingLists.ts`)
- List management → Local storage facade: persists lists (evidence: `src/services/ShoppingListManager.ts`)
- List management → Offline sync engine: queues sync (evidence: `src/services/ShoppingListManager.ts`)
- Item management → Local storage facade: persists items (evidence: `src/services/ItemManager.ts`)
- Item management → Offline sync engine: queues sync (evidence: `src/services/ItemManager.ts`)
- Item management → Price history: records prices (evidence: `src/services/ItemManager.ts`)
- Offline sync engine → Local storage facade: reads queue data (evidence: `src/services/SyncEngine.ts`)
- Local storage facade → Local database: uses database (evidence: `src/services/storage/database.ts`)
- Urgent items → Local storage facade: stores urgent items
- Urgent items → Supabase edge functions: upserts urgent
- Supabase edge functions → Notifications: sends alerts
- App navigation → Notifications: initializes (evidence: `App.tsx`)
- Receipt screens → Receipt capture: captures receipt
- Receipt screens → Receipt OCR: requests OCR
- Receipt screens → Receipt image storage: stores image
- Receipt OCR → Supabase edge functions: uses OCR proxy
- Receipt image storage → Firebase backend: uploads image (evidence: `src/services/ImageStorageManager.ts`)
- Shopping history → Local storage facade: reads history
- Budget analysis → Spending analytics: analyzes spending
- Spending analytics → Price history: uses price data
- App navigation → Subscription management: provides context (evidence: `App.tsx`)
- Subscription management → Firebase backend: reads family tier (evidence: `src/contexts/RevenueCatContext.tsx`)
- Subscription management → Supabase edge functions: uses client
- App navigation → Ads and consent: provides context (evidence: `App.tsx`)
- Ads and consent → Subscription management: checks subscription (evidence: `src/contexts/AdMobContext.tsx`)
- App navigation → Settings: routes to (evidence: `App.tsx`)