# itswadesh/svelte-commerce architecture

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

- Interactive diagram: https://gitdiagram.com/itswadesh/svelte-commerce
- Repository: https://github.com/itswadesh/svelte-commerce

## Overview

1. This repository is a SvelteKit-based headless ecommerce storefront. Its main boundary is the frontend app: it renders product discovery, cart, checkout, account, and content pages while delegating commerce data to an external backend/API.

2. The application is split by route groups under `src/routes`:
   - `(www)` is the public storefront and commerce flow
   - `(my)` is the authenticated customer area
   - `(legal)` contains static/legal content
   - `proxy/shopify/[path]` is an API proxy boundary
   - `robots.txt` and `sitemap.xml` are generated SEO endpoints

3. The storefront flow is organized around core ecommerce domains: home page, categories, collections, products, store/vendor pages, cart, checkout, auth, profile, orders, wishlist, messages, and order tracking. Product detail pages have their own local component set, showing that PDP behavior is a major subsystem rather than a simple generic page.

4. Data loading is split between SvelteKit server hooks/layouts and page-level loaders. Files like `+layout.server.ts`, `+page.server.ts`, and `+page.ts` indicate SSR-driven data fetches for initial page state, with client-side navigation enhancing SPA behavior after hydration.

5. The backend integration boundary lives in `src/lib/services` and is explicitly configurable. The README says only one service implementation is active at a time, with supported connector targets such as Litekart and Medusa, and the proxy route exists to adapt third-party API paths without exposing the backend directly to the browser.

6. `src/lib/core` is the app’s shared architecture layer. It contains reusable logic, service exports, load-function helpers, stores, hooks, composables, utilities, and core components. This is where cross-cutting concerns like viewport detection, collection state, theme handling, and loading behavior are centralized.

7. UI is heavily componentized. `src/lib/components` contains feature components for auth, address, checkout, cart, coupon, navigation, home, page blocks, product catalogue, and order UI. In parallel, `src/lib/components/ui` provides a large primitive design system for dialogs, drawers, buttons, tables, forms, tabs, selects, carousel, sidebar, and other reusable controls.

8. The checkout and account areas are distinct subsystems. Checkout is broken into steps and pages for cart, address, payment, process, success, and failure. The customer area under `(my)` handles orders, addresses, profile, wishlist, and buy-again behavior, implying authenticated state and server-side authorization checks.

9. The content and merchandising layer is separate from pure catalog pages. Home page banners, collection carousels, featured products, featured categories, rich text blocks, Instagram/share/WhatsApp-style plugins, and product aggregations show that the storefront is designed to be driven by configurable page sections rather than hardcoded layouts.

10. Assets and presentation are part of the app package, not a separate service. Media lives in `src/lib/assets` and `static`, while styling is handled through app CSS, Tailwind/PostCSS, and Svelte components. This supports themeable storefronts and image-heavy merchandising.

11. Operationally, the repo is built for multiple deployment targets: Vercel, Docker, and a PM2-based setup in `devops`. There are helper scripts for copying and deploying, plus manifest generation, which suggests the app can be packaged and hosted in several production environments without changing the core architecture.

12. Test coverage is split between unit/component tests and browser flows. `tests/*.test.ts` covers lower-level UI and logic, while `tests/*.spec.ts` and Playwright config cover end-to-end storefront journeys like navigation, product browsing, checkout, login, and cart behavior.

13. The overall runtime picture is: browser client → SvelteKit pages/layouts → shared core/service layer → external commerce backend via connector/proxy. The repo’s key architectural choice is that the storefront owns presentation, routing, and customer flows, while catalog/order/payment data come from whichever backend connector is selected.

