---
name: deco-apps-architecture
description: Architecture reference for deco-cx/apps monorepo — the canonical Deco commerce integration library. Covers the monorepo structure with 90+ apps (VTEX, Shopify, Nuvemshop, Wake, etc.), shared utils (HTTP client, GraphQL, fetch, cookies, LRU cache), commerce types (schema.org), the app pattern (mod.ts, manifest.gen.ts, actions/, loaders/, hooks/, utils/), and the relationship between deco-cx/apps (Fresh/Deno) and @decocms/apps-start (TanStack/Node). Use when exploring the apps repo, understanding how a Deco app is structured, creating new integrations, or porting apps to TanStack Start.
globs:
  - "**/deco.ts"
  - "**/manifest.gen.ts"
  - "**/mod.ts"
  - "**/runtime.ts"
---

## Sub-documents

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

```typescript
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

```typescript
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
