# achyuth098/homecart architecture

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

- Interactive diagram: https://gitdiagram.com/achyuth098/homecart
- Repository: https://github.com/achyuth098/homecart

## Overview

HomeCart is a shared apartment grocery-list app. The workflow starts with anonymous phone sign-in, then creating or joining an apartment, managing needed and bought items, and syncing changes across roommates. The graph includes offline caching and queued edits, apartment membership, invitations, and database-enforced access. Runtime wiring is grounded in the sampled React modules; the SQL schema and policies are represented at their documented path, but their details were not sampled.

Main entry points: [`src/App.jsx`](https://github.com/achyuth098/homecart/blob/main/src/App.jsx) (App shell), [`src/supabase.js`](https://github.com/achyuth098/homecart/blob/main/src/supabase.js) (Supabase client), [`src/useList.js`](https://github.com/achyuth098/homecart/blob/main/src/useList.js) (List operations), [`src/ListScreen.jsx`](https://github.com/achyuth098/homecart/blob/main/src/ListScreen.jsx) (Shopping list UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["App experience"]
  node_app["App shell<br/>[App.jsx]"]
  node_welcome["Apartment entry<br/>[Welcome.jsx]"]
  node_list_screen["Shopping list UI<br/>[ListScreen.jsx]"]
end

subgraph group_sync["List and offline sync"]
  node_list_hook["List operations<br/>[useList.js]"]
  node_local_storage[("Local cache<br/>[storage.js]")]
end

subgraph group_backend["Supabase backend"]
  node_supabase_client["Supabase client<br/>[supabase.js]"]
  node_auth["Anonymous auth"]
  node_database[("Apartment data")]
  node_realtime["Realtime events"]
end

subgraph group_pwa["Install and cache"]
  node_service_worker["App shell cache<br/>[sw.js]"]
  node_manifest["Install metadata"]
end

node_roommate(("Roommate"))
node_browser(("Phone browser"))

node_roommate -->|"opens"| node_app
node_app -->|"checks config"| node_supabase_client
node_app -->|"signs in"| node_auth
node_auth -->|"uses client"| node_supabase_client
node_app -->|"loads membership"| node_database
node_app -->|"loads membership"| node_local_storage
node_app -->|"shows entry"| node_welcome
node_welcome -->|"creates or joins"| node_supabase_client
node_supabase_client -->|"calls apartment RPCs"| node_database
node_app -->|"shows list"| node_list_screen
node_list_screen -->|"requests list actions"| node_list_hook
node_list_hook -->|"fetches and writes"| node_supabase_client
node_list_hook -->|"caches and queues"| node_local_storage
node_list_hook -->|"subscribes"| node_realtime
node_realtime -->|"dispatches changes"| node_list_hook
node_supabase_client -->|"reads and writes"| node_database
node_list_screen -->|"shares invite"| node_roommate
node_browser -->|"registers"| node_service_worker
node_service_worker -->|"serves cached shell"| node_browser
node_browser -->|"reads install metadata"| node_manifest

click node_app "https://github.com/achyuth098/homecart/blob/main/src/App.jsx"
click node_welcome "https://github.com/achyuth098/homecart/blob/main/src/Welcome.jsx"
click node_list_screen "https://github.com/achyuth098/homecart/blob/main/src/ListScreen.jsx"
click node_list_hook "https://github.com/achyuth098/homecart/blob/main/src/useList.js"
click node_local_storage "https://github.com/achyuth098/homecart/blob/main/src/storage.js"
click node_supabase_client "https://github.com/achyuth098/homecart/blob/main/src/supabase.js"
click node_database "https://github.com/achyuth098/homecart/blob/main/supabase/01_phase1_setup.sql"
click node_service_worker "https://github.com/achyuth098/homecart/blob/main/public/sw.js"
click node_manifest "https://github.com/achyuth098/homecart/blob/main/public/manifest.webmanifest"

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_welcome,node_list_screen,node_browser toneBlue
class node_list_hook,node_local_storage toneAmber
class node_supabase_client,node_auth,node_database,node_realtime toneMint
class node_service_worker,node_manifest toneRose
class node_roommate toneIndigo
```

## Components

### App experience

- [App shell](https://github.com/achyuth098/homecart/blob/main/src/App.jsx): `src/App.jsx`
- [Apartment entry](https://github.com/achyuth098/homecart/blob/main/src/Welcome.jsx): `src/Welcome.jsx`
- [Shopping list UI](https://github.com/achyuth098/homecart/blob/main/src/ListScreen.jsx): `src/ListScreen.jsx`

### List and offline sync

- [List operations](https://github.com/achyuth098/homecart/blob/main/src/useList.js): `src/useList.js`
- [Local cache](https://github.com/achyuth098/homecart/blob/main/src/storage.js): `src/storage.js`

### Supabase backend

- [Supabase client](https://github.com/achyuth098/homecart/blob/main/src/supabase.js): `src/supabase.js`
- **Anonymous auth**
- [Apartment data](https://github.com/achyuth098/homecart/blob/main/supabase/01_phase1_setup.sql): `supabase/01_phase1_setup.sql`
- **Realtime events**

### Install and cache

- [App shell cache](https://github.com/achyuth098/homecart/blob/main/public/sw.js): `public/sw.js`
- [Install metadata](https://github.com/achyuth098/homecart/blob/main/public/manifest.webmanifest): `public/manifest.webmanifest`

### Other components

- **Roommate**
- **Phone browser**

## Connections

- Roommate → App shell: opens
- App shell → Supabase client: checks config
- App shell → Anonymous auth: signs in
- Anonymous auth → Supabase client: uses client
- App shell → Apartment data: loads membership
- App shell → Local cache: loads membership
- App shell → Apartment entry: shows entry
- Apartment entry → Supabase client: creates or joins
- Supabase client → Apartment data: calls apartment RPCs
- App shell → Shopping list UI: shows list
- Shopping list UI → List operations: requests list actions
- List operations → Supabase client: fetches and writes
- List operations → Local cache: caches and queues
- List operations → Realtime events: subscribes
- Realtime events → List operations: dispatches changes
- Supabase client → Apartment data: reads and writes
- Shopping list UI → Roommate: shares invite
- Phone browser → App shell cache: registers
- App shell cache → Phone browser: serves cached shell
- Phone browser → Install metadata: reads install metadata