> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pcnaid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Apex Brand & Event Mgmt architecture

> Runtime and product data flow described by the Apex Brand & Event Mgmt README.

# Apex Brand & Event Mgmt architecture

## Runtime

Apex Brand & Event Mgmt is a Shopify embedded app built on React Router (framework mode) with Shopify Polaris web components and App Bridge. It runs as two processes connected through Redis (BullMQ) and a shared database:

* **Web server** — serves the embedded UI, handles OAuth, API routes, and enqueues jobs.
* **Background worker** — runs the BullMQ campaign and failure-notification consumers.

A PostgreSQL database accessed through Prisma stores application data. Campaign scheduling uses BullMQ with Redis; delayed jobs publish campaign start and end work.

## Product data flow

A merchant configures a campaign with a start and end time, selected products, an optional discount, and optional storefront, email, price-edit, and theme steps. At campaign start, queued work publishes the selected products, activates the discount, applies variant price edits and product tags, and can switch to a promo theme. At the end, the app unpublishes only the products it published, deactivates the discount, restores the original prices and theme, and untags the products. Every action is recorded in an audit trail.

Execution is fail-closed: product publication, tagging, variant pricing, discount creation, and theme application must each complete before the campaign is considered running. Failed steps keep the campaign retryable, and persisted progress makes retries idempotent.

## Storefront surfaces

The Advanced smart-intent popup runs separately from the admin frame. Its theme app extension injects a deferred request to the shop-owned signed app-proxy URL, which the app serves from an authenticated proxy route. The route derives the shop from the Shopify request signature, checks the Advanced entitlement, and reads the active popup configuration. Settings is the single theme-extension onboarding surface, linking to the theme editor and reporting the published-theme embed status.

## Backend services

* **CampaignService** — campaign CRUD, scheduling, cancellation, and release-bundle orchestration.
* **CampaignExecutionService** — Shopify Admin GraphQL operations for publishing, discounts, pricing, tags, and themes.
* **Shop cleanup service** — async cleanup for app uninstall and GDPR redaction webhooks.
* **Reconciler** — after a successful OAuth callback, repairs the authenticated shop's missing campaign jobs.

## Billing and entitlements

Billing uses Shopify's app-managed Billing API with Free, Pro, and Advanced plans. The app refreshes the shop's complete Shopify subscription ledger before campaign create, edit, and schedule actions and before campaign start. Only an active paid Shopify subscription grants paid entitlements; all other states fail closed to Free. A shop receives one 14-day free trial on its first paid subscription.

See the [merchant setup guide](https://docs.pcnaid.com/nodes/shopify/apex-brand-event-mgmt/merchant/guides/index.md) for the store-facing workflow and the [API overview](https://docs.pcnaid.com/nodes/shopify/apex-brand-event-mgmt/developer/api/index.md) for documented interfaces.

## Quickstart

For how an integrator or contributor gets oriented, see the [quickstart](https://docs.pcnaid.com/nodes/shopify/apex-brand-event-mgmt/developer/quickstart.md).

[Pcnaid Documentation](https://docs.pcnaid.com/namespace/index.md) › [Shopify Ecosystem](https://docs.pcnaid.com/hubs/shopify-ecosystem/index.md) › [Apex Brand & Event Mgmt](https://docs.pcnaid.com/nodes/shopify/apex-brand-event-mgmt/index.md) › [Developer](https://docs.pcnaid.com/nodes/shopify/apex-brand-event-mgmt/developer/index)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.