# aaron-howard/e-commerce architecture

> Architecture diagram of the GitHub repository aaron-howard/e-commerce, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aaron-howard/e-commerce
- Repository: https://github.com/aaron-howard/e-commerce

## Overview

1. **Overall shape**
   - This is a **SvelteKit storefront MVP**. The app is entirely **client-side mocked**: products, users, cart, checkout, and orders are all simulated in-memory or via `localStorage`, with **no backend API, payment gateway, or database**.

2. **Primary UI shell**
   - `src/routes/+layout.svelte` provides the shared application frame.
   - `src/lib/components/Nav.svelte` and `Footer.svelte` are the main cross-page UI boundaries, reused by marketing and commerce pages.

3. **Route structure**
   - The app is organized by user journey:
     - Marketing/content: `/`, `/about`, `/collections`, `/journal`
     - Commerce browsing: `/shop`, `/product/[slug]`
     - Transaction flow: `/cart`, `/checkout/shipping`, `/checkout/payment`
     - Identity/account: `/login`, `/signup`, `/account`
     - Orders: `/orders/[id]`
   - Dynamic routes for product and order details are driven by URL params and route-specific load logic.

4. **Data layer**
   - Canonical mock content lives in `src/lib/data/`:
     - `products.ts` for the catalog
     - `collections.ts` for collection metadata / deep-linking
     - `mockUser.ts` for simulated user identity
   - These files act as the app’s source of truth for displayed commerce content.

5. **State management boundary**
   - Persistent client state is centralized in `src/lib/stores/` using Svelte stores.
   - The main stores are:
     - `cart.ts` for cart contents
     - `checkout.ts` for checkout progression and form state
     - `auth.ts` for mock sign-in/sign-up state
     - `orders.ts` for persisted mock orders
   - `readJsonArray.ts` suggests a small persistence helper around `localStorage` or JSON-serialized arrays.

6. **Checkout and order flow**
   - The transaction path is a two-step wizard:
     - shipping information
     - payment review
   - `src/lib/order/placeOrder.ts` likely converts the current cart + checkout state into a persisted order record.
   - `totalsFromSubtotal.ts` encapsulates business logic for shipping/tax/total calculations, keeping pricing rules separate from UI.

7. **Catalog and product browsing flow**
   - `/shop` is the main browsing entry point and supports search and category/collection filters.
   - `/collections` provides deep links into the catalog via `?collection=...`.
   - `/product/[slug]` resolves a single product from the mock catalog and supports quantity selection plus add-to-cart.

8. **Order detail and persistence**
   - `/orders/[id]` is a client-only order confirmation/detail view, meaning the order record must already exist in local persisted state.
   - This creates a clear dependency chain: cart → checkout → place order → orders store → order detail route.

9. **Account flow**
   - `/login`, `/signup`, and `/account` are mock identity screens tied to the auth store and mock user data.
   - There is no real authentication boundary; the “account” experience is a UI/state simulation for the storefront demo.

10. **Styling and design system**
    - `src/routes/layout.css` contains the global visual tokens, aligned to the Stitch/Digital Atelier palette.
    - The repository includes `stitch_e-commerce/stitch/` as a **reference artifact set**: exported HTML and design docs used to port the visual system, but not executed by the app.

11. **Execution/runtime boundaries**
    - Since the app has no server-side data sources, the main runtime boundary is the browser itself.
    - Persistence, navigation state, and mock business logic all live in the client, which makes the architecture simple but also means reloads depend on local storage for continuity.

12. **What to draw in an architecture diagram**
    - A good diagram would show:
      - SvelteKit route layer on top
      - shared components and layout beneath it
      - mock data modules as static inputs
      - Svelte stores as the central state hub
      - order/pricing helpers as business-logic services
      - browser localStorage as the only persistence layer
      - the Stitch folder as an external design reference, not a runtime dependency

