Business Logic

Overview

25 service files in packages/merch/srv/src/ (package @zooly/merch-srv) covering the full backend logic. Payment integration is handled by @zooly/srv-stripe-payment.

AI Art Generation

generateConsistentAIArt (generate-ai-art.ts)

Sequential generation with character consistency scoring, configurable quality tiers, and user-driven regeneration:

1. Receive a qualityTiers: QualityTier[] array (e.g. ["low", "medium", "high"]) from the resolved design config; fall back to DEFAULT_QUALITY_TIERS if not set
2. Iterate once per entry in qualityTiers, generating one image per tier at that quality level via generateAIArt() (Vercel AI Gateway)
3. Post-process each result with downloadAndProcessAIImage(), upload to S3, then score with validateCharacterConsistency() (Gemini vision)
4. Keep all generated candidates; return all as candidates sorted by likeness score
5. New candidates are prepended to any existing ones from prior generations in the session's aiArtCandidates
6. The user can click "Regenerate" to request another attempt with forceRegenerate: true, bypassing the server-side generation cache; all prior generations remain selectable

The client shows all accumulated candidates (newest first) and lets the fan select their preferred art via POST /api/merch/ai/select, which updates the session's aiArtKey to the chosen candidate.

Quality tier configuration: Admin-configurable per design config. The array length determines how many generation attempts run; the values control quality per attempt. Examples:

• ["low", "medium", "high"] — 3 attempts at ascending quality
• ["low", "low"] — 2 fast/cheap attempts

Design Resolution — 3-Level Hierarchy

Designs follow a 3-level override hierarchy. At runtime the system merges configs from each level, with child values overriding parent values for non-empty fields.

Level 1: Design (base generation settings — applies to ALL products)
  └─ Level 2: Product Variation (overrides template image, prompt, AI model for a specific catalog product)
       └─ Level 3: Demographic Variation (overrides for a specific gender/age within a product variation)

resolveDesignConfig3Level (merch-design.ts)

Primary resolver — the single entry point for all generation config resolution:

1. Level 1 base: Loads the first config row from the top-level design. The productType column on this row is ignored — it is always treated as the universal default for all products (legacy data may have a specific type like "tshirt" instead of NULL; this is harmless).
2. Level 2 product override: Finds a child design matching the requested catalogProductId (with gender and ageGroup both NULL). If found, merges its configJson on top of Level 1. The catalog product's productType is still passed through for config fallback-chain logic.
3. Level 3 demographic override: If Level 2 was found, looks for a grandchild design matching the selfie's { gender, ageGroup }. If found, merges on top.
4. Legacy fallback: If no Level 2 product variation exists, checks for direct demographic sub-designs of the Level 1 design (backward compatibility).

Returns { effectiveDesignId, configJson } — the merged config and the ID of the most-specific design that matched.

Config merging (mergeConfigJson)

mergeConfigJson(parent, child) produces a merged config where non-empty child values override parent values. "Empty" means undefined, null, or "". This means a Level 2 config only needs to specify the fields it wants to override — everything else inherits from Level 1.

Legacy resolvers (still exported)

Campaign-Agnostic Session & Adoption

In standard campaigns, a session is tightly bound to a campaign at creation. To support multishop Superstore journeys, sessions are campaign-agnostic—the database merch_session.campaign_id column is nullable.

1. Mode-Dependent Lifecycle

The creation and adoption of sessions depends on the entry point:

• Direct Entry (Regular/Experience Campaign): Creates a fresh, campaign-bound session immediately via POST /session/create with campaignSlug set.
• Multishop Entry (Superstore Aggregator): The Superstore lives at /merch/superstore/:slug as a top-level SPA route. Tapping a sub-store card calls startSuperstoreJourney(slug) which creates a campaign-null session via POST /session/create (omitting campaignSlug but storing /merch/superstore/{slug} as startPage) and stores journeySessionId + journeySuperstoreSlug in Zustand. The shopper is then navigated in-SPA to the sub-store with ?utm=superstore-{slug} (no ?s= — the session id is in memory).

2. Session Adoption (POST /api/merch/session/update)

When a shopper enters a sub-store, if the entry detects utm=superstore-* and a journeySessionId in the Zustand store, it calls adoptSession which hits PATCH /api/merch/session/update with campaignSlug. If the requested campaignSlug differs from the session's existing campaignId:

