# starkdockris/ecom-master architecture

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

- Interactive diagram: https://gitdiagram.com/starkdockris/ecom-master
- Repository: https://github.com/starkdockris/ecom-master

## Overview

#### Purpose and Runtime
This is a Next.js App Router storefront for product browsing, cart management, checkout, order confirmation, policy/content pages, and order tracking. The primary application entry is `app/layout.js`; the storefront landing route is `app/page.js`. Styling is globally initialized in `app/globals.css`.

#### Route Layer
Server-rendered route segments define the customer-facing site:
- Product catalog and product-detail routes: `app/products/page.js`, `app/products/[slug]/page.js`
- Purchase flow: `app/cart/page.js`, `app/checkout/page.js`, `app/order-confirmation/page.js`
- Informational and support routes: `app/contact/page.js`, `app/track-order/page.js`, `app/about/page.js`

SEO crawler endpoints are implemented as App Router modules in `app/robots.js` and `app/sitemap.js`.

#### Backend/API Boundary
`app/api/[[...path]]/route.js` is a catch-all API route, creating a single internal boundary for browser-to-backend requests. This likely isolates frontend pages and client components from the commerce service’s API shape and credentials.

Commerce access is centralized in `lib/wc.js`, indicating a WooCommerce-oriented external integration. Product fallback/bootstrap data is held separately in `lib/products-seed.js`, so product presentation can be decoupled from live backend availability.

#### Product Data and Presentation Flow
Catalog/detail routes obtain or receive product data, then render reusable product UI:
- Catalog cards: `components/products/product-card.jsx`
- Interactive detail experience: `components/products/product-detail-client.jsx`
- Product data/integration modules: `lib/products-seed.js`, `lib/wc.js`

The slug route (`app/products/[slug]/page.js`) is the key boundary between URL identity and product lookup. Client-side detail behavior is intentionally isolated from the route/server layer in `components/products/product-detail-client.jsx`.

#### Cart and Checkout State
Cart state is centralized in `lib/cart-context.js`, rather than being owned independently by product, cart, and checkout pages. The expected control flow is product-detail/card interaction → cart context mutation → cart drawer/cart page → checkout → confirmation.

Global cart access is surfaced through `components/layout/cart-drawer.jsx`; dedicated purchase stages are represented by `app/cart/page.js`, `app/checkout/page.js`, and `app/order-confirmation/page.js`. This separation makes cart state a cross-page client concern while checkout/order operations remain route-level workflows.

#### Shared Shell and Client Experience
The site shell is assembled from shared layout components:
- `components/layout/header.jsx`
- `components/layout/footer.jsx`
- `components/layout/cart-drawer.jsx`

Additional global interaction/presentation elements include `components/layout/page-loader.jsx`, `components/layout/whatsapp-button.jsx`, and `components/layout/mandala-background.jsx`. The UI component library under `components/ui/` supplies reusable primitives, while `components.json`, `tailwind.config.js`, and `postcss.config.js` indicate a Tailwind-based component styling stack.

#### Infrastructure and Supporting Boundaries
Next.js configuration is defined in `next.config.js`; path alias behavior is likely configured through `jsconfig.json`. The application’s material external dependency is the WooCommerce-like commerce backend accessed via `lib/wc.js` and exposed to clients through the catch-all API route. Static/public assets and branding guidance reside under `public/`, including `public/LOGO_INSTRUCTIONS.md`.

