Sub-documents

Document	Topic
commerce-types.md	Schema.org types reference — Product, Offer, PDP, PLP, Analytics
shared-utils.md	Shared utilities — HTTP client, GraphQL, fetch, cookie, normalize
app-pattern.md	The Deco App Pattern — mod.ts, manifest, runtime, hooks, context
vtex-deep-structure.md	VTEX app deep dive — all 141 files, endpoints, data flow
website-app.md	Website app — routing, SEO, handlers, matchers, A/B testing
scripts-codegen.md	Scripts & codegen — OpenAPI, GraphQL, templates, CI/CD
new-app-guide.md	Creating a new app — step-by-step guide with commerce template

deco-cx/apps Architecture

Reference for the deco-cx/apps monorepo — the canonical library of Deco integrations.

Monorepo Overview

apps/
├── deco.ts              # App registry — lists all ~90 apps
├── deno.json            # Deno config, import map, tasks
├── scripts/             # Codegen and project scaffolding
│   ├── start.ts         # OpenAPI/GraphQL codegen + bundle
│   └── new.ts           # App/MCP template generator
├── utils/               # Shared utilities (all apps can import)
├── commerce/            # Schema.org commerce types + shared loaders
├── website/             # Base website app (routing, SEO, analytics, image)
├── admin/               # Admin widget types
├── compat/              # Legacy compatibility ($live, std)
├── workflows/           # Deco workflow engine
├── vtex/                # VTEX integration (141 files)
├── shopify/             # Shopify integration
├── nuvemshop/           # Nuvemshop integration
├── wake/                # Wake integration
├── wap/                 # Wap integration
└── (80+ more apps)      # AI, analytics, CRM, payments, etc.

The App Pattern

Every app follows the same structure:

{app-name}/
├── mod.ts               # App factory — exports Props, AppContext, state
├── manifest.gen.ts      # Auto-generated — registers all blocks
├── runtime.ts           # Client-side invoke proxy (optional)
├── middleware.ts         # Request middleware (optional)
├── actions/             # Write operations (mutations)
├── loaders/             # Read operations (data fetching)
├── hooks/               # Client-side Preact hooks (optional)
├── sections/            # CMS-renderable UI sections (optional)
├── handlers/            # HTTP request handlers (optional)
├── components/          # Shared Preact components (optional)
├── utils/               # Internal utilities and types
│   ├── types.ts         # API response/request types
│   ├── client.ts        # Typed HTTP client definitions
│   ├── transform.ts     # API → schema.org mapping (commerce apps)
│   └── openapi/         # Auto-generated OpenAPI types (optional)
├── workflows/           # Background workflow definitions (optional)
└── preview/             # Admin preview UI (optional)

mod.ts Pattern

import manifest, { Manifest } from "./manifest.gen.ts";
import { type App, type AppContext as AC } from "@deco/deco";

export type AppContext = AC<ReturnType<typeof MyApp>>;

export interface Props {
  account: string;
  apiKey?: Secret;
  // ...
}

export default function MyApp(props: Props) {
  const state = { /* clients, config */ };
  const app: App<Manifest, typeof state> = { manifest, state };
  return app;
}

manifest.gen.ts

Auto-generated by Deco. Registers all actions, loaders, handlers, sections, workflows as blocks.

runtime.ts

import { Manifest } from "./manifest.gen.ts";
import { proxy } from "@deco/deco/web";
export const invoke = proxy<Manifest>();

Shared Utils (/utils/)

File	Purpose
http.ts	createHttpClient<T> — typed HTTP client from OpenAPI specs
graphql.ts	createGraphqlClient — typed GraphQL client
fetch.ts	fetchSafe, fetchAPI, retry with exponential backoff, STALE cache headers
cookie.ts	proxySetCookie, getFlagsFromCookies
normalize.ts	removeDirtyCookies, removeNonLatin1Chars
lru.ts	LRU cache implementation
shortHash.ts	SHA-256 string hashing
pool.ts	Resource pool with acquire/release
worker.ts	Web Worker abstraction (Comlink-style)
dataURI.ts	Script-to-data-URI conversion
capitalize.ts	String capitalization

Commerce Module (/commerce/)

The shared commerce layer — platform-agnostic types and utilities.

commerce/
├── types.ts             # Schema.org types (Product, Offer, BreadcrumbList, etc.)
├── mod.ts               # Composes website + platform (vtex/shopify/wake/vnda)
├── manifest.gen.ts
├── loaders/
│   ├── extensions/      # Product page/list/PLP enrichment
│   ├── navbar.ts        # Navigation loader
│   └── product/         # Product query orchestration
├── sections/Seo/        # SEO sections for PDP/PLP
└── utils/
    ├── filters.ts       # parseRange, formatRange
    ├── constants.ts     # DEFAULT_IMAGE placeholder
    ├── canonical.ts     # Canonical URL from breadcrumb
    ├── productToAnalyticsItem.ts  # Product → GA4 AnalyticsItem
    └── stateByZip.ts    # Brazilian state from ZIP code

Key Types (types.ts)

