# hmbinara/toyalfa architecture

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

- Interactive diagram: https://gitdiagram.com/hmbinara/toyalfa
- Repository: https://github.com/hmbinara/toyalfa

## Overview

ToyAlfa is a toy e-commerce platform. Shoppers browse products, manage a cart, authenticate, and place orders; admins have a separate dashboard. The frontend also includes profile, wishlist, and product-management surfaces, while the FastAPI backend exposes authentication, product, and order APIs backed by PostgreSQL. The README additionally advertises multimodal search and automated order workflows with ChromaDB, Gemini, and n8n, but the supplied tree and excerpts do not show their implementation or wiring.

Main entry points: [`frontend/src/App.jsx`](https://github.com/hmbinara/toyalfa/blob/main/frontend/src/App.jsx) (App routing), [`backend/app/api/orders.py`](https://github.com/hmbinara/toyalfa/blob/main/backend/app/api/orders.py) (Order API), [`backend/app/api/auth.py`](https://github.com/hmbinara/toyalfa/blob/main/backend/app/api/auth.py) (Authentication API), [`frontend/src/store/orderStore.js`](https://github.com/hmbinara/toyalfa/blob/main/frontend/src/store/orderStore.js) (Order state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Shopper frontend"]
  node_app["App routing<br/>[App.jsx]"]
  node_home["Home storefront<br/>[HomePage.jsx]"]
  node_shop["Product browsing<br/>[ShopPage.jsx]"]
  node_detail["Product details"]
  node_profile["Account profile<br/>[ProfilePage.jsx]"]
  node_admin["Admin dashboard<br/>[AdminPage.jsx]"]
  node_layout["Shared layout<br/>[MainLayout.jsx]"]
  node_authmodal["Sign-in modal<br/>[AuthModal.jsx]"]
  node_productcard["Product card<br/>[ProductCard.jsx]"]
  node_checkout["Checkout<br/>[CheckoutModal.jsx]"]
end

subgraph group_commerce["Commerce state"]
  node_authstate["Auth state<br/>[authStore.js]"]
  node_cartstate["Cart state<br/>[cartStore.js]"]
  node_orderstate["Order state<br/>[orderStore.js]"]
  node_productstate["Product state<br/>[productStore.js]"]
  node_wishlist["Wishlist state<br/>[wishlistStore.js]"]
  node_mockdata["Demo catalog data<br/>[mockData.js]"]
end

subgraph group_api["Backend API"]
  node_apiapp["FastAPI application<br/>[main.py]"]
  node_authapi["Authentication API<br/>[auth.py]"]
  node_productapi["Product API<br/>[products.py]"]
  node_orderapi["Order API<br/>[orders.py]"]
  node_security["Password and tokens<br/>[security.py]"]
end

subgraph group_data["Persistence and integrations"]
  node_session["Database sessions<br/>[session.py]"]
  node_users[("User records<br/>[user.py]")]
  node_products[("Product records<br/>[product.py]")]
  node_orders[("Order records<br/>[order.py]")]
end

node_shopper(("Shopper"))
node_postgres[("PostgreSQL")]
node_chromadb[("ChromaDB")]
node_gemini["Gemini AI"]
node_n8n["n8n workflows"]

node_shopper -->|"visits"| node_app
node_app -->|"wraps pages"| node_layout
node_app -->|"routes to"| node_home
node_app -->|"routes to"| node_shop
node_app -->|"routes to"| node_detail
node_app -->|"guards route"| node_profile
node_app -->|"guards route"| node_admin
node_layout -->|"renders"| node_authmodal
node_authmodal -->|"calls login"| node_authstate
node_authstate -->|"HTTP requests"| node_authapi
node_detail -->|"uses"| node_productstate
node_shop -->|"uses"| node_productstate
node_productcard -->|"adds items"| node_cartstate
node_productcard -->|"toggles wishlist"| node_wishlist
node_checkout -->|"reads cart"| node_cartstate
node_checkout -->|"submits order"| node_orderstate
node_checkout -->|"reads account"| node_authstate
node_profile -->|"shows orders"| node_orderstate
node_profile -->|"shows wishlist"| node_wishlist
node_admin -->|"manages products"| node_productstate
node_admin -->|"manages orders"| node_orderstate
node_cartstate -->|"reads promo codes"| node_mockdata
node_productstate -->|"uses demo data"| node_mockdata
node_orderstate -->|"uses demo orders"| node_mockdata
node_apiapp -->|"registers router"| node_authapi
node_apiapp -->|"registers router"| node_productapi
node_apiapp -->|"registers router"| node_orderapi
node_authapi -->|"uses sessions"| node_session
node_authapi -->|"queries users"| node_users
node_authapi -->|"hashes and verifies"| node_security
node_productapi -->|"uses sessions"| node_session
node_productapi -->|"queries products"| node_products
node_orderapi -->|"uses sessions"| node_session
node_orderapi -->|"queries orders"| node_orders
node_orderapi -->|"reads products"| node_products
node_session -->|"connects to"| node_postgres
node_shopper -.->|"multimodal search"| node_chromadb
node_chromadb -.->|"AI-assisted search"| node_gemini
node_orderapi -.->|"automated workflows"| node_n8n

click node_app "https://github.com/hmbinara/toyalfa/blob/main/frontend/src/App.jsx"
click node_home "https://github.com/hmbinara/toyalfa/blob/main/frontend/src/pages/HomePage.jsx"
click node_shop "https://github.com/hmbinara/toyalfa/blob/main/frontend/src/pages/ShopPage.jsx"
click node_detail "https://github.com/hmbinara/toyalfa/blob/main/frontend/src/pages/ProductDetailPage.jsx"
click node_profile "https://github.com/hmbinara/toyalfa/blob/main/frontend/src/pages/ProfilePage.jsx"
click node_admin "https://github.com/hmbinara/toyalfa/blob/main/frontend/src/pages/AdminPage.jsx"
click node_layout "https://github.com/hmbinara/toyalfa/blob/main/frontend/src/components/layout/MainLayout.jsx"
click node_authmodal "https://github.com/hmbinara/toyalfa/blob/main/frontend/src/components/common/AuthModal.jsx"
click node_productcard "https://github.com/hmbinara/toyalfa/blob/main/frontend/src/components/common/ProductCard.jsx"
click node_checkout "https://github.com/hmbinara/toyalfa/blob/main/frontend/src/components/cart/CheckoutModal.jsx"
click node_authstate "https://github.com/hmbinara/toyalfa/blob/main/frontend/src/store/authStore.js"
click node_cartstate "https://github.com/hmbinara/toyalfa/blob/main/frontend/src/store/cartStore.js"
click node_orderstate "https://github.com/hmbinara/toyalfa/blob/main/frontend/src/store/orderStore.js"
click node_productstate "https://github.com/hmbinara/toyalfa/blob/main/frontend/src/store/productStore.js"
click node_wishlist "https://github.com/hmbinara/toyalfa/blob/main/frontend/src/store/wishlistStore.js"
click node_mockdata "https://github.com/hmbinara/toyalfa/blob/main/frontend/src/data/mockData.js"
click node_apiapp "https://github.com/hmbinara/toyalfa/blob/main/backend/app/main.py"
click node_authapi "https://github.com/hmbinara/toyalfa/blob/main/backend/app/api/auth.py"
click node_productapi "https://github.com/hmbinara/toyalfa/blob/main/backend/app/api/products.py"
click node_orderapi "https://github.com/hmbinara/toyalfa/blob/main/backend/app/api/orders.py"
click node_security "https://github.com/hmbinara/toyalfa/blob/main/backend/app/core/security.py"
click node_session "https://github.com/hmbinara/toyalfa/blob/main/backend/app/db/session.py"
click node_users "https://github.com/hmbinara/toyalfa/blob/main/backend/app/models/user.py"
click node_products "https://github.com/hmbinara/toyalfa/blob/main/backend/app/models/product.py"
click node_orders "https://github.com/hmbinara/toyalfa/blob/main/backend/app/models/order.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_home,node_shop,node_detail,node_profile,node_admin,node_layout,node_authmodal,node_productcard,node_checkout toneBlue
class node_authstate,node_cartstate,node_orderstate,node_productstate,node_wishlist,node_mockdata,node_postgres,node_chromadb toneAmber
class node_apiapp,node_authapi,node_productapi,node_orderapi,node_security toneMint
class node_session,node_users,node_products,node_orders toneRose
class node_shopper,node_gemini,node_n8n toneIndigo
```

## Components

### Shopper frontend

- [App routing](https://github.com/hmbinara/toyalfa/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Home storefront](https://github.com/hmbinara/toyalfa/blob/main/frontend/src/pages/HomePage.jsx): `frontend/src/pages/HomePage.jsx`
- [Product browsing](https://github.com/hmbinara/toyalfa/blob/main/frontend/src/pages/ShopPage.jsx): `frontend/src/pages/ShopPage.jsx`
- [Product details](https://github.com/hmbinara/toyalfa/blob/main/frontend/src/pages/ProductDetailPage.jsx): `frontend/src/pages/ProductDetailPage.jsx`
- [Account profile](https://github.com/hmbinara/toyalfa/blob/main/frontend/src/pages/ProfilePage.jsx): `frontend/src/pages/ProfilePage.jsx`
- [Admin dashboard](https://github.com/hmbinara/toyalfa/blob/main/frontend/src/pages/AdminPage.jsx): `frontend/src/pages/AdminPage.jsx`
- [Shared layout](https://github.com/hmbinara/toyalfa/blob/main/frontend/src/components/layout/MainLayout.jsx): `frontend/src/components/layout/MainLayout.jsx`
- [Sign-in modal](https://github.com/hmbinara/toyalfa/blob/main/frontend/src/components/common/AuthModal.jsx): `frontend/src/components/common/AuthModal.jsx`
- [Product card](https://github.com/hmbinara/toyalfa/blob/main/frontend/src/components/common/ProductCard.jsx): `frontend/src/components/common/ProductCard.jsx`
- [Checkout](https://github.com/hmbinara/toyalfa/blob/main/frontend/src/components/cart/CheckoutModal.jsx): `frontend/src/components/cart/CheckoutModal.jsx`

### Commerce state

- [Auth state](https://github.com/hmbinara/toyalfa/blob/main/frontend/src/store/authStore.js): `frontend/src/store/authStore.js`
- [Cart state](https://github.com/hmbinara/toyalfa/blob/main/frontend/src/store/cartStore.js): `frontend/src/store/cartStore.js`
- [Order state](https://github.com/hmbinara/toyalfa/blob/main/frontend/src/store/orderStore.js): `frontend/src/store/orderStore.js`
- [Product state](https://github.com/hmbinara/toyalfa/blob/main/frontend/src/store/productStore.js): `frontend/src/store/productStore.js`
- [Wishlist state](https://github.com/hmbinara/toyalfa/blob/main/frontend/src/store/wishlistStore.js): `frontend/src/store/wishlistStore.js`
- [Demo catalog data](https://github.com/hmbinara/toyalfa/blob/main/frontend/src/data/mockData.js): `frontend/src/data/mockData.js`

### Backend API

- [FastAPI application](https://github.com/hmbinara/toyalfa/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication API](https://github.com/hmbinara/toyalfa/blob/main/backend/app/api/auth.py): `backend/app/api/auth.py`
- [Product API](https://github.com/hmbinara/toyalfa/blob/main/backend/app/api/products.py): `backend/app/api/products.py`
- [Order API](https://github.com/hmbinara/toyalfa/blob/main/backend/app/api/orders.py): `backend/app/api/orders.py`
- [Password and tokens](https://github.com/hmbinara/toyalfa/blob/main/backend/app/core/security.py): `backend/app/core/security.py`

### Persistence and integrations

- [Database sessions](https://github.com/hmbinara/toyalfa/blob/main/backend/app/db/session.py): `backend/app/db/session.py`
- [User records](https://github.com/hmbinara/toyalfa/blob/main/backend/app/models/user.py): `backend/app/models/user.py`
- [Product records](https://github.com/hmbinara/toyalfa/blob/main/backend/app/models/product.py): `backend/app/models/product.py`
- [Order records](https://github.com/hmbinara/toyalfa/blob/main/backend/app/models/order.py): `backend/app/models/order.py`

### Other components

- **Shopper**
- **PostgreSQL**
- **ChromaDB**
- **Gemini AI**
- **n8n workflows**

## Connections

- Shopper → App routing: visits (evidence: `frontend/src/App.jsx`)
- App routing → Shared layout: wraps pages (evidence: `frontend/src/App.jsx`)
- App routing → Home storefront: routes to (evidence: `frontend/src/App.jsx`)
- App routing → Product browsing: routes to (evidence: `frontend/src/App.jsx`)
- App routing → Product details: routes to (evidence: `frontend/src/App.jsx`)
- App routing → Account profile: guards route (evidence: `frontend/src/App.jsx`)
- App routing → Admin dashboard: guards route (evidence: `frontend/src/App.jsx`)
- Shared layout → Sign-in modal: renders (evidence: `frontend/src/components/layout/MainLayout.jsx`)
- Sign-in modal → Auth state: calls login (evidence: `frontend/src/components/common/AuthModal.jsx`)
- Auth state → Authentication API: HTTP requests (evidence: `frontend/src/store/authStore.js`)
- Product details → Product state: uses (evidence: `frontend/src/pages/ProductDetailPage.jsx`)
- Product browsing → Product state: uses (evidence: `frontend/src/pages/ShopPage.jsx`)
- Product card → Cart state: adds items (evidence: `frontend/src/components/common/ProductCard.jsx`)
- Product card → Wishlist state: toggles wishlist (evidence: `frontend/src/components/common/ProductCard.jsx`)
- Checkout → Cart state: reads cart (evidence: `frontend/src/components/cart/CheckoutModal.jsx`)
- Checkout → Order state: submits order (evidence: `frontend/src/components/cart/CheckoutModal.jsx`)
- Checkout → Auth state: reads account (evidence: `frontend/src/components/cart/CheckoutModal.jsx`)
- Account profile → Order state: shows orders (evidence: `frontend/src/pages/ProfilePage.jsx`)
- Account profile → Wishlist state: shows wishlist (evidence: `frontend/src/pages/ProfilePage.jsx`)
- Admin dashboard → Product state: manages products (evidence: `frontend/src/pages/AdminPage.jsx`)
- Admin dashboard → Order state: manages orders (evidence: `frontend/src/pages/AdminPage.jsx`)
- Cart state → Demo catalog data: reads promo codes (evidence: `frontend/src/store/cartStore.js`)
- Product state → Demo catalog data: uses demo data (evidence: `frontend/src/store/productStore.js`)
- Order state → Demo catalog data: uses demo orders (evidence: `frontend/src/store/orderStore.js`)
- FastAPI application → Authentication API: registers router (evidence: `backend/app/main.py`)
- FastAPI application → Product API: registers router (evidence: `backend/app/main.py`)
- FastAPI application → Order API: registers router (evidence: `backend/app/main.py`)
- Authentication API → Database sessions: uses sessions (evidence: `backend/app/api/auth.py`)
- Authentication API → User records: queries users (evidence: `backend/app/api/auth.py`)
- Authentication API → Password and tokens: hashes and verifies (evidence: `backend/app/api/auth.py`)
- Product API → Database sessions: uses sessions (evidence: `backend/app/api/products.py`)
- Product API → Product records: queries products (evidence: `backend/app/api/products.py`)
- Order API → Database sessions: uses sessions (evidence: `backend/app/api/orders.py`)
- Order API → Order records: queries orders (evidence: `backend/app/api/orders.py`)
- Order API → Product records: reads products (evidence: `backend/app/api/orders.py`)
- Database sessions → PostgreSQL: connects to (evidence: `backend/app/db/session.py`)
- Shopper → ChromaDB: multimodal search (evidence: `README.md`)
- ChromaDB → Gemini AI: AI-assisted search (evidence: `README.md`)
- Order API → n8n workflows: automated workflows (evidence: `README.md`)