Main entry points: [`src/routes/+layout.svelte`](https://github.com/aaron-howard/e-commerce/blob/main/src/routes/+layout.svelte) (App shell), [`src/lib/stores`](https://github.com/aaron-howard/e-commerce/tree/main/src/lib/stores) (Stores), [`src/lib/order/placeOrder.ts`](https://github.com/aaron-howard/e-commerce/blob/main/src/lib/order/placeOrder.ts) (Place order), [`src/routes/product/[slug]/+page.svelte`](https://github.com/aaron-howard/e-commerce/blob/main/src/routes/product/[slug]/+page.svelte) (Product detail)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_routes["SvelteKit routes"]
  node_layout["App shell<br/>SvelteKit layout<br/>[+layout.svelte]"]
  node_home["Home<br/>Landing page<br/>[+page.svelte]"]
  node_about["About<br/>Content page<br/>[+page.svelte]"]
  node_collections["Collections<br/>Catalog entry<br/>[+page.svelte]"]
  node_journal["Journal<br/>Editorial page<br/>[+page.svelte]"]
  node_shop["Shop<br/>Catalog browse<br/>[+page.svelte]"]
  node_product["Product detail<br/>Dynamic route<br/>[+page.svelte]"]
  node_cart["Cart<br/>[+page.svelte]"]
  node_shipping["Shipping<br/>Checkout step<br/>[+page.svelte]"]
  node_payment["Payment<br/>Checkout step<br/>[+page.svelte]"]
  node_login["Login<br/>Auth page<br/>[+page.svelte]"]
  node_signup["Signup<br/>Auth page<br/>[+page.svelte]"]
  node_account["Account<br/>Profile page<br/>[+page.svelte]"]
  node_orderdetail["Order detail<br/>Dynamic route<br/>[+page.svelte]"]
end

subgraph group_ui["Shared UI"]
  node_nav["Nav<br/>Shared component<br/>[Nav.svelte]"]
  node_footer["Footer<br/>Shared component<br/>[Footer.svelte]"]
end

subgraph group_state["Client state"]
  node_stores[("Stores")]
  node_localstorage[("Local storage<br/>Browser persistence")]
end

subgraph group_data["Mock content"]
  node_productsdata["Products<br/>Catalog data<br/>[products.ts]"]
  node_collectionsdata["Collections data<br/>Collection data<br/>[collections.ts]"]
  node_mockuser["Mock user<br/>Identity seed<br/>[mockUser.ts]"]
end

subgraph group_business["Commerce logic"]
  node_orderlogic["Place order<br/>Order service<br/>[placeOrder.ts]"]
  node_totalslogic["Totals<br/>Pricing logic"]
end

subgraph group_reference["Design reference"]
  node_stitch["Stitch refs<br/>Design artifacts"]
end

node_layout -->|"renders"| node_nav
node_layout -->|"renders"| node_footer
node_layout -->|"wraps"| node_home
node_layout -->|"wraps"| node_about
node_layout -->|"wraps"| node_collections
node_layout -->|"wraps"| node_journal
node_layout -->|"wraps"| node_shop
node_layout -->|"wraps"| node_product
node_layout -->|"wraps"| node_cart
node_layout -->|"wraps"| node_shipping
node_layout -->|"wraps"| node_payment
node_layout -->|"wraps"| node_login
node_layout -->|"wraps"| node_signup
node_layout -->|"wraps"| node_account
node_layout -->|"wraps"| node_orderdetail
node_home -->|"reads"| node_productsdata
node_collections -->|"reads"| node_collectionsdata
node_shop -->|"reads"| node_productsdata
node_product -->|"loads"| node_productsdata
node_cart -->|"uses"| node_stores
node_shipping -->|"uses"| node_stores
node_payment -->|"uses"| node_stores
node_login -->|"uses"| node_stores
node_signup -->|"uses"| node_stores
node_account -->|"uses"| node_stores
node_orderdetail -->|"reads"| node_stores
node_stores -->|"persists to"| node_localstorage
node_orderlogic -->|"reads/writes"| node_stores
node_orderlogic -->|"uses"| node_totalslogic
node_orderlogic -->|"persists to"| node_localstorage
node_shipping -->|"advances"| node_orderlogic
node_payment -->|"confirms"| node_orderlogic
node_product -->|"adds to cart"| node_stores
node_stitch -.->|"references"| node_layout
node_stitch -.->|"references"| node_collections
node_stitch -.->|"references"| node_product

click node_layout "https://github.com/aaron-howard/e-commerce/blob/main/src/routes/+layout.svelte"
click node_home "https://github.com/aaron-howard/e-commerce/blob/main/src/routes/+page.svelte"
click node_about "https://github.com/aaron-howard/e-commerce/blob/main/src/routes/about/+page.svelte"
click node_collections "https://github.com/aaron-howard/e-commerce/blob/main/src/routes/collections/+page.svelte"
click node_journal "https://github.com/aaron-howard/e-commerce/blob/main/src/routes/journal/+page.svelte"
click node_shop "https://github.com/aaron-howard/e-commerce/blob/main/src/routes/shop/+page.svelte"
click node_product "https://github.com/aaron-howard/e-commerce/blob/main/src/routes/product/[slug]/+page.svelte"
click node_cart "https://github.com/aaron-howard/e-commerce/blob/main/src/routes/cart/+page.svelte"
click node_shipping "https://github.com/aaron-howard/e-commerce/blob/main/src/routes/checkout/shipping/+page.svelte"
click node_payment "https://github.com/aaron-howard/e-commerce/blob/main/src/routes/checkout/payment/+page.svelte"
click node_login "https://github.com/aaron-howard/e-commerce/blob/main/src/routes/login/+page.svelte"
click node_signup "https://github.com/aaron-howard/e-commerce/blob/main/src/routes/signup/+page.svelte"
click node_account "https://github.com/aaron-howard/e-commerce/blob/main/src/routes/account/+page.svelte"
click node_orderdetail "https://github.com/aaron-howard/e-commerce/blob/main/src/routes/orders/[id]/+page.svelte"
click node_nav "https://github.com/aaron-howard/e-commerce/blob/main/src/lib/components/Nav.svelte"
click node_footer "https://github.com/aaron-howard/e-commerce/blob/main/src/lib/components/Footer.svelte"
click node_stores "https://github.com/aaron-howard/e-commerce/tree/main/src/lib/stores"
click node_productsdata "https://github.com/aaron-howard/e-commerce/blob/main/src/lib/data/products.ts"
click node_collectionsdata "https://github.com/aaron-howard/e-commerce/blob/main/src/lib/data/collections.ts"
click node_mockuser "https://github.com/aaron-howard/e-commerce/blob/main/src/lib/data/mockUser.ts"
click node_orderlogic "https://github.com/aaron-howard/e-commerce/blob/main/src/lib/order/placeOrder.ts"
click node_totalslogic "https://github.com/aaron-howard/e-commerce/blob/main/src/lib/order/totalsFromSubtotal.ts"
click node_stitch "https://github.com/aaron-howard/e-commerce/tree/main/stitch_e-commerce/stitch"

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_layout,node_home,node_about,node_collections,node_journal,node_shop,node_product,node_cart,node_shipping,node_payment,node_login,node_signup,node_account,node_orderdetail toneBlue
class node_nav,node_footer toneAmber
class node_stores,node_localstorage toneMint
class node_productsdata,node_collectionsdata,node_mockuser toneRose
class node_orderlogic,node_totalslogic toneIndigo
class node_stitch toneTeal
```

## Components

### SvelteKit routes

Client-side pages and route-specific load logic.

- [App shell](https://github.com/aaron-howard/e-commerce/blob/main/src/routes/+layout.svelte): SvelteKit layout · Shared application frame for all routes. · `src/routes/+layout.svelte`
- [Home](https://github.com/aaron-howard/e-commerce/blob/main/src/routes/+page.svelte): Landing page · Marketing entry page. · `src/routes/+page.svelte`
- [About](https://github.com/aaron-howard/e-commerce/blob/main/src/routes/about/+page.svelte): Content page · Brand/about information page. · `src/routes/about/+page.svelte`
- [Collections](https://github.com/aaron-howard/e-commerce/blob/main/src/routes/collections/+page.svelte): Catalog entry · Collection deep links into the product catalog. · `src/routes/collections/+page.svelte`
- [Journal](https://github.com/aaron-howard/e-commerce/blob/main/src/routes/journal/+page.svelte): Editorial page · Content/editorial browsing page. · `src/routes/journal/+page.svelte`
- [Shop](https://github.com/aaron-howard/e-commerce/blob/main/src/routes/shop/+page.svelte): Catalog browse · Primary product listing with search and filters. · `src/routes/shop/+page.svelte`
- [Product detail](https://github.com/aaron-howard/e-commerce/blob/main/src/routes/product/[slug]/+page.svelte): Dynamic route · Single product view driven by slug params. · `src/routes/product/[slug]/+page.svelte`
- [Cart](https://github.com/aaron-howard/e-commerce/blob/main/src/routes/cart/+page.svelte): Cart page · Cart review and quantity management. · `src/routes/cart/+page.svelte`
- [Shipping](https://github.com/aaron-howard/e-commerce/blob/main/src/routes/checkout/shipping/+page.svelte): Checkout step · Shipping information step in the checkout wizard. · `src/routes/checkout/shipping/+page.svelte`
- [Payment](https://github.com/aaron-howard/e-commerce/blob/main/src/routes/checkout/payment/+page.svelte): Checkout step · Payment review step in the checkout wizard. · `src/routes/checkout/payment/+page.svelte`
- [Login](https://github.com/aaron-howard/e-commerce/blob/main/src/routes/login/+page.svelte): Auth page · Mock sign-in screen. · `src/routes/login/+page.svelte`
- [Signup](https://github.com/aaron-howard/e-commerce/blob/main/src/routes/signup/+page.svelte): Auth page · Mock sign-up screen. · `src/routes/signup/+page.svelte`
- [Account](https://github.com/aaron-howard/e-commerce/blob/main/src/routes/account/+page.svelte): Profile page · Client-side account view bound to mock auth state. · `src/routes/account/+page.svelte`
- [Order detail](https://github.com/aaron-howard/e-commerce/blob/main/src/routes/orders/[id]/+page.svelte): Dynamic route · Persisted order confirmation/detail view driven by id params. · `src/routes/orders/[id]/+page.svelte`

### Shared UI

Layout shell and reusable components across pages.

- [Nav](https://github.com/aaron-howard/e-commerce/blob/main/src/lib/components/Nav.svelte): Shared component · Primary navigation reused across the storefront. · `src/lib/components/Nav.svelte`
- [Footer](https://github.com/aaron-howard/e-commerce/blob/main/src/lib/components/Footer.svelte): Shared component · Shared footer across pages. · `src/lib/components/Footer.svelte`

### Client state

Svelte stores plus persistence helpers for mock app state.

- [Stores](https://github.com/aaron-howard/e-commerce/tree/main/src/lib/stores): Svelte stores · Central client state boundary for cart, checkout, auth, and orders. · `src/lib/stores`
- **Local storage**: Browser persistence · Only persistence layer for mock state continuity.

### Mock content

Canonical in-memory catalog and identity data.

- [Products](https://github.com/aaron-howard/e-commerce/blob/main/src/lib/data/products.ts): Catalog data · Canonical mock product catalog. · `src/lib/data/products.ts`
- [Collections data](https://github.com/aaron-howard/e-commerce/blob/main/src/lib/data/collections.ts): Collection data · Collection metadata and deep-link targets. · `src/lib/data/collections.ts`
- [Mock user](https://github.com/aaron-howard/e-commerce/blob/main/src/lib/data/mockUser.ts): Identity seed · Simulated user identity used by auth/account flows. · `src/lib/data/mockUser.ts`

### Commerce logic

Order placement and pricing calculations.

- [Place order](https://github.com/aaron-howard/e-commerce/blob/main/src/lib/order/placeOrder.ts): Order service · Converts cart and checkout state into a persisted order record. · `src/lib/order/placeOrder.ts`
- [Totals](https://github.com/aaron-howard/e-commerce/blob/main/src/lib/order/totalsFromSubtotal.ts): Pricing logic · Shipping, tax, and total calculations. · `src/lib/order/totalsFromSubtotal.ts`

### Design reference

Stitch export artifacts used as visual/source reference, not runtime dependencies.

- [Stitch refs](https://github.com/aaron-howard/e-commerce/tree/main/stitch_e-commerce/stitch): Design artifacts · Reference HTML and design docs for visual implementation; not executed by the app. · `stitch_e-commerce/stitch`

## Connections

- App shell → Nav: renders · The app shell composes shared navigation.
- App shell → Footer: renders · The app shell composes shared footer.
- App shell → Home: wraps · Shared frame applies to all top-level routes.
- App shell → About: wraps · Shared frame applies to all top-level routes.
- App shell → Collections: wraps · Shared frame applies to all top-level routes.
- App shell → Journal: wraps · Shared frame applies to all top-level routes.
- App shell → Shop: wraps · Shared frame applies to all top-level routes.
- App shell → Product detail: wraps · Shared frame applies to all top-level routes.
- App shell → Cart: wraps · Shared frame applies to all top-level routes.
- App shell → Shipping: wraps · Shared frame applies to all top-level routes.
- App shell → Payment: wraps · Shared frame applies to all top-level routes.
- App shell → Login: wraps · Shared frame applies to all top-level routes.
- App shell → Signup: wraps · Shared frame applies to all top-level routes.
- App shell → Account: wraps · Shared frame applies to all top-level routes.
- App shell → Order detail: wraps · Shared frame applies to all top-level routes.
- Home → Products: reads · Marketing and storefront pages draw from mock catalog content.
- Collections → Collections data: reads · Collection page uses catalog grouping metadata.
- Shop → Products: reads · Shop listing is driven by canonical catalog data.
- Product detail → Products: loads · Slug-based detail route resolves one product from the catalog.
- Cart → Stores: uses · Cart state is sourced from the central stores boundary.
- Shipping → Stores: uses · Checkout step reads and updates shared checkout state.
- Payment → Stores: uses · Checkout step reads and updates shared checkout state.
- Login → Stores: uses · Mock sign-in state flows through auth store.
- Signup → Stores: uses · Mock sign-up state flows through auth store.
- Account → Stores: uses · Account screen reflects simulated auth/account state.
- Order detail → Stores: reads · Order detail route looks up persisted orders.
- Stores → Local storage: persists to · Persistent client state survives reloads through browser storage.
- Place order → Stores: reads/writes · Order placement consumes cart and checkout state and updates orders.
- Place order → Totals: uses · Order placement relies on pricing calculations.
- Place order → Local storage: persists to · Placed orders are stored in browser persistence.
- Shipping → Place order: advances · Shipping step feeds into order placement flow.
- Payment → Place order: confirms · Payment review triggers final order creation.
- Product detail → Stores: adds to cart · Product detail page drives cart mutations through stores.
- Stitch refs → App shell: references · Visual system reference informs the app shell and styling.
- Stitch refs → Collections: references · Design artifacts mirror the storefront's collection page.
- Stitch refs → Product detail: references · Design artifacts mirror the product detail experience.