1. The server validates that the campaign is active and matches the environment.
2. The server updates merch_session.campaign_id to point to the new campaign.
3. The server clears per-campaign scratch fields so they can regenerate specifically for this campaign:
   • designId, pendingItem
   • aiArtKey, aiArtRawKey, aiArtPrompt, aiArtCandidates
   • finalImgKey and all illustration/mockup image keys
4. The server preserves all identity fields, meaning the user's selfie, email, userId, shipping info, consent flags, and location are reused seamlessly across different sub-stores.
5. The server ensures a corresponding merch_session_analytics row exists for the new campaign.

3. Per-Campaign Analytics Funnels

Even though a single journey session spans multiple sub-stores/campaigns, analytics must remain granular per campaign.

• merch_session_analytics relaxes the session_id uniqueness and is instead keyed on a composite unique key (session_id, campaign_id).
• Standard sessions produce exactly 1 analytics row. Multishop sessions produce 1 row per campaign they adopt, preserving the integrity of individual campaign funnels.

AI generate route integration

The /api/merch/ai/generate route:

1. Design selection: Priority is explicit designId in request > auto-select by catalog product ID via listDesignsByCatalogProductId > legacy product-type fallback > session fallback. Auto-selection always finds a top-level design (not a sub-design) since session.designId may hold a product/demographic variation from a previous generation for a different product.
2. Loads the active selfie via getActiveSelfie(sessionId) to get demographics (gender, ageGroup)
3. Generation cache: Checks merch_session_generation for a cached result matching (sessionId, effectiveDesignId, productType, selfieKey). On cache hit, updates the session's aiArtKey and aiArtCandidates to match the cached product (so /ai/select sees the correct candidates) and returns immediately.
4. Calls resolveDesignConfig3Level(designId, productType, { gender, ageGroup }, fallbackChain, catalogProductId)
5. Extracts qualityTiers, templateImageUrl, and prompt from the merged config
6. Runs the selected GPT Image 1.5 or GPT Image 2 model, then independently applies the selected background remover.
7. Passes qualityTiers to generateConsistentAIArt to control how many attempts and at what quality

Image Processing Pipeline (img-processing/)

Modules for post-processing AI output:

Transparent backgrounds and template masks

All model requests set background: "opaque" and outputFormat: "png". Model selection (gpt-image-1.5 or gpt-image-2) is independent from bgRemovalMode.

Background removal is opt-in: bgRemovalMode defaults to none, which preserves the opaque model output, and a remover only runs when a design explicitly selects one in the store builder. bria sends the generated PNG to fal.ai's fal-ai/bria/background/remove endpoint and validates its alpha output. The legacy options apply flood-fill and/or edge feathering in code. The benchmark never applies any remover.

bria — and only bria — also appends REMOVABLE_BACKGROUND_PROMPT_SUFFIX, which asks the model for a flat, solid white backdrop for the segmentation model to cut. The legacy removers must not get that suffix: they flood-fill outward from the image corners of whatever background the template already supplies, so replacing it with forced white removes the thing they were tuned to cut.

The legacy flood fill's colour tolerance (BG_REMOVE_DEFAULTS.threshold) matters more than it looks. Model backgrounds are dithered rather than mathematically flat, and the fill is all-or-nothing — too tight a tolerance traps it in the corner pixel and removes nothing at all, with no error and no log line.

maskImageUrl / maskImageAssetId remains an optional, separate template-shaping feature. It cuts the generated art to an admin-supplied alpha shape during generation. Every later render, mockup, and print file inherits both the generated transparency (when a remover ran) and the optional template mask.

The mask follows the normal 3-level config merge: a product variation (Level 2) or demographic variation (Level 3) that sets maskImageUrl overrides the design default, and one that leaves it empty inherits the top-level mask.

FAL.AI Integration

Character Consistency (validate-character-consistency.ts)

Gemini vision likeness scoring with optional SAM segmentation. Returns overall_likeness_score (0-1).

Catalog Product Rendering

POST /api/merch/render

The current runtime render path is catalog-backed and uses catalog_renderer_config for the selected catalog product:

