# edm00/luvfitsv1 architecture

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

- Interactive diagram: https://gitdiagram.com/edm00/luvfitsv1
- Repository: https://github.com/edm00/luvfitsv1

## Overview

Luvfits is a clothing-product collector and outfit discovery app. Its documented refresh workflow gathers retailer listings, classifies and tags products, stores them, then prepares compatible outfits; users browse or search outfits through the API and see them in the React app. The sampled API search handler reads stored outfits and applies a simple vibe filter; it does not call the embedding service, despite the README’s semantic-search description. Refresh-worker internals and several API sections were not sampled, so those documented connections are shown only where supported.

Main entry points: [`backend/scrapers/scraper_manager.py`](https://github.com/edm00/luvfitsv1/blob/main/backend/scrapers/scraper_manager.py) (Scraper manager), [`backend/main.py`](https://github.com/edm00/luvfitsv1/blob/main/backend/main.py) (FastAPI), [`backend/database/db.py`](https://github.com/edm00/luvfitsv1/blob/main/backend/database/db.py) (MongoDB client), [`backend/scrapers/base_scraper.py`](https://github.com/edm00/luvfitsv1/blob/main/backend/scrapers/base_scraper.py) (Scrape base)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_app["App coordinator<br/>[App.jsx]"]
  node_searchbar["Vibe input<br/>[SearchBar.jsx]"]
  node_display["Outfit display<br/>[OutfitDisplay.jsx]"]
end

subgraph group_api["API and orchestration"]
  node_api["FastAPI<br/>[main.py]"]
  node_worker["Refresh worker<br/>[refresh_worker.py]"]
end

subgraph group_acquisition["Product acquisition"]
  node_manager["Scraper manager<br/>[scraper_manager.py]"]
  node_base["Scrape base<br/>[base_scraper.py]"]
  node_hm["H&amp;M scraper<br/>[hm_scraper.py]"]
  node_amazon["Amazon scraper<br/>[amazon_scraper.py]"]
  node_nordstrom["Nordstrom scraper"]
  node_taxonomy["Taxonomy mapping<br/>[google_taxonomy.py]"]
end

subgraph group_matching["Outfit matching"]
  node_embeddings["Embedding service"]
  node_matcher["Outfit matcher<br/>[outfit_matcher.py]"]
  node_builder["Outfit builder<br/>[outfit_builder.py]"]
  node_searchlogic["Legacy search logic<br/>[search_logic.py]"]
end

subgraph group_persistence["Data storage"]
  node_models["Product and outfit models<br/>[models.py]"]
  node_dbclient["MongoDB client<br/>[db.py]"]
  node_mongodb[("MongoDB")]
end

node_shopper(("Shopper"))
node_scrapedo["Scrape.do"]

node_shopper -->|"enters vibe"| node_searchbar
node_searchbar -->|"submits query"| node_app
node_app -->|"requests outfits"| node_api
node_api -->|"reads outfits"| node_dbclient
node_api -->|"reads products"| node_dbclient
node_api -->|"starts and stops"| node_worker
node_api -->|"triggers refresh"| node_manager
node_app -->|"renders result"| node_display
node_api -->|"returns response"| node_app
node_manager -->|"dispatches scrape"| node_hm
node_manager -->|"dispatches scrape"| node_amazon
node_manager -->|"dispatches scrape"| node_nordstrom
node_hm -->|"uses scraping"| node_base
node_amazon -->|"uses scraping"| node_base
node_nordstrom -->|"uses scraping"| node_base
node_base -.->|"fetches pages"| node_scrapedo
node_manager -->|"stores products and jobs"| node_dbclient
node_manager -->|"constructs records"| node_models
node_dbclient -->|"reads and writes"| node_mongodb
node_worker -->|"runs refresh"| node_manager
node_worker -->|"generates embeddings"| node_embeddings
node_worker -->|"generates outfits"| node_matcher
node_matcher -->|"loads and saves data"| node_dbclient
node_matcher -->|"builds combinations"| node_builder
node_base -.->|"classifies products"| node_taxonomy
node_embeddings -->|"reads products and outfits"| node_dbclient
node_searchlogic -->|"falls back to build"| node_builder
node_searchlogic -->|"queries products"| node_models

click node_app "https://github.com/edm00/luvfitsv1/blob/main/frontend/src/App.jsx"
click node_searchbar "https://github.com/edm00/luvfitsv1/blob/main/frontend/src/components/SearchBar.jsx"
click node_display "https://github.com/edm00/luvfitsv1/blob/main/frontend/src/components/OutfitDisplay.jsx"
click node_api "https://github.com/edm00/luvfitsv1/blob/main/backend/main.py"
click node_worker "https://github.com/edm00/luvfitsv1/blob/main/backend/scripts/refresh_worker.py"
click node_manager "https://github.com/edm00/luvfitsv1/blob/main/backend/scrapers/scraper_manager.py"
click node_base "https://github.com/edm00/luvfitsv1/blob/main/backend/scrapers/base_scraper.py"
click node_hm "https://github.com/edm00/luvfitsv1/blob/main/backend/scrapers/hm_scraper.py"
click node_amazon "https://github.com/edm00/luvfitsv1/blob/main/backend/scrapers/amazon_scraper.py"
click node_nordstrom "https://github.com/edm00/luvfitsv1/blob/main/backend/scrapers/nordstrom_scraper.py"
click node_taxonomy "https://github.com/edm00/luvfitsv1/blob/main/backend/logic/google_taxonomy.py"
click node_embeddings "https://github.com/edm00/luvfitsv1/blob/main/backend/logic/embedding_search.py"
click node_matcher "https://github.com/edm00/luvfitsv1/blob/main/backend/logic/outfit_matcher.py"
click node_builder "https://github.com/edm00/luvfitsv1/blob/main/backend/logic/outfit_builder.py"
click node_searchlogic "https://github.com/edm00/luvfitsv1/blob/main/backend/logic/search_logic.py"
click node_models "https://github.com/edm00/luvfitsv1/blob/main/backend/database/models.py"
click node_dbclient "https://github.com/edm00/luvfitsv1/blob/main/backend/database/db.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_searchbar,node_display toneBlue
class node_api,node_worker toneAmber
class node_manager,node_base,node_hm,node_amazon,node_nordstrom,node_taxonomy toneMint
class node_embeddings,node_matcher,node_builder,node_searchlogic toneRose
class node_models,node_dbclient,node_mongodb,node_shopper,node_scrapedo toneIndigo
```

## Components

### User experience

- [App coordinator](https://github.com/edm00/luvfitsv1/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Vibe input](https://github.com/edm00/luvfitsv1/blob/main/frontend/src/components/SearchBar.jsx): `frontend/src/components/SearchBar.jsx`
- [Outfit display](https://github.com/edm00/luvfitsv1/blob/main/frontend/src/components/OutfitDisplay.jsx): `frontend/src/components/OutfitDisplay.jsx`

### API and orchestration

- [FastAPI](https://github.com/edm00/luvfitsv1/blob/main/backend/main.py): `backend/main.py`
- [Refresh worker](https://github.com/edm00/luvfitsv1/blob/main/backend/scripts/refresh_worker.py): `backend/scripts/refresh_worker.py`

### Product acquisition

- [Scraper manager](https://github.com/edm00/luvfitsv1/blob/main/backend/scrapers/scraper_manager.py): `backend/scrapers/scraper_manager.py`
- [Scrape base](https://github.com/edm00/luvfitsv1/blob/main/backend/scrapers/base_scraper.py): `backend/scrapers/base_scraper.py`
- [H&M scraper](https://github.com/edm00/luvfitsv1/blob/main/backend/scrapers/hm_scraper.py): `backend/scrapers/hm_scraper.py`
- [Amazon scraper](https://github.com/edm00/luvfitsv1/blob/main/backend/scrapers/amazon_scraper.py): `backend/scrapers/amazon_scraper.py`
- [Nordstrom scraper](https://github.com/edm00/luvfitsv1/blob/main/backend/scrapers/nordstrom_scraper.py): `backend/scrapers/nordstrom_scraper.py`
- [Taxonomy mapping](https://github.com/edm00/luvfitsv1/blob/main/backend/logic/google_taxonomy.py): `backend/logic/google_taxonomy.py`

### Outfit matching

- [Embedding service](https://github.com/edm00/luvfitsv1/blob/main/backend/logic/embedding_search.py): `backend/logic/embedding_search.py`
- [Outfit matcher](https://github.com/edm00/luvfitsv1/blob/main/backend/logic/outfit_matcher.py): `backend/logic/outfit_matcher.py`
- [Outfit builder](https://github.com/edm00/luvfitsv1/blob/main/backend/logic/outfit_builder.py): `backend/logic/outfit_builder.py`
- [Legacy search logic](https://github.com/edm00/luvfitsv1/blob/main/backend/logic/search_logic.py): `backend/logic/search_logic.py`

### Data storage

- [Product and outfit models](https://github.com/edm00/luvfitsv1/blob/main/backend/database/models.py): `backend/database/models.py`
- [MongoDB client](https://github.com/edm00/luvfitsv1/blob/main/backend/database/db.py): `backend/database/db.py`
- **MongoDB**

### Other components

- **Shopper**
- **Scrape.do**

## Connections

- Shopper → Vibe input: enters vibe
- Vibe input → App coordinator: submits query
- App coordinator → FastAPI: requests outfits
- FastAPI → MongoDB client: reads outfits
- FastAPI → MongoDB client: reads products
- FastAPI → Refresh worker: starts and stops
- FastAPI → Scraper manager: triggers refresh
- App coordinator → Outfit display: renders result
- FastAPI → App coordinator: returns response
- Scraper manager → H&M scraper: dispatches scrape
- Scraper manager → Amazon scraper: dispatches scrape
- Scraper manager → Nordstrom scraper: dispatches scrape
- H&M scraper → Scrape base: uses scraping
- Amazon scraper → Scrape base: uses scraping
- Nordstrom scraper → Scrape base: uses scraping
- Scrape base → Scrape.do: fetches pages
- Scraper manager → MongoDB client: stores products and jobs
- Scraper manager → Product and outfit models: constructs records
- MongoDB client → MongoDB: reads and writes
- Refresh worker → Scraper manager: runs refresh
- Refresh worker → Embedding service: generates embeddings
- Refresh worker → Outfit matcher: generates outfits
- Outfit matcher → MongoDB client: loads and saves data
- Outfit matcher → Outfit builder: builds combinations
- Scrape base → Taxonomy mapping: classifies products
- Embedding service → MongoDB client: reads products and outfits
- Legacy search logic → Outfit builder: falls back to build
- Legacy search logic → Product and outfit models: queries products