# immanuelphilli1/handco architecture

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

- Interactive diagram: https://gitdiagram.com/immanuelphilli1/handco
- Repository: https://github.com/immanuelphilli1/handco

## Overview

This is a React storefront for browsing products, managing a cart and wishlist, checking out, and viewing account/order information. The principal flow starts at the storefront, proceeds through catalog discovery and cart/checkout, then reaches payment and order status; account and policy pages are additional branches. The sampled sources show app routing, session handling, shared commerce state, and API request plumbing. Many feature implementations are unsampled, so those links are limited to relationships named by the SOURCE INDEX or README.

Main entry points: [`src/pages/HomePage.tsx`](https://github.com/immanuelphilli1/handco/blob/main/src/pages/HomePage.tsx) (Storefront), [`src/api/services`](https://github.com/immanuelphilli1/handco/tree/main/src/api/services) (API services), [`src/components/Nav.tsx`](https://github.com/immanuelphilli1/handco/blob/main/src/components/Nav.tsx) (Navigation), [`src/App.tsx`](https://github.com/immanuelphilli1/handco/blob/main/src/App.tsx) (App routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application shell"]
  node_app["App routes<br/>[App.tsx]"]
  node_home["Storefront<br/>[HomePage.tsx]"]
  node_account_page["Account page<br/>[AccountPage.tsx]"]
  node_policy_pages["Policy pages"]
  node_nav["Navigation<br/>[Nav.tsx]"]
end

subgraph group_discovery["Catalog discovery"]
  node_category_nav["Category navigation"]
  node_route_model["Shop routes<br/>[shopRoutes.ts]"]
  node_category_model["Category model"]
  node_listing_model["Listing and filters<br/>[categoryListing.ts]"]
  node_search["Product search"]
  node_catalog_state["Catalog state<br/>[CatalogContext.tsx]"]
end

subgraph group_commerce["Shopping and orders"]
  node_cart_view["Cart<br/>[CartView.tsx]"]
  node_checkout["Checkout<br/>[CheckoutView.tsx]"]
  node_payment_return["Payment return"]
  node_orders["Orders and tracking<br/>[YourOrdersView.tsx]"]
  node_shop_state["Cart and wishlist state<br/>[ShopContext.tsx]"]
end

subgraph group_account["Account and content"]
  node_auth["Session and sign-in<br/>[AuthContext.tsx]"]
  node_account_features["Account features"]
end

subgraph group_platform["API and state"]
  node_api_services["API services"]
  node_api_client["HTTP client<br/>[client.ts]"]
  node_api_storage[("Session storage<br/>[storage.ts]")]
  node_api_mappers["API mappers<br/>[mappers.ts]"]
end

node_customer(("Shopper"))
node_backend["Store backend"]

node_customer -->|"opens storefront"| node_app
node_app -->|"routes to"| node_home
node_app -->|"routes to"| node_account_page
node_app -->|"routes to"| node_policy_pages
node_home -->|"renders"| node_nav
node_home -->|"renders"| node_cart_view
node_home -->|"renders"| node_checkout
node_home -->|"renders"| node_payment_return
node_home -->|"uses"| node_category_nav
node_nav -->|"uses"| node_category_nav
node_category_nav -->|"navigates with"| node_route_model
node_route_model -->|"builds selections with"| node_category_model
node_route_model -->|"uses selection types"| node_listing_model
node_home -->|"renders search"| node_search
node_search -->|"reads catalog"| node_catalog_state
node_account_page -->|"renders"| node_orders
node_account_page -->|"renders"| node_nav
node_orders -->|"renders panels"| node_account_features
node_nav -->|"reads session state"| node_auth
node_nav -->|"reads shop state"| node_shop_state
node_shop_state -->|"reads user state"| node_auth
node_shop_state -->|"calls cart and wishlist APIs"| node_api_services
node_auth -->|"calls auth API"| node_api_services
node_auth -->|"reads and clears tokens"| node_api_storage
node_api_services -->|"uses HTTP client"| node_api_client
node_api_client -->|"reads and writes tokens"| node_api_storage
node_api_client -->|"sends requests"| node_backend
node_catalog_state -->|"loads catalog"| node_api_services
node_catalog_state -->|"maps responses"| node_api_mappers
node_search -->|"uses product mappings"| node_api_mappers
node_checkout -.->|"uses checkout API"| node_api_services
node_payment_return -.->|"checks payment status"| node_api_services

click node_app "https://github.com/immanuelphilli1/handco/blob/main/src/App.tsx"
click node_home "https://github.com/immanuelphilli1/handco/blob/main/src/pages/HomePage.tsx"
click node_account_page "https://github.com/immanuelphilli1/handco/blob/main/src/pages/AccountPage.tsx"
click node_policy_pages "https://github.com/immanuelphilli1/handco/tree/main/src/pages"
click node_nav "https://github.com/immanuelphilli1/handco/blob/main/src/components/Nav.tsx"
click node_category_nav "https://github.com/immanuelphilli1/handco/blob/main/src/hooks/useCategoryNavigation.ts"
click node_route_model "https://github.com/immanuelphilli1/handco/blob/main/src/data/shopRoutes.ts"
click node_category_model "https://github.com/immanuelphilli1/handco/blob/main/src/data/catalogCategories.ts"
click node_listing_model "https://github.com/immanuelphilli1/handco/blob/main/src/data/categoryListing.ts"
click node_search "https://github.com/immanuelphilli1/handco/blob/main/src/hooks/useProductSearch.ts"
click node_catalog_state "https://github.com/immanuelphilli1/handco/blob/main/src/context/CatalogContext.tsx"
click node_cart_view "https://github.com/immanuelphilli1/handco/blob/main/src/components/CartView.tsx"
click node_checkout "https://github.com/immanuelphilli1/handco/blob/main/src/components/CheckoutView.tsx"
click node_payment_return "https://github.com/immanuelphilli1/handco/blob/main/src/components/PaymentReturnView.tsx"
click node_orders "https://github.com/immanuelphilli1/handco/blob/main/src/components/YourOrdersView.tsx"
click node_shop_state "https://github.com/immanuelphilli1/handco/blob/main/src/context/ShopContext.tsx"
click node_auth "https://github.com/immanuelphilli1/handco/blob/main/src/context/AuthContext.tsx"
click node_account_features "https://github.com/immanuelphilli1/handco/tree/main/src/components"
click node_api_services "https://github.com/immanuelphilli1/handco/tree/main/src/api/services"
click node_api_client "https://github.com/immanuelphilli1/handco/blob/main/src/api/client.ts"
click node_api_storage "https://github.com/immanuelphilli1/handco/blob/main/src/api/storage.ts"
click node_api_mappers "https://github.com/immanuelphilli1/handco/blob/main/src/api/mappers.ts"

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_account_page,node_policy_pages,node_nav toneBlue
class node_category_nav,node_route_model,node_category_model,node_listing_model,node_search,node_catalog_state toneAmber
class node_cart_view,node_checkout,node_payment_return,node_orders,node_shop_state toneMint
class node_auth,node_account_features toneRose
class node_api_services,node_api_client,node_api_storage,node_api_mappers,node_customer,node_backend toneIndigo
```

## Components

### Application shell

- [App routes](https://github.com/immanuelphilli1/handco/blob/main/src/App.tsx): `src/App.tsx`
- [Storefront](https://github.com/immanuelphilli1/handco/blob/main/src/pages/HomePage.tsx): `src/pages/HomePage.tsx`
- [Account page](https://github.com/immanuelphilli1/handco/blob/main/src/pages/AccountPage.tsx): `src/pages/AccountPage.tsx`
- [Policy pages](https://github.com/immanuelphilli1/handco/tree/main/src/pages): `src/pages`
- [Navigation](https://github.com/immanuelphilli1/handco/blob/main/src/components/Nav.tsx): `src/components/Nav.tsx`

### Catalog discovery

- [Category navigation](https://github.com/immanuelphilli1/handco/blob/main/src/hooks/useCategoryNavigation.ts): `src/hooks/useCategoryNavigation.ts`
- [Shop routes](https://github.com/immanuelphilli1/handco/blob/main/src/data/shopRoutes.ts): `src/data/shopRoutes.ts`
- [Category model](https://github.com/immanuelphilli1/handco/blob/main/src/data/catalogCategories.ts): `src/data/catalogCategories.ts`
- [Listing and filters](https://github.com/immanuelphilli1/handco/blob/main/src/data/categoryListing.ts): `src/data/categoryListing.ts`
- [Product search](https://github.com/immanuelphilli1/handco/blob/main/src/hooks/useProductSearch.ts): `src/hooks/useProductSearch.ts`
- [Catalog state](https://github.com/immanuelphilli1/handco/blob/main/src/context/CatalogContext.tsx): `src/context/CatalogContext.tsx`

### Shopping and orders

- [Cart](https://github.com/immanuelphilli1/handco/blob/main/src/components/CartView.tsx): `src/components/CartView.tsx`
- [Checkout](https://github.com/immanuelphilli1/handco/blob/main/src/components/CheckoutView.tsx): `src/components/CheckoutView.tsx`
- [Payment return](https://github.com/immanuelphilli1/handco/blob/main/src/components/PaymentReturnView.tsx): `src/components/PaymentReturnView.tsx`
- [Orders and tracking](https://github.com/immanuelphilli1/handco/blob/main/src/components/YourOrdersView.tsx): `src/components/YourOrdersView.tsx`
- [Cart and wishlist state](https://github.com/immanuelphilli1/handco/blob/main/src/context/ShopContext.tsx): `src/context/ShopContext.tsx`

### Account and content

- [Session and sign-in](https://github.com/immanuelphilli1/handco/blob/main/src/context/AuthContext.tsx): `src/context/AuthContext.tsx`
- [Account features](https://github.com/immanuelphilli1/handco/tree/main/src/components): `src/components`

### API and state

- [API services](https://github.com/immanuelphilli1/handco/tree/main/src/api/services): `src/api/services`
- [HTTP client](https://github.com/immanuelphilli1/handco/blob/main/src/api/client.ts): `src/api/client.ts`
- [Session storage](https://github.com/immanuelphilli1/handco/blob/main/src/api/storage.ts): `src/api/storage.ts`
- [API mappers](https://github.com/immanuelphilli1/handco/blob/main/src/api/mappers.ts): `src/api/mappers.ts`

### Other components

- **Shopper**
- **Store backend**

## Connections

- Shopper → App routes: opens storefront (evidence: `src/App.tsx`)
- App routes → Storefront: routes to (evidence: `src/App.tsx`)
- App routes → Account page: routes to (evidence: `src/App.tsx`)
- App routes → Policy pages: routes to (evidence: `src/App.tsx`)
- Storefront → Navigation: renders (evidence: `src/pages/HomePage.tsx`)
- Storefront → Cart: renders (evidence: `src/pages/HomePage.tsx`)
- Storefront → Checkout: renders (evidence: `src/pages/HomePage.tsx`)
- Storefront → Payment return: renders (evidence: `src/pages/HomePage.tsx`)
- Storefront → Category navigation: uses (evidence: `src/pages/HomePage.tsx`)
- Navigation → Category navigation: uses (evidence: `src/components/Nav.tsx`)
- Category navigation → Shop routes: navigates with (evidence: `src/hooks/useCategoryNavigation.ts`)
- Shop routes → Category model: builds selections with (evidence: `src/data/shopRoutes.ts`)
- Shop routes → Listing and filters: uses selection types (evidence: `src/data/shopRoutes.ts`)
- Storefront → Product search: renders search (evidence: `src/pages/HomePage.tsx`)
- Product search → Catalog state: reads catalog (evidence: `src/hooks/useProductSearch.ts`)
- Account page → Orders and tracking: renders (evidence: `src/pages/AccountPage.tsx`)
- Account page → Navigation: renders (evidence: `src/pages/AccountPage.tsx`)
- Orders and tracking → Account features: renders panels (evidence: `src/components/YourOrdersView.tsx`)
- Navigation → Session and sign-in: reads session state (evidence: `src/components/Nav.tsx`)
- Navigation → Cart and wishlist state: reads shop state (evidence: `src/components/Nav.tsx`)
- Cart and wishlist state → Session and sign-in: reads user state (evidence: `src/context/ShopContext.tsx`)
- Cart and wishlist state → API services: calls cart and wishlist APIs (evidence: `src/context/ShopContext.tsx`)
- Session and sign-in → API services: calls auth API (evidence: `src/context/AuthContext.tsx`)
- Session and sign-in → Session storage: reads and clears tokens (evidence: `src/context/AuthContext.tsx`)
- API services → HTTP client: uses HTTP client (evidence: `src/api/services/auth.ts`)
- HTTP client → Session storage: reads and writes tokens (evidence: `src/api/client.ts`)
- HTTP client → Store backend: sends requests (evidence: `src/api/client.ts`)
- Catalog state → API services: loads catalog (evidence: `src/context/CatalogContext.tsx`)
- Catalog state → API mappers: maps responses (evidence: `src/context/CatalogContext.tsx`)
- Product search → API mappers: uses product mappings (evidence: `src/hooks/useProductSearch.ts`)
- Checkout → API services: uses checkout API
- Payment return → API services: checks payment status