Main entry points: [`src/routes`](https://github.com/itswadesh/svelte-commerce/tree/main/src/routes) (Storefront app), [`src/lib/components`](https://github.com/itswadesh/svelte-commerce/tree/main/src/lib/components) (Feature UI), [`src/routes/(www)`](https://github.com/itswadesh/svelte-commerce/tree/main/src/routes/(www)) (Public flow), [`src/lib/core`](https://github.com/itswadesh/svelte-commerce/tree/main/src/lib/core) (Core layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["SvelteKit app"]
  node_root["Storefront app<br/>SvelteKit storefront"]
  node_storefront["Public flow<br/>route group"]
  node_customer["My account<br/>route group"]
  node_legal["Legal pages<br/>route group"]
  node_product["Product pages<br/>PDP subsystem"]
  node_checkout["Checkout flow<br/>multi-step flow"]
  node_auth["Auth flow<br/>auth routes"]
  node_seo["SEO endpoints<br/>generated routes<br/>[robots.txt]"]
  node_proxy["Backend proxy<br/>API proxy"]
  node_layouts["SSR layouts<br/>load boundary<br/>[+layout.server.ts]"]
end

subgraph group_core["Shared core"]
  node_corelib["Core layer<br/>shared architecture"]
  node_services["Services<br/>backend connectors"]
  node_components["Feature UI<br/>feature components"]
  node_primitives["UI primitives<br/>design system"]
  node_hooks["Hooks & stores<br/>client state"]
  node_assets[("Assets & styles<br/>presentation assets")]
end

subgraph group_ops["Operations"]
  node_deploy["Deploy tools<br/>ops scripts"]
end

subgraph group_qa["Tests"]
  node_unit["Unit tests"]
  node_e2e["E2E tests<br/>browser flows"]
end

node_root -->|"routes"| node_storefront
node_root -->|"routes"| node_customer
node_root -->|"routes"| node_legal
node_root -->|"generates"| node_seo
node_root -->|"proxies"| node_proxy
node_root -->|"boots"| node_layouts
node_storefront -->|"includes"| node_product
node_storefront -->|"includes"| node_checkout
node_storefront -->|"includes"| node_auth
node_storefront -->|"renders with"| node_components
node_customer -->|"renders with"| node_components
node_legal -->|"renders with"| node_components
node_product -->|"uses"| node_components
node_checkout -->|"uses"| node_components
node_auth -->|"uses"| node_primitives
node_components -->|"built on"| node_primitives
node_corelib -->|"exports"| node_services
node_corelib -->|"centralizes"| node_hooks
node_corelib -->|"shares"| node_components
node_corelib -->|"supports"| node_layouts
node_services -->|"connects via"| node_proxy
node_assets -->|"supplies"| node_components
node_deploy -->|"packages"| node_root
node_unit -->|"covers"| node_primitives
node_unit -->|"covers"| node_corelib
node_e2e -->|"covers"| node_storefront
node_e2e -->|"covers"| node_checkout
node_e2e -->|"covers"| node_auth

click node_root "https://github.com/itswadesh/svelte-commerce/tree/main/src/routes"
click node_storefront "https://github.com/itswadesh/svelte-commerce/tree/main/src/routes/(www)"
click node_customer "https://github.com/itswadesh/svelte-commerce/tree/main/src/routes/(my)"
click node_legal "https://github.com/itswadesh/svelte-commerce/tree/main/src/routes/(legal)"
click node_product "https://github.com/itswadesh/svelte-commerce/tree/main/src/routes/(www)/products/[slug]"
click node_checkout "https://github.com/itswadesh/svelte-commerce/tree/main/src/routes/(www)/checkout"
click node_auth "https://github.com/itswadesh/svelte-commerce/tree/main/src/routes/(www)/auth"
click node_seo "https://github.com/itswadesh/svelte-commerce/blob/main/src/routes/robots.txt"
click node_proxy "https://github.com/itswadesh/svelte-commerce/tree/main/src/routes/proxy/shopify/[path]"
click node_layouts "https://github.com/itswadesh/svelte-commerce/blob/main/src/routes/+layout.server.ts"
click node_corelib "https://github.com/itswadesh/svelte-commerce/tree/main/src/lib/core"
click node_services "https://github.com/itswadesh/svelte-commerce/tree/main/src/lib/core/services"
click node_components "https://github.com/itswadesh/svelte-commerce/tree/main/src/lib/components"
click node_primitives "https://github.com/itswadesh/svelte-commerce/tree/main/src/lib/components/ui"
click node_hooks "https://github.com/itswadesh/svelte-commerce/tree/main/src/lib/core/hooks"
click node_assets "https://github.com/itswadesh/svelte-commerce/tree/main/src/lib/assets"
click node_deploy "https://github.com/itswadesh/svelte-commerce/tree/main/devops"
click node_unit "https://github.com/itswadesh/svelte-commerce/tree/main/tests"
click node_e2e "https://github.com/itswadesh/svelte-commerce/tree/main/tests"

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_root,node_storefront,node_customer,node_legal,node_product,node_checkout,node_auth,node_seo,node_proxy,node_layouts toneBlue
class node_corelib,node_services,node_components,node_primitives,node_hooks,node_assets toneAmber
class node_deploy toneMint
class node_unit,node_e2e toneRose
```

## Components

### SvelteKit app

Frontend storefront application, route boundaries, and shared app layer.

- [Storefront app](https://github.com/itswadesh/svelte-commerce/tree/main/src/routes): SvelteKit storefront · Headless ecommerce frontend that owns routing, presentation, and customer flows. · `src/routes`
- [Public flow](https://github.com/itswadesh/svelte-commerce/tree/main/src/routes/(www)): route group · Public storefront for discovery, product browsing, and commerce actions. · `src/routes/(www)`
- [My account](https://github.com/itswadesh/svelte-commerce/tree/main/src/routes/(my)): route group · Authenticated customer area for profile, orders, wishlist, and addresses. · `src/routes/(my)`
- [Legal pages](https://github.com/itswadesh/svelte-commerce/tree/main/src/routes/(legal)): route group · Static and content-oriented pages such as policies, blog, and FAQs. · `src/routes/(legal)`
- [Product pages](https://github.com/itswadesh/svelte-commerce/tree/main/src/routes/(www)/products/[slug]): PDP subsystem · Product detail route with its own local component set for gallery, pricing, specs, reviews, and related items. · `src/routes/(www)/products/[slug]`
- [Checkout flow](https://github.com/itswadesh/svelte-commerce/tree/main/src/routes/(www)/checkout): multi-step flow · Cart-to-success path covering cart, address, payment, processing, success, and failure states. · `src/routes/(www)/checkout`
- [Auth flow](https://github.com/itswadesh/svelte-commerce/tree/main/src/routes/(www)/auth): auth routes · Login, signup, verification, password reset, and vendor onboarding paths. · `src/routes/(www)/auth`
- [SEO endpoints](https://github.com/itswadesh/svelte-commerce/blob/main/src/routes/robots.txt): generated routes · robots.txt and sitemap.xml generation for search indexing. · `src/routes/robots.txt`
- [Backend proxy](https://github.com/itswadesh/svelte-commerce/tree/main/src/routes/proxy/shopify/[path]): API proxy · Path adapter boundary that forwards selected backend requests without exposing the service directly. · `src/routes/proxy/shopify/[path]`
- [SSR layouts](https://github.com/itswadesh/svelte-commerce/blob/main/src/routes/+layout.server.ts): load boundary · Root and section layouts/loaders that establish server-rendered app state and navigation context. · `src/routes/+layout.server.ts`

### Shared core

Reusable logic, services, hooks, and UI building blocks.

- [Core layer](https://github.com/itswadesh/svelte-commerce/tree/main/src/lib/core): shared architecture · Reusable application layer for cross-cutting state, hooks, load helpers, logic, and component exports. · `src/lib/core`
- [Services](https://github.com/itswadesh/svelte-commerce/tree/main/src/lib/core/services): backend connectors · Configurable commerce service implementations; only one connector is active at a time. · `src/lib/core/services`
- [Feature UI](https://github.com/itswadesh/svelte-commerce/tree/main/src/lib/components): feature components · Domain components for auth, cart, checkout, home, product catalogue, orders, navigation, and content sections. · `src/lib/components`
- [UI primitives](https://github.com/itswadesh/svelte-commerce/tree/main/src/lib/components/ui): design system · Reusable component library for dialogs, drawers, forms, tables, tabs, selects, carousel, sidebar, and more. · `src/lib/components/ui`
- [Hooks & stores](https://github.com/itswadesh/svelte-commerce/tree/main/src/lib/core/hooks): client state · Shared client behaviors such as viewport detection, theme handling, and collection state. · `src/lib/core/hooks`
- [Assets & styles](https://github.com/itswadesh/svelte-commerce/tree/main/src/lib/assets): presentation assets · Images, static media, app styles, and themeable presentation resources. · `src/lib/assets`

### Operations

Deployment, build, and packaging helpers.

- [Deploy tools](https://github.com/itswadesh/svelte-commerce/tree/main/devops): ops scripts · Build and deployment helpers for Docker, Vercel, and PM2-based hosting. · `devops`

### Tests

Unit, component, and end-to-end coverage.

- [Unit tests](https://github.com/itswadesh/svelte-commerce/tree/main/tests): tests · Component and logic tests for UI primitives, services, utilities, and validation behavior. · `tests`
- [E2E tests](https://github.com/itswadesh/svelte-commerce/tree/main/tests): browser flows · Playwright-style browser journeys covering navigation, product browsing, cart, checkout, and login. · `tests`

## Connections

- Storefront app → Public flow: routes · Public storefront boundary.
- Storefront app → My account: routes · Authenticated customer area.
- Storefront app → Legal pages: routes · Static content and policy pages.
- Storefront app → SEO endpoints: generates · SEO output routes.
- Storefront app → Backend proxy: proxies · Backend API adaptation boundary.
- Storefront app → SSR layouts: boots · Server/client layouts establish app state.
- Public flow → Product pages: includes · PDP subsystem inside commerce flow.
- Public flow → Checkout flow: includes · Shopping cart and checkout journey.
- Public flow → Auth flow: includes · Public authentication and onboarding flow.
- Public flow → Feature UI: renders with · Feature components drive storefront sections.
- My account → Feature UI: renders with · Account UI reuses domain components.
- Legal pages → Feature UI: renders with · Content pages use shared layout components.
- Product pages → Feature UI: uses · Local PDP pieces compose the detail page.
- Checkout flow → Feature UI: uses · Checkout steps use feature UI components.
- Auth flow → UI primitives: uses · Forms, dialogs, and inputs support auth flows.
- Feature UI → UI primitives: built on · Feature UI composes the design system.
- Core layer → Services: exports · Connector and service layer lives under core.
- Core layer → Hooks & stores: centralizes · Shared client state and behaviors.
- Core layer → Feature UI: shares · Reusable core components and plugins.
- Core layer → SSR layouts: supports · Load helpers and SSR utilities feed route loaders.
- Services → Backend proxy: connects via · Proxy route adapts external commerce APIs.
- Assets & styles → Feature UI: supplies · Media and styling assets feed rendered UI.
- Deploy tools → Storefront app: packages · Operational scripts target the app for deployment.
- Unit tests → UI primitives: covers · Tests validate shared UI and logic.
- Unit tests → Core layer: covers · Tests validate shared architecture code.
- E2E tests → Public flow: covers · Browser flows exercise storefront journeys.
- E2E tests → Checkout flow: covers · Checkout journey is verified end to end.
- E2E tests → Auth flow: covers · Login and signup flows are browser tested.