1. Resolves session.aiArtKey as a media filename.
2. Uses the generated PNG's alpha channel directly; no render-time background-removal algorithm runs.
3. Composites the transparent art through renderProductComposite() using the product renderer config: background, art bounds, overlays, and text layers.
4. For digital-img (rendererConfig.disabled === true), skips product compositing and uses the generated art directly.
5. Produces a watermarked preview and a clean output, uploads both to S3, registers both as media records, and writes their filenames to the cart item (imageKey, cleanImageKey) when a cartItemId is supplied.
6. Returns { previewFilename, cleanFilename }.

Legacy mockup and garment/plaque render endpoints still exist, but new shopper flows should use the catalog renderer.

Order Creation

createOrGetMerchOrderFromSession (create-order.ts)

10-step idempotent pipeline:

1. Fetch session + campaign
2. Lifecycle validation: SOFT_CLOSE (grace expired), ENDED, EMERGENCY_CLOSE all blocked
3. Deduplicate cart items by shop product id
4. Validate all shop products exist and are active
5. Price per item: use the attached shop product override price/free flag, then catalog base price as fallback
6. Calculate totals: subtotal, shippingCost, total
7. Idempotency check: find existing order by sessionId with matching email + totals + status
8. Normalize address fields
9. Create order with generated orderNumber, determine mode (tester = PREVIEW, else LIVE)
10. Create order items via batch insert

Email

sendMerchOrderConfirmationEmail (send-email.ts)

• Subject: Your Order Confirmation - {orderNumber} (DEMO/TEST prefix for non-live)
• From: support@zooly.ai
• BCC: merch-orders@zooly.ai (customer orders only)
• HTML: items table, shipping address, order totals, back-to-merch link
• DEMO disclaimer: "This is a demo order. No payment was taken..."
• TEST disclaimer: "This is a test order. If you completed payment, a real charge was taken..."

sendMerchDelayedReadyEmail (send-email.ts)

Sent when AI generation takes >90s and fan provides email.

• Subject: "Your custom merch is ready"
• HTML: "The wait is over." headline + "View My Merch" CTA button

Campaign Lifecycle FSM

State Derivation (activation-lifecycle.ts)

isOpen = status === "LIVE" AND shutdownMode === "NONE"
isSoftClosing = shutdownMode === "SOFT_CLOSE" AND NOT graceExpired
isSoftCloseGraceExpired = shutdownMode === "SOFT_CLOSE" AND shutdownEndsAt < now()
isEmergencyClosed = shutdownMode === "EMERGENCY_CLOSE"
isEnded = status === "ENDED"
isCheckoutBlocked = isEnded OR isEmergencyClosed OR isSoftCloseGraceExpired

Valid Transitions

SOFT_CLOSE_GRACE_MINUTES = 10

Image Verification

A selfie is checked before it can be used on merchandise. The check asks whether a person is visible, whether the photo is too blurry or poorly lit, whether it shows prohibited nudity, and whether the person is a widely famous celebrity. It also estimates gender, age group, and how many people are in the photo.

The photo is blocked when no person is visible, when it is too blurry or poorly lit, when it shows prohibited nudity (including a shirtless child), or when the person is a widely famous celebrity. Ordinary shirtlessness, tank tops, and swimwear on teens and adults are allowed.

Gender, age group, and how many people are in the photo are saved with the selfie for later art. They never block the photo. Gender and age are left blank when no person is visible. A failure to save them does not fail the check.

Watermarking

applyWatermark (img-processing/watermark.ts)

Sharp + opentype.js overlay that stamps a semi-transparent diagonal "SAMPLE ONLY" label across the image. Fonts load from S3 and are cached in-process. Any failure returns the original buffer so uploads never break.

Where watermarks are applied (both LIVE and PREVIEW modes):

The rule: everything pre-purchase is watermarked; the confirm page (post-payment) shows the clean render. Runtime render outputs are media filenames resolved through the media proxy, not raw S3 URLs.

Analytics

Session Analytics (analytics.ts)

Step order map:

studio/review/upload-verify/camera = 1
merch = 2, size = 3, loading = 4, result = 5
shipping/payment = 6, confirm = 7

Updates maxStepReached when current step exceeds previous max. Appends to stepTimeline JSON array. Tracks milestones: generationStartedAt, generationCompletedAt, checkoutStartedAt, completedAt, abandonedAt.

Utility Functions (utils.ts)

Constants (constants.ts)