# ecombio/storefront architecture

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

- Interactive diagram: https://gitdiagram.com/ecombio/storefront
- Repository: https://github.com/ecombio/storefront

## Overview

Ecombio is a headless Shopify storefront: shoppers browse and search the catalog, inspect products, manage a cart, and proceed to Shopify-hosted checkout; signed-in customers can also manage account details and orders. The repository includes complementary discovery surfaces for Markdown and agent commerce, plus reviews and Shopify-driven cache refresh. The tree and sampled routes support these major areas, but most page and data-layer implementations were not sampled, so some internal wiring is intentionally left out.

Main entry points: [`components/collections`](https://github.com/ecombio/storefront/tree/main/components/collections) (Catalog and product UI), [`components/cart`](https://github.com/ecombio/storefront/tree/main/components/cart) (Cart UI), [`app/md`](https://github.com/ecombio/storefront/tree/main/app/md) (Markdown endpoints), [`app/api/yotpo/reviews/route.ts`](https://github.com/ecombio/storefront/blob/main/app/api/yotpo/reviews/route.ts) (Review endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_storefront["Storefront browsing"]
  node_storefront_pages["Store pages"]
  node_catalog_ui["Catalog and product UI"]
  node_search_ui["Search UI"]
end

subgraph group_commerce["Cart and accounts"]
  node_cart_ui["Cart UI"]
  node_cart_server["Cart operations<br/>[server.ts]"]
  node_account_pages["Customer account"]
  node_customer_auth["Customer sessions<br/>[server.ts]"]
end

subgraph group_discovery["Agent discovery"]
  node_markdown_routes["Markdown endpoints"]
  node_storefront_guide["Storefront guide<br/>[route.ts]"]
  node_ucp_profile["UCP profile<br/>[route.ts]"]
  node_shop_agent["Shop Agent<br/>[agent.ts]"]
  node_agent_session["Agent session<br/>[route.ts]"]
end

subgraph group_integrations["External integrations"]
  node_checkout["Hosted checkout"]
  node_customer_api["Customer Account API"]
  node_review_submission["Review endpoint<br/>[route.ts]"]
  node_yotpo["Yotpo reviews"]
  node_shopify_webhook["Shopify webhook<br/>[route.ts]"]
end

subgraph group_data["Shopify data"]
  node_product_data["Product data<br/>[server.ts]"]
  node_collection_data["Collection data<br/>[server.ts]"]
  node_search_data["Search data<br/>[server.ts]"]
  node_shopify_storefront["Storefront API<br/>[server.ts]"]
  node_cache[("Tagged cache")]
end

node_shopper(("Shopper"))
node_ai_agent(("AI agent"))
node_shopify["Shopify"]

node_shopper -->|"browses"| node_storefront_pages
node_storefront_pages -->|"renders"| node_catalog_ui
node_catalog_ui -->|"loads collections"| node_collection_data
node_catalog_ui -->|"loads products"| node_product_data
node_shopper -->|"searches"| node_search_ui
node_search_ui -->|"requests results"| node_search_data
node_shopify_storefront -->|"queries catalog"| node_shopify
node_shopper -->|"manages cart"| node_cart_ui
node_cart_ui -->|"updates cart"| node_cart_server
node_cart_server -->|"reads and writes"| node_shopify_storefront
node_cart_ui -->|"starts checkout"| node_checkout
node_shopper -->|"manages account"| node_account_pages
node_account_pages -->|"checks session"| node_customer_auth
node_customer_auth -->|"authenticates"| node_customer_api
node_ai_agent -.->|"reads guide"| node_storefront_guide
node_storefront_guide -->|"lists collections"| node_collection_data
node_ai_agent -.->|"fetches Markdown"| node_markdown_routes
node_markdown_routes -->|"loads search"| node_search_data
node_markdown_routes -->|"loads products"| node_product_data
node_ai_agent -.->|"discovers commerce"| node_ucp_profile
node_shopper -.->|"chats with"| node_shop_agent
node_shop_agent -.->|"prepares session"| node_agent_session
node_agent_session -.->|"creates or reads cart"| node_cart_server
node_shopper -->|"submits review"| node_review_submission
node_review_submission -->|"resolves product"| node_product_data
node_review_submission -->|"submits review"| node_yotpo
node_shopify -->|"sends event"| node_shopify_webhook
node_shopify_webhook -->|"invalidates tags"| node_cache

click node_storefront_pages "https://github.com/ecombio/storefront/tree/main/app"
click node_catalog_ui "https://github.com/ecombio/storefront/tree/main/components/collections"
click node_search_ui "https://github.com/ecombio/storefront/tree/main/components/search"
click node_product_data "https://github.com/ecombio/storefront/blob/main/lib/product/server.ts"
click node_collection_data "https://github.com/ecombio/storefront/blob/main/lib/collections/server.ts"
click node_search_data "https://github.com/ecombio/storefront/blob/main/lib/search/server.ts"
click node_shopify_storefront "https://github.com/ecombio/storefront/blob/main/lib/shopify/storefront/server.ts"
click node_cart_ui "https://github.com/ecombio/storefront/tree/main/components/cart"
click node_cart_server "https://github.com/ecombio/storefront/blob/main/lib/cart/server.ts"
click node_account_pages "https://github.com/ecombio/storefront/tree/main/app/account/(authenticated)"
click node_customer_auth "https://github.com/ecombio/storefront/blob/main/lib/auth/server.ts"
click node_markdown_routes "https://github.com/ecombio/storefront/tree/main/app/md"
click node_storefront_guide "https://github.com/ecombio/storefront/blob/main/app/llms.txt/route.ts"
click node_ucp_profile "https://github.com/ecombio/storefront/blob/main/app/agent/ucp-profile.json/route.ts"
click node_shop_agent "https://github.com/ecombio/storefront/blob/main/agent/agent.ts"
click node_agent_session "https://github.com/ecombio/storefront/blob/main/app/api/agent/session/route.ts"
click node_review_submission "https://github.com/ecombio/storefront/blob/main/app/api/yotpo/reviews/route.ts"
click node_shopify_webhook "https://github.com/ecombio/storefront/blob/main/app/api/webhooks/shopify/route.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_storefront_pages,node_catalog_ui,node_search_ui toneBlue
class node_cart_ui,node_cart_server,node_account_pages,node_customer_auth toneAmber
class node_markdown_routes,node_storefront_guide,node_ucp_profile,node_shop_agent,node_agent_session toneMint
class node_checkout,node_customer_api,node_review_submission,node_yotpo,node_shopify_webhook toneRose
class node_product_data,node_collection_data,node_search_data,node_shopify_storefront,node_cache,node_shopper,node_ai_agent,node_shopify toneIndigo
```

## Components

### Storefront browsing

- [Store pages](https://github.com/ecombio/storefront/tree/main/app): `app`
- [Catalog and product UI](https://github.com/ecombio/storefront/tree/main/components/collections): `components/collections`
- [Search UI](https://github.com/ecombio/storefront/tree/main/components/search): `components/search`

### Cart and accounts

- [Cart UI](https://github.com/ecombio/storefront/tree/main/components/cart): `components/cart`
- [Cart operations](https://github.com/ecombio/storefront/blob/main/lib/cart/server.ts): `lib/cart/server.ts`
- [Customer account](https://github.com/ecombio/storefront/tree/main/app/account/(authenticated)): `app/account/(authenticated)`
- [Customer sessions](https://github.com/ecombio/storefront/blob/main/lib/auth/server.ts): `lib/auth/server.ts`

### Agent discovery

- [Markdown endpoints](https://github.com/ecombio/storefront/tree/main/app/md): `app/md`
- [Storefront guide](https://github.com/ecombio/storefront/blob/main/app/llms.txt/route.ts): `app/llms.txt/route.ts`
- [UCP profile](https://github.com/ecombio/storefront/blob/main/app/agent/ucp-profile.json/route.ts): `app/agent/ucp-profile.json/route.ts`
- [Shop Agent](https://github.com/ecombio/storefront/blob/main/agent/agent.ts): `agent/agent.ts`
- [Agent session](https://github.com/ecombio/storefront/blob/main/app/api/agent/session/route.ts): `app/api/agent/session/route.ts`

### External integrations

- **Hosted checkout**
- **Customer Account API**
- [Review endpoint](https://github.com/ecombio/storefront/blob/main/app/api/yotpo/reviews/route.ts): `app/api/yotpo/reviews/route.ts`
- **Yotpo reviews**
- [Shopify webhook](https://github.com/ecombio/storefront/blob/main/app/api/webhooks/shopify/route.ts): `app/api/webhooks/shopify/route.ts`

### Shopify data

- [Product data](https://github.com/ecombio/storefront/blob/main/lib/product/server.ts): `lib/product/server.ts`
- [Collection data](https://github.com/ecombio/storefront/blob/main/lib/collections/server.ts): `lib/collections/server.ts`
- [Search data](https://github.com/ecombio/storefront/blob/main/lib/search/server.ts): `lib/search/server.ts`
- [Storefront API](https://github.com/ecombio/storefront/blob/main/lib/shopify/storefront/server.ts): `lib/shopify/storefront/server.ts`
- **Tagged cache**

### Other components

- **Shopper**
- **AI agent**
- **Shopify**

## Connections

- Shopper → Store pages: browses
- Store pages → Catalog and product UI: renders
- Catalog and product UI → Collection data: loads collections
- Catalog and product UI → Product data: loads products
- Shopper → Search UI: searches
- Search UI → Search data: requests results
- Storefront API → Shopify: queries catalog
- Shopper → Cart UI: manages cart
- Cart UI → Cart operations: updates cart
- Cart operations → Storefront API: reads and writes
- Cart UI → Hosted checkout: starts checkout
- Shopper → Customer account: manages account
- Customer account → Customer sessions: checks session
- Customer sessions → Customer Account API: authenticates
- AI agent → Storefront guide: reads guide
- Storefront guide → Collection data: lists collections
- AI agent → Markdown endpoints: fetches Markdown
- Markdown endpoints → Search data: loads search
- Markdown endpoints → Product data: loads products
- AI agent → UCP profile: discovers commerce
- Shopper → Shop Agent: chats with
- Shop Agent → Agent session: prepares session
- Agent session → Cart operations: creates or reads cart
- Shopper → Review endpoint: submits review
- Review endpoint → Product data: resolves product
- Review endpoint → Yotpo reviews: submits review
- Shopify → Shopify webhook: sends event
- Shopify webhook → Tagged cache: invalidates tags