Storefront Templates Module

The /[locale]/loja route showcases paid/free templates pulled from Supabase and rendered with liquid-glass cards. This page documents the data model, components, analytics hooks, and how to extend the module.

Runtime Flow

1. src/app/[locale]/(pages)/store/page.tsx
   • Calls setRequestLocale(locale).
   • Loads translations under Store.*.
   • Fetches products via getAllProducts() (Server Query that uses ProductRepository).
   • Emits trackServerEvent("page_view", { page: "store" }) for Mixpanel.
   • Renders TemplatesGrid (filters + cards) and a CTA.
2. TemplatesGrid (client component)
   • Filters stored in local state (search, category, stack, level, priceType).
   • For each change, emits store_filter_applied through useClickTracking (GA4 + Mixpanel).
   • Renders TemplateCard and optionally highlights one via ?template=<id> query string.
3. CTAs use StoreContactCTA linking to /[locale]/contato and track conversions.

Data Model

src/app/types/template.ts defines the Template type (single source of truth for the store). Key fields:

Field	Description
id, slug	Stable identifiers used for filtering and highlight anchors.
price, priceType, stripePriceId	Pricing metadata (one-time, subscription, free).
category, stack, level	Drive filters in TemplateFilters. Keep values in sync with translation files (Store.filters.*).
features	Rendered as bullet list inside TemplateCard.
demoUrl, image	CTA + screenshot link.

Data can come from:

• Supabase products table (via ProductRepository).
• Static fallback in src/app/data/recommendations.ts (used for marketing sections like /recommendations).

Repository & Admin Layer

• ProductRepository (see src/app/lib/repositories/product-repository.ts) encapsulates Supabase queries (findAll, findPaginated, create, update, etc.) and enforces unique slugs.
• Admin CRUD flows live under src/app/actions/products/* and src/app/[locale]/admin/products/* pages.
• Any mutation must call revalidateProducts/revalidateProduct via src/app/lib/cache.ts so the ISR store page refreshes within 1 hour (revalidate = 3600).

Translations

Store.* strings in src/i18n/messages/{locale}.json cover hero copy, filters, empty state, CTA. When adding new filters/categories:

1. Update enums in TemplateFilters.
2. Extend translation keys (e.g., "filters.categories.{key}").
3. Add analytics instrumentation if new filter interactions matter.

Analytics & Instrumentation

• Mixpanel trackServerEvent("page_view", { page: "store" }) inside the page component.
• GA4 events defined in content/analytics/events.mdx:
  • store_template_view
  • store_template_demo_click
  • store_filter_applied
  • store_initiate_checkout
• The StoreContactCTA emits contact_form_start once the user lands on /contato.

Testing

• Unit tests under src/app/test/unit/components/store/ cover TemplateCard, TemplateFilters, etc.
• Integration tests for actions and repositories under src/app/test/integration/actions/products-actions.test.ts ensure ActionResult codes (DUPLICATE_SLUG, NOT_FOUND, etc.).
• Playwright specs (e.g., src/app/test/e2e/tests/store.spec.ts) navigate the store filters and verify CTAs.

Extending the Module

1. New Template Category – Update Template['category'], TemplateFilters options, translations, and consider adding a new filter icon/tag.
2. Price Localization – Use Intl.NumberFormat in TemplateCard to display localized pricing (look at Store.priceNote). For multi-currency checkout, see /pricing doc.
3. Promo Highlights – To spotlight a template, append ?template=<id> to the URL. TemplatesGrid scrolls it into view automatically.
4. Server Measurements – If needed, add more trackServerEvent calls (e.g., store-contact-cta) in page.tsx.

Related Docs

• Pricing Strategy
• Products Admin Guide
• Analytics Events
• Stripe Integration

Keep this page updated whenever the store gains new filters, data fields, or payment flows so marketing, product, and engineering teams stay aligned.