Technical Documentation

The platform is a full-stack web application built on React 19, tRPC, and Express. When a student submits a collection, the following pipeline executes:

1. Images are encoded as base64 in the browser and sent to the server via tRPC.
2. The server decodes them and stores the raw buffers in S3 (Manus built-in storage) as a reliable staging area.
3. The server calls Shopify's stagedUploadsCreate mutation to obtain secure, temporary upload URLs.
4. Each image buffer is posted directly to its staged target URL using multipart form data.
5. The server calls fileCreate with the resourceUrl values returned by the staged targets.
6. The server polls nodes(ids:) until all files reach READY status, collecting their MediaImage GIDs.
7. Finally, metaobjectCreate is called with the designer name, description, and a JSON array of image GIDs for the images field.

This two-stage approach (S3 → Shopify) ensures that large or multiple images are reliably transferred even under slow network conditions, and that the browser never communicates directly with the Shopify Admin API (keeping the access token server-side only).

The integration requires a Shopify Custom App with Admin API access. Follow these steps to create one:

1. In your Shopify Admin, navigate to Settings → Apps and sales channels.
2. Click Develop apps, then Create an app.
3. Give the app a name (e.g., SAFD Collection Form) and click Create app.
4. Go to Configuration → Admin API integration and click Configure.
5. Enable the following access scopes:

After saving, go to API credentials and click Install app. Copy the Admin API access token — it is only shown once. Store it as the SHOPIFY_ACCESS_TOKEN environment variable.

To find your metaobject type handle, go to Content → Metaobjects in Shopify Admin, click on your Collections definition, and look at the URL — the last segment is the type handle (e.g., collections or safd_collections). Set this as SHOPIFY_METAOBJECT_TYPE.

SHOPIFY_STORE_DOMAIN=your-store.myshopify.com
SHOPIFY_ACCESS_TOKEN=shpat_xxxxxxxxxxxxxxxxxxxx
SHOPIFY_METAOBJECT_TYPE=collections

The form fields map directly to the Shopify metaobject field keys. The table below shows the exact mapping used in the metaobjectCreate mutation:

The images field expects a JSON-serialised array of Shopify Global IDs (GIDs) in the format gid://shopify/MediaImage/<id>. These GIDs are obtained after uploading images through the staged upload pipeline and calling fileCreate.

If your metaobject uses different field keys (e.g., designer_name instead of designer), update the keys in server/shopify.ts → createCollectionMetaobject().

mutation metaobjectCreate($metaobject: MetaobjectCreateInput!) {
  metaobjectCreate(metaobject: $metaobject) {
    metaobject { id handle }
    userErrors { field message code }
  }
}

# Variables:
{
  "metaobject": {
    "type": "collections",
    "fields": [
      { "key": "designer",    "value": "Jane Doe" },
      { "key": "description", "value": "A collection inspired by…" },
      { "key": "images",      "value": "["gid://shopify/MediaImage/123"]" }
    ]
  }
}

The complete server-side flow is implemented across two tRPC procedures in server/routers/collection.ts and the Shopify helper in server/shopify.ts:

// Staged upload input (one entry per image)
{
  filename: "collection-01.jpg",
  mimeType: "image/jpeg",
  resource: "FILE",
  httpMethod: "POST",
  fileSize: "2048000"   // bytes as string
}

// fileCreate input
{
  originalSource: "https://shopify-staged-uploads.s3.amazonaws.com/…",
  contentType: "IMAGE"
}

// metaobjectCreate field values
{ key: "images", value: "["gid://shopify/MediaImage/987654321"]" }

The platform is deployed via the Manus publishing workflow. No external hosting configuration is required.

1. Ensure all three Shopify environment variables are set in the Manus project Secrets panel (SHOPIFY_STORE_DOMAIN, SHOPIFY_ACCESS_TOKEN, SHOPIFY_METAOBJECT_TYPE).
2. Create a checkpoint via the Manus interface (required before publishing).
3. Click the Publish button in the Manus Management UI header. The platform will be live at your assigned *.manus.space domain.
4. Optionally, bind a custom domain under Settings → Domains.

To embed the form in your Shopify store, you can link to the published URL from a custom page, a navigation menu item, or a Shopify theme button. The form operates as a standalone web application and does not require Shopify theme integration.