Type	Purpose
Product	Schema.org Product with offers, images, variants
ProductGroup	Product with hasVariant[]
Offer / AggregateOffer	Pricing and availability
ProductDetailsPage	PDP data (product + breadcrumb + SEO)
ProductListingPage	PLP data (products + filters + pagination + SEO)
BreadcrumbList	Navigation path
Filter / FilterToggle / FilterRange	Faceted search filters
Suggestion	Autocomplete results
AnalyticsItem	GA4 event item format
SiteNavigationElement	Menu/navbar structure

VTEX App Structure (/vtex/)

The largest integration (141 files). For detailed VTEX-specific docs, see the deco-apps-vtex-porting and deco-apps-vtex-review skills.

vtex/
├── actions/           # 43 files across 11 subdirs
│   ├── cart/          # 16 actions (addItems, updateItems, updateCoupons, etc.)
│   ├── authentication/# 8 actions (signIn, logout, recovery, etc.)
│   ├── address/       # 3 (create, update, delete)
│   ├── session/       # 3 (create, edit, delete)
│   ├── wishlist/      # 2 (add, remove)
│   ├── newsletter/    # 2 (subscribe, updateOptIn)
│   ├── masterdata/    # 2 (create, update document)
│   └── (orders, payment, profile, review, analytics)
├── loaders/           # 50+ files across 15 subdirs
│   ├── intelligentSearch/  # 6 (PDP, PLP, productList, suggestions, topSearches, validator)
│   ├── legacy/             # 7 (PDP, PLP, productList, suggestions, brands, pageType, related)
│   ├── logistics/          # 5 (salesChannel, pickupPoints, stock)
│   ├── workflow/           # 2 (product, products)
│   └── (address, cart, categories, collections, orders, payment, profile, session, etc.)
├── hooks/             # 5 (context, useCart, useUser, useWishlist, useAutocomplete)
├── utils/             # 31 files
│   ├── transform.ts   # Canonical VTEX → schema.org mapping (THE key file)
│   ├── types.ts       # 1320 lines of VTEX API types
│   ├── client.ts      # SP, VTEXCommerceStable client definitions
│   ├── openapi/       # 12 files — auto-generated from VTEX OpenAPI specs
│   └── (cookies, segment, intelligentSearch, legacy, vtexId, etc.)
└── (middleware, handlers/sitemap, sections/Analytics, workflows, components, preview)

Shopify App Structure (/shopify/)

shopify/
├── actions/cart/       # addItems, updateCoupons, updateItems
├── actions/order/      # draftOrderCalculate
├── actions/user/       # signIn, signUp
├── hooks/              # context, useCart, useUser
├── loaders/            # PDP, PLP, ProductList, RelatedProducts, cart, shop, user, proxy
└── utils/
    ├── admin/          # Admin API queries
    ├── storefront/     # Storefront API (GraphQL schema + generated types)
    └── transform.ts    # Shopify → schema.org mapping

Website App (/website/)

Base app that all storefronts use. Handles routing, SEO, analytics, image optimization, and theme.

Key areas:

• handlers/ — Fresh router, proxy, redirect, sitemap
• loaders/ — Pages, fonts, images, redirects, secrets, environment
• sections/ — Analytics (GA, GTM, Pixel), Rendering, SEO
• matchers/ — Audience targeting (device, cookie, date, location, etc.)
• flags/ — A/B testing, multivariate, audience segmentation

Scripts (/scripts/)

Script	Purpose
start.ts	Runs on deno task start — generates OpenAPI types, GraphQL types, bundles
new.ts	Scaffolds new app from template — deno task new

CI/CD (.github/workflows/)

Workflow	Trigger	Purpose
ci.yaml	Push/PR	Bundle, fmt check, lint, test, bench
release.yaml	Tag push	Publish release
releaser.yaml	PR/comment	Version bump, tag creation

Relationship: apps → apps-start

deco-cx/apps (Fresh/Deno)          @decocms/apps-start (TanStack/Node)
────────────────────────           ─────────────────────────────────
vtex/utils/transform.ts      →    vtex/utils/transform.ts (ported)
vtex/utils/types.ts          →    vtex/utils/types.ts (ported)
vtex/loaders/**              →    vtex/loaders/** + vtex/inline-loaders/**
vtex/actions/**              →    vtex/actions/** (consolidated)
vtex/hooks/**                →    vtex/hooks/** (React + TanStack Query)
commerce/types.ts            →    commerce/types/commerce.ts
commerce/utils/**            →    commerce/utils/** + commerce/sdk/**
utils/fetch.ts               →    Replaced by vtexFetch/vtexFetchWithCookies
utils/http.ts                →    Not needed (no OpenAPI codegen in apps-start)
utils/graphql.ts             →    vtexIOGraphQL in client.ts

Key differences:

• apps-start has no mod.ts / manifest.gen.ts / runtime.ts (no Deco framework)
• apps-start uses configureVtex() instead of app factory pattern
• apps-start loaders are pure async functions, not Deco blocks
• apps-start hooks use @tanstack/react-query instead of @preact/signals
• apps-start has no OpenAPI codegen — uses manual vtexFetch calls