Main entry points: [`lib/cart-context.js`](https://github.com/starkdockris/ecom-master/blob/NEX/lib/cart-context.js) (Cart context), [`app/products/page.js`](https://github.com/starkdockris/ecom-master/blob/NEX/app/products/page.js) (Product catalog), [`lib/wc.js`](https://github.com/starkdockris/ecom-master/blob/NEX/lib/wc.js) (WooCommerce client), [`app/layout.js`](https://github.com/starkdockris/ecom-master/blob/NEX/app/layout.js) (Root layout)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_routes["App Router"]
  node_root_layout["Root layout<br/>Next.js entry<br/>[layout.js]"]
  node_global_styles["Global styles<br/>CSS<br/>[globals.css]"]
  node_landing["Storefront landing<br/>route<br/>[page.js]"]
  node_catalog["Product catalog<br/>route<br/>[page.js]"]
  node_product_route["Product slug route<br/>[page.js]"]
  node_purchase_routes["Purchase flow<br/>route workflow<br/>[page.js]"]
  node_content_routes["Content &amp; support<br/>routes<br/>[page.js]"]
  node_seo_endpoints["SEO endpoints<br/>metadata routes<br/>[robots.js]"]
end

subgraph group_ui["Shared UI &amp; State"]
  node_site_shell["Site shell<br/>layout components<br/>[header.jsx]"]
  node_cart_drawer["Cart drawer<br/>client component<br/>[cart-drawer.jsx]"]
  node_product_card["Product card<br/>product UI<br/>[product-card.jsx]"]
  node_product_detail_client["Product detail client<br/>client component"]
  node_cart_state{{"Cart context<br/>client state<br/>[cart-context.js]"}}
  node_ui_primitives["UI primitives<br/>component library"]
end

subgraph group_commerce["Commerce Data"]
  node_api_boundary["Catch-all API<br/>route handler<br/>[route.js]"]
  node_commerce_client{{"WooCommerce client<br/>integration<br/>[wc.js]"}}
  node_product_seed["Product seed data<br/>fallback data<br/>[products-seed.js]"]
  node_commerce_backend[("Commerce backend<br/>external service")]
end

node_root_layout -->|"initializes"| node_global_styles
node_root_layout -->|"assembles"| node_site_shell
node_root_layout -->|"provides"| node_cart_state
node_site_shell -->|"includes"| node_cart_drawer
node_cart_drawer -->|"reads and mutates"| node_cart_state
node_landing -.->|"leads to"| node_catalog
node_catalog -->|"renders"| node_product_card
node_catalog -->|"loads products"| node_commerce_client
node_catalog -.->|"falls back to"| node_product_seed
node_product_route -->|"looks up slug"| node_commerce_client
node_product_route -->|"renders"| node_product_detail_client
node_product_detail_client -->|"adds items"| node_cart_state
node_product_card -->|"adds items"| node_cart_state
node_cart_state -->|"drives cart and checkout"| node_purchase_routes
node_purchase_routes -->|"submits commerce requests"| node_api_boundary
node_api_boundary -->|"delegates"| node_commerce_client
node_commerce_client -->|"calls"| node_commerce_backend
node_product_card -.->|"uses"| node_ui_primitives
node_product_detail_client -.->|"uses"| node_ui_primitives

click node_root_layout "https://github.com/starkdockris/ecom-master/blob/NEX/app/layout.js"
click node_global_styles "https://github.com/starkdockris/ecom-master/blob/NEX/app/globals.css"
click node_landing "https://github.com/starkdockris/ecom-master/blob/NEX/app/page.js"
click node_catalog "https://github.com/starkdockris/ecom-master/blob/NEX/app/products/page.js"
click node_product_route "https://github.com/starkdockris/ecom-master/blob/NEX/app/products/%5Bslug%5D/page.js"
click node_purchase_routes "https://github.com/starkdockris/ecom-master/blob/NEX/app/cart/page.js"
click node_content_routes "https://github.com/starkdockris/ecom-master/blob/NEX/app/contact/page.js"
click node_seo_endpoints "https://github.com/starkdockris/ecom-master/blob/NEX/app/robots.js"
click node_site_shell "https://github.com/starkdockris/ecom-master/blob/NEX/components/layout/header.jsx"
click node_cart_drawer "https://github.com/starkdockris/ecom-master/blob/NEX/components/layout/cart-drawer.jsx"
click node_product_card "https://github.com/starkdockris/ecom-master/blob/NEX/components/products/product-card.jsx"
click node_product_detail_client "https://github.com/starkdockris/ecom-master/blob/NEX/components/products/product-detail-client.jsx"
click node_cart_state "https://github.com/starkdockris/ecom-master/blob/NEX/lib/cart-context.js"
click node_api_boundary "https://github.com/starkdockris/ecom-master/blob/NEX/app/api/%5B%5B...path%5D%5D/route.js"
click node_commerce_client "https://github.com/starkdockris/ecom-master/blob/NEX/lib/wc.js"
click node_product_seed "https://github.com/starkdockris/ecom-master/blob/NEX/lib/products-seed.js"

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_layout,node_global_styles,node_landing,node_catalog,node_product_route,node_purchase_routes,node_content_routes,node_seo_endpoints toneBlue
class node_site_shell,node_cart_drawer,node_product_card,node_product_detail_client,node_cart_state,node_ui_primitives toneAmber
class node_api_boundary,node_commerce_client,node_product_seed,node_commerce_backend toneMint
```

## Components

### App Router

Customer routes and crawler endpoints.

- [Root layout](https://github.com/starkdockris/ecom-master/blob/NEX/app/layout.js): Next.js entry · Assembles global providers and site chrome. · `app/layout.js`
- [Global styles](https://github.com/starkdockris/ecom-master/blob/NEX/app/globals.css): CSS · `app/globals.css`
- [Storefront landing](https://github.com/starkdockris/ecom-master/blob/NEX/app/page.js): route · `app/page.js`
- [Product catalog](https://github.com/starkdockris/ecom-master/blob/NEX/app/products/page.js): route · `app/products/page.js`
- [Product slug route](https://github.com/starkdockris/ecom-master/blob/NEX/app/products/%5Bslug%5D/page.js): route · Maps URL slugs to product lookup and detail rendering. · `app/products/[slug]/page.js`
- [Purchase flow](https://github.com/starkdockris/ecom-master/blob/NEX/app/cart/page.js): route workflow · Cart, checkout, and confirmation stages. · `app/cart/page.js`
- [Content & support](https://github.com/starkdockris/ecom-master/blob/NEX/app/contact/page.js): routes · Contact, tracking, and about pages. · `app/contact/page.js`
- [SEO endpoints](https://github.com/starkdockris/ecom-master/blob/NEX/app/robots.js): metadata routes · Robots and sitemap responses. · `app/robots.js`

### Shared UI & State

Cross-page shell, product UI, and cart state.

- [Site shell](https://github.com/starkdockris/ecom-master/blob/NEX/components/layout/header.jsx): layout components · Header, footer, loader, background, and WhatsApp affordance. · `components/layout/header.jsx`
- [Cart drawer](https://github.com/starkdockris/ecom-master/blob/NEX/components/layout/cart-drawer.jsx): client component · Global cart access from the shared shell. · `components/layout/cart-drawer.jsx`
- [Product card](https://github.com/starkdockris/ecom-master/blob/NEX/components/products/product-card.jsx): product UI · `components/products/product-card.jsx`
- [Product detail client](https://github.com/starkdockris/ecom-master/blob/NEX/components/products/product-detail-client.jsx): client component · Isolates interactive detail behavior from the slug route. · `components/products/product-detail-client.jsx`
- [Cart context](https://github.com/starkdockris/ecom-master/blob/NEX/lib/cart-context.js): client state · Centralized cart state shared across purchase surfaces. · `lib/cart-context.js`
- **UI primitives**: component library

### Commerce Data

Internal API boundary and WooCommerce access.

- [Catch-all API](https://github.com/starkdockris/ecom-master/blob/NEX/app/api/%5B%5B...path%5D%5D/route.js): route handler · Internal browser-to-commerce boundary. · `app/api/[[...path]]/route.js`
- [WooCommerce client](https://github.com/starkdockris/ecom-master/blob/NEX/lib/wc.js): integration · Centralized external commerce access. · `lib/wc.js`
- [Product seed data](https://github.com/starkdockris/ecom-master/blob/NEX/lib/products-seed.js): fallback data · Bootstrap or fallback product data. · `lib/products-seed.js`
- **Commerce backend**: external service · WooCommerce-oriented product and order service.

## Connections

- Root layout → Global styles: initializes
- Root layout → Site shell: assembles
- Root layout → Cart context: provides
- Site shell → Cart drawer: includes
- Cart drawer → Cart context: reads and mutates
- Storefront landing → Product catalog: leads to
- Product catalog → Product card: renders
- Product catalog → WooCommerce client: loads products
- Product catalog → Product seed data: falls back to
- Product slug route → WooCommerce client: looks up slug
- Product slug route → Product detail client: renders
- Product detail client → Cart context: adds items
- Product card → Cart context: adds items
- Cart context → Purchase flow: drives cart and checkout
- Purchase flow → Catch-all API: submits commerce requests
- Catch-all API → WooCommerce client: delegates
- WooCommerce client → Commerce backend: calls
- Product card → UI primitives: uses
- Product detail client → UI primitives: uses