# nowtyler/family-wishlist architecture

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

- Interactive diagram: https://gitdiagram.com/nowtyler/family-wishlist
- Repository: https://github.com/nowtyler/family-wishlist
- Video tour (about a minute): https://gitdiagram.com/nowtyler/family-wishlist/video

## Overview

Family Wishlist is a full-stack app for managing personal and shared gift lists, coordinating purchases across households, and administering family accounts and system data. The principal flow is a family member signs in, views or edits wishlists, and coordinates gifts; React screens call the FastAPI API, which applies domain logic and persists records. The README documents additional capabilities whose individual implementations are not fully represented in the excerpts; those are shown at subsystem level where the tree supports a path. Calls involving unsampled routes are not expanded beyond documented API boundaries.

Main entry points: [`frontend/src/services/api.js`](https://github.com/nowtyler/family-wishlist/blob/main/frontend/src/services/api.js) (Frontend API client), [`backend/app/crud.py`](https://github.com/nowtyler/family-wishlist/blob/main/backend/app/crud.py) (Data operations), [`backend/app/main.py`](https://github.com/nowtyler/family-wishlist/blob/main/backend/app/main.py) (Admin operations), [`frontend/src/App.jsx`](https://github.com/nowtyler/family-wishlist/blob/main/frontend/src/App.jsx) (App router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_app["App router<br/>[App.jsx]"]
  node_dashboard["Wishlist dashboard"]
  node_itemform["Item entry<br/>[AddItemForm.jsx]"]
  node_sharedui["Shared list manager"]
  node_householdui["Household manager"]
  node_adminui["Admin console<br/>[AdminPage.jsx]"]
  node_api["Frontend API client<br/>[api.js]"]
end

subgraph group_wishlist["Wishlist and gifting"]
  node_wishlistapi["Wishlist API<br/>[main.py]"]
  node_sharedapi["Shared list API<br/>[main.py]"]
  node_cartapi["Gift coordination API<br/>[main.py]"]
  node_scraping["URL product import<br/>[url_scraper.py]"]
end

subgraph group_family["Family and identity"]
  node_familyapi["Household API<br/>[main.py]"]
  node_authapi["Authentication API<br/>[main.py]"]
  node_userauth["Account authentication"]
end

subgraph group_platform["Administration and services"]
  node_email["Email delivery<br/>[email_service.py]"]
  node_adminapi["Admin operations<br/>[main.py]"]
  node_backup["Backup service<br/>[backup_service.py]"]
  node_migration["Schema migrations"]
end

subgraph group_storage["Persistence"]
  node_crud["Data operations<br/>[crud.py]"]
  node_models["Domain records<br/>[models.py]"]
  node_database[("Application database<br/>[database.py]")]
end

node_member(("Family member"))
node_external(("Product websites"))
node_captcha{{"Turnstile"}}

node_member -->|"uses"| node_app
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_adminui
node_dashboard -->|"requests data"| node_api
node_itemform -->|"submits items"| node_api
node_sharedui -->|"manages lists"| node_api
node_householdui -->|"manages households"| node_api
node_adminui -->|"requests administration"| node_api
node_api -->|"HTTP requests"| node_wishlistapi
node_api -->|"HTTP requests"| node_sharedapi
node_api -->|"HTTP requests"| node_cartapi
node_api -->|"HTTP requests"| node_familyapi
node_api -->|"HTTP requests"| node_authapi
node_api -->|"HTTP requests"| node_adminapi
node_wishlistapi -->|"reads and writes"| node_crud
node_sharedapi -->|"reads and writes"| node_crud
node_cartapi -->|"reads and writes"| node_crud
node_familyapi -->|"reads and writes"| node_crud
node_authapi -->|"authenticates"| node_userauth
node_userauth -->|"sends reset email"| node_email
node_authapi -.->|"validates challenge"| node_captcha
node_wishlistapi -->|"imports product details"| node_scraping
node_scraping -.->|"fetches product page"| node_external
node_adminapi -->|"manages backups"| node_backup
node_adminapi -->|"manages schema"| node_migration
node_adminapi -->|"reads and writes"| node_crud
node_crud -->|"uses records"| node_models
node_models -->|"maps to tables"| node_database
node_crud -->|"persists data"| node_database

click node_app "https://github.com/nowtyler/family-wishlist/blob/main/frontend/src/App.jsx"
click node_dashboard "https://github.com/nowtyler/family-wishlist/blob/main/frontend/src/components/DashboardScreen.jsx"
click node_itemform "https://github.com/nowtyler/family-wishlist/blob/main/frontend/src/components/AddItemForm.jsx"
click node_sharedui "https://github.com/nowtyler/family-wishlist/blob/main/frontend/src/components/SharedWishlistManager.jsx"
click node_householdui "https://github.com/nowtyler/family-wishlist/blob/main/frontend/src/components/UserHouseholdManager.jsx"
click node_adminui "https://github.com/nowtyler/family-wishlist/blob/main/frontend/src/components/AdminPage.jsx"
click node_api "https://github.com/nowtyler/family-wishlist/blob/main/frontend/src/services/api.js"
click node_wishlistapi "https://github.com/nowtyler/family-wishlist/blob/main/backend/app/main.py"
click node_sharedapi "https://github.com/nowtyler/family-wishlist/blob/main/backend/app/main.py"
click node_cartapi "https://github.com/nowtyler/family-wishlist/blob/main/backend/app/main.py"
click node_scraping "https://github.com/nowtyler/family-wishlist/blob/main/backend/app/services/url_scraper.py"
click node_familyapi "https://github.com/nowtyler/family-wishlist/blob/main/backend/app/main.py"
click node_authapi "https://github.com/nowtyler/family-wishlist/blob/main/backend/app/main.py"
click node_userauth "https://github.com/nowtyler/family-wishlist/blob/main/backend/app/services/user_auth_service.py"
click node_email "https://github.com/nowtyler/family-wishlist/blob/main/backend/app/services/email_service.py"
click node_adminapi "https://github.com/nowtyler/family-wishlist/blob/main/backend/app/main.py"
click node_backup "https://github.com/nowtyler/family-wishlist/blob/main/backend/app/services/backup_service.py"
click node_migration "https://github.com/nowtyler/family-wishlist/blob/main/backend/app/services/migration_service.py"
click node_crud "https://github.com/nowtyler/family-wishlist/blob/main/backend/app/crud.py"
click node_models "https://github.com/nowtyler/family-wishlist/blob/main/backend/app/models.py"
click node_database "https://github.com/nowtyler/family-wishlist/blob/main/backend/app/database.py"

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_dashboard,node_itemform,node_sharedui,node_householdui,node_adminui,node_api toneBlue
class node_wishlistapi,node_sharedapi,node_cartapi,node_scraping toneAmber
class node_familyapi,node_authapi,node_userauth toneMint
class node_email,node_adminapi,node_backup,node_migration toneRose
class node_crud,node_models,node_database,node_member,node_external,node_captcha toneIndigo
```

## Components

### Web client

- [App router](https://github.com/nowtyler/family-wishlist/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Wishlist dashboard](https://github.com/nowtyler/family-wishlist/blob/main/frontend/src/components/DashboardScreen.jsx): `frontend/src/components/DashboardScreen.jsx`
- [Item entry](https://github.com/nowtyler/family-wishlist/blob/main/frontend/src/components/AddItemForm.jsx): `frontend/src/components/AddItemForm.jsx`
- [Shared list manager](https://github.com/nowtyler/family-wishlist/blob/main/frontend/src/components/SharedWishlistManager.jsx): `frontend/src/components/SharedWishlistManager.jsx`
- [Household manager](https://github.com/nowtyler/family-wishlist/blob/main/frontend/src/components/UserHouseholdManager.jsx): `frontend/src/components/UserHouseholdManager.jsx`
- [Admin console](https://github.com/nowtyler/family-wishlist/blob/main/frontend/src/components/AdminPage.jsx): `frontend/src/components/AdminPage.jsx`
- [Frontend API client](https://github.com/nowtyler/family-wishlist/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`

### Wishlist and gifting

- [Wishlist API](https://github.com/nowtyler/family-wishlist/blob/main/backend/app/main.py): `backend/app/main.py`
- [Shared list API](https://github.com/nowtyler/family-wishlist/blob/main/backend/app/main.py): `backend/app/main.py`
- [Gift coordination API](https://github.com/nowtyler/family-wishlist/blob/main/backend/app/main.py): `backend/app/main.py`
- [URL product import](https://github.com/nowtyler/family-wishlist/blob/main/backend/app/services/url_scraper.py): `backend/app/services/url_scraper.py`

### Family and identity

- [Household API](https://github.com/nowtyler/family-wishlist/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication API](https://github.com/nowtyler/family-wishlist/blob/main/backend/app/main.py): `backend/app/main.py`
- [Account authentication](https://github.com/nowtyler/family-wishlist/blob/main/backend/app/services/user_auth_service.py): `backend/app/services/user_auth_service.py`

### Administration and services

- [Email delivery](https://github.com/nowtyler/family-wishlist/blob/main/backend/app/services/email_service.py): `backend/app/services/email_service.py`
- [Admin operations](https://github.com/nowtyler/family-wishlist/blob/main/backend/app/main.py): `backend/app/main.py`
- [Backup service](https://github.com/nowtyler/family-wishlist/blob/main/backend/app/services/backup_service.py): `backend/app/services/backup_service.py`
- [Schema migrations](https://github.com/nowtyler/family-wishlist/blob/main/backend/app/services/migration_service.py): `backend/app/services/migration_service.py`

### Persistence

- [Data operations](https://github.com/nowtyler/family-wishlist/blob/main/backend/app/crud.py): `backend/app/crud.py`
- [Domain records](https://github.com/nowtyler/family-wishlist/blob/main/backend/app/models.py): `backend/app/models.py`
- [Application database](https://github.com/nowtyler/family-wishlist/blob/main/backend/app/database.py): `backend/app/database.py`

### Other components

- **Family member**
- **Product websites**
- **Turnstile**

## Connections

- Family member → App router: uses
- App router → Wishlist dashboard: routes to
- App router → Admin console: routes to
- Wishlist dashboard → Frontend API client: requests data
- Item entry → Frontend API client: submits items
- Shared list manager → Frontend API client: manages lists
- Household manager → Frontend API client: manages households
- Admin console → Frontend API client: requests administration
- Frontend API client → Wishlist API: HTTP requests
- Frontend API client → Shared list API: HTTP requests
- Frontend API client → Gift coordination API: HTTP requests
- Frontend API client → Household API: HTTP requests
- Frontend API client → Authentication API: HTTP requests
- Frontend API client → Admin operations: HTTP requests
- Wishlist API → Data operations: reads and writes
- Shared list API → Data operations: reads and writes
- Gift coordination API → Data operations: reads and writes
- Household API → Data operations: reads and writes
- Authentication API → Account authentication: authenticates
- Account authentication → Email delivery: sends reset email
- Authentication API → Turnstile: validates challenge
- Wishlist API → URL product import: imports product details
- URL product import → Product websites: fetches product page
- Admin operations → Backup service: manages backups
- Admin operations → Schema migrations: manages schema
- Admin operations → Data operations: reads and writes
- Data operations → Domain records: uses records
- Domain records → Application database: maps to tables
- Data operations → Application database: persists data