# TRA — Project Development Plan

**Project name:** TRA (The Ring Authority)  
**Source of truth for:** greenfield Shopify replacement, public storefront parity, admin platform, CRM, social, accounting, SEO, media, analytics, and automation  
**Reference storefront:** [https://theringauthority.com/](https://theringauthority.com/)  
**Document version:** 1.0  
**Status:** Implementation blueprint (research complete; build not started)  
**Last updated:** 2026-09-22  

---

## Table of contents

1. [Executive summary](#1-executive-summary)
2. [Goals, assumptions, non-goals, success metrics](#2-goals-assumptions-non-goals-success-metrics)
3. [Tech stack and environments](#3-tech-stack-and-environments)
4. [Current storefront crawl and audit](#4-current-storefront-crawl-and-audit)
5. [Public frontend requirements and visual parity](#5-public-frontend-requirements-and-visual-parity)
6. [Target system architecture](#6-target-system-architecture)
7. [Admin UX system](#7-admin-ux-system)
8. [Shopify-parity commerce modules](#8-shopify-parity-commerce-modules)
9. [Mandatory internal apps](#9-mandatory-internal-apps)
10. [Inbound CRM and pipelines](#10-inbound-crm-and-pipelines)
11. [Social media management](#11-social-media-management)
12. [Accounts, suppliers, and double-entry ledger](#12-accounts-suppliers-and-double-entry-ledger)
13. [RBAC, security, privacy, and audit](#13-rbac-security-privacy-and-audit)
14. [Media gallery (WordPress-parity + DAM)](#14-media-gallery-wordpress-parity--dam)
15. [SEO platform (beyond Rank Math / Yoast)](#15-seo-platform-beyond-rank-math--yoast)
16. [Product and business analytics](#16-product-and-business-analytics)
17. [Automation engine](#17-automation-engine)
18. [Domain model, data, APIs, events](#18-domain-model-data-apis-events)
19. [Integrations and official external APIs](#19-integrations-and-official-external-apis)
20. [Performance, accessibility, and PageSpeed](#20-performance-accessibility-and-pagespeed)
21. [Testing, CI/CD, DevOps, monitoring](#21-testing-cicd-devops-monitoring)
22. [Phased delivery roadmap](#22-phased-delivery-roadmap)
23. [Risks, dependencies, launch checklist](#23-risks-dependencies-launch-checklist)
24. [Requirements traceability checklist](#24-requirements-traceability-checklist)
25. [Appendix: references](#25-appendix-references)

---

## 1. Executive summary

TRA is a **brand-new, from-scratch commerce operating platform** that will replace the current Shopify storefront and admin for The Ring Authority. The public site’s **visual design, IA, and page content patterns remain the same**; the backend and admin are rebuilt as a first-party platform so the business owns:

- Full ecommerce (catalog, cart, checkout, orders, inventory, promotions, content)
- Inbound CRM with pipelines, inbox, quotes, and HTML email templates
- Social media management for multiple networks from one admin
- Supplier accounts, ledgers, and double-entry accounting
- Comprehensive RBAC, media library, advanced SEO, and product analytics
- End-to-end process automation without SaaS CRM/social/accounting products

**Migration policy:** build greenfield; **manual data shift later** (products, customers, content, URLs/redirects). No automated Shopify import in Phase 1.

**“No third party” boundary:** TRA owns all **business modules and workflows**. Official external APIs remain required where platforms mandate them: card payments, carriers (optional), transactional email delivery, and social networks. No scraping or unofficial consumer-UI automation. No raw card vaulting.

**Secrets:** database and API credentials are stored only in environment files / secret managers. This document never embeds production passwords in plaintext for deployment.

---

## 2. Goals, assumptions, non-goals, success metrics

### 2.1 Goals

1. Pixel-faithful public storefront parity with [theringauthority.com](https://theringauthority.com/), mobile-first, with improved SEO and PageSpeed.
2. Shopify-admin-or-better operational parity for a B2C + quote-led custom manufacturing business (ring canvas, skirts, corner pads, accessories).
3. Native CRM for inbound RFQs, wholesale applications, contact forms, chat-like inbox, pipelines, and marketing/email templates.
4. Unified social publishing, moderation, and analytics across supported official APIs.
5. Supplier-centric accounting with inventory valuation, landed costs, AP/AR, bank reconciliation, and close controls.
6. SEO that exceeds Rank Math Pro / Yoast Premium in automation, schema graph, audits, and ecommerce guardrails.
7. Media gallery matching WordPress Media Library UX with DAM extensions.
8. Product analytics deeper than typical third-party plugins (funnels, cohorts, profitability, experiments).
9. Comprehensive RBAC, audit, automation, and observability on the specified stack.

### 2.2 Assumptions

- Single brand / single tenant initially (multi-brand hooks allowed in schema).
- Primary market: Australia (AUD), with multi-currency country selector retained for UX parity.
- Catalog is variant-heavy (size × colour / type) with custom branding and quote-led sales.
- Physical goods with shipping; custom production SLAs matter.
- Manual migration after platform readiness.
- PHP 8.5 and Laravel 13 as specified; Nuxt 4 for public; separate Vue 3 TS admin SPA.
- MySQL database `ronnie_tra` with user `ronnie_tra` (password via `DB_PASSWORD` env only).

### 2.3 Non-goals (initial)

- Building a card processor / PCI Level 1 vault.
- Scraping Facebook/Instagram/TikTok/X/Reddit consumer UIs.
- Automated Shopify order/customer sync as a permanent integration.
- Multi-tenant SaaS resale of TRA itself.
- Full ERP manufacturing MRP / shop-floor MES (can integrate later).

### 2.4 Success metrics

| Area | Target |
|------|--------|
| Public visual parity | Design match on home, PDP, collection, blog, content, policies |
| Lighthouse (lab, 5-run median) | Desktop ≥ 99; Mobile ≥ 95 |
| Field CWV (p75) | LCP ≤ 2.5s; INP ≤ 200ms; CLS ≤ 0.1 |
| Checkout correctness | Idempotent payments; inventory reservation; tax/shipping snapshots |
| Admin completeness | All P0 modules live with RBAC + audit |
| SEO | Schema graph valid; sitemaps accurate; no indexable empty traps |
| CRM | RFQ → pipeline → quote → order path end-to-end |
| Accounting | Balanced journals; 3-way match; period close |

### 2.5 Priority tiers

- **P0** — required for launch
- **P0-C** — required if business model needs it (e.g. markets, wholesale)
- **P1** — soon after launch
- **P2** — advanced / later

---

## 3. Tech stack and environments

### 3.1 Locked stack

| Component | Choice |
|-----------|--------|
| Public frontend | Nuxt 4 |
| Admin frontend | Vue 3 + TypeScript |
| UI | Tailwind CSS |
| Icons | Lucide |
| Fonts (public + admin) | Segoe UI (Windows/default); Selawik (Apple devices) |
| State | Pinia |
| Routing | Nuxt / Vue Router |
| Backend | Laravel 13 |
| PHP | PHP 8.5 |
| API | REST / JSON |
| Database | MySQL (`ronnie_tra`) |
| Cache | Redis |
| Queues | Laravel Horizon |
| Search | Meilisearch |
| Realtime | Laravel Reverb |
| CDN/WAF | Cloudflare |
| Web server | Nginx |
| Build | Vite / Nuxt |
| Monitoring | Laravel Pulse + server monitoring |

### 3.2 Environment variables (representative)

```bash
APP_NAME=TRA
APP_ENV=production
APP_URL=https://tra.example.com
ADMIN_URL=https://admin.tra.example.com
DB_CONNECTION=mysql
DB_DATABASE=ronnie_tra
DB_USERNAME=ronnie_tra
DB_PASSWORD=**********   # secret manager / .env only — never commit
REDIS_HOST=127.0.0.1
MEILISEARCH_HOST=http://127.0.0.1:7700
MEILISEARCH_KEY=**********
REVERB_APP_ID=...
REVERB_APP_KEY=...
REVERB_APP_SECRET=**********
CLOUDFLARE_ZONE_ID=...
PAYMENT_PROVIDER=...
MAIL_MAILER=...
```

### 3.3 Environments

| Env | Purpose |
|-----|---------|
| local | Developer machines |
| staging | Full stack, test payments, social sandbox where available |
| production | Live storefront + admin |

### 3.4 Repository layout (target)

```
/apps
  /storefront     # Nuxt 4
  /admin          # Vue 3 + TS + Vite
/api              # Laravel 13
/docs             # plan, OpenAPI, runbooks
/infra            # Nginx, Horizon, Reverb, deploy scripts
```

---

## 4. Current storefront crawl and audit

Crawl date: **2026-09-22**. Source: [robots.txt](https://theringauthority.com/robots.txt), sitemap children, all 41 sitemap HTML URLs + policies + utilities.

### 4.1 Discovery surfaces

- Robots: allows products/collections/pages/blogs/policies; blocks admin, checkout, cart AJAX, filter/sort traps.
- Agent surfaces: `/agents.md`, `/.well-known/ucp`, Shopify UCP/MCP.
- Underlying Shopify domain observed: `gnh35j-e2.myshopify.com`.
- Localization: country/currency (not translated URL trees / hreflang).

### 4.2 Complete canonical HTML inventory (45)

#### Home (1)
- `/`

#### Products (5)
- `/products/boxing-ring-canvas-training-grade`
- `/products/boxing-ring-canvas-pro-grade`
- `/products/boxing-ring-canvas-champion-grade`
- `/products/boxing-ring-side-skirt-polyester`
- `/products/standard-corner-pad-cover-pu-leather`

#### Collections (10)
- `/collections/ring-canvas`
- `/collections/ring-side-skirts`
- `/collections/corner-pads`
- `/collections/best-sellers`
- `/collections/all`
- `/collections/rope-covers` (empty)
- `/collections/other-accessories` (empty)
- `/collections/new-arrivals` (empty)
- `/collections/sporting-goods-boxing-martial-arts-boxing-rings-accessories` (empty)
- `/collections/turnbuckle-covers` (empty)

#### Content pages (16)
- `/pages/contact`
- `/pages/about-us`
- `/pages/faq`
- `/pages/gallery`
- `/pages/wishlist`
- `/pages/data-sharing-opt-out`
- `/pages/request-for-quotation`
- `/pages/landing-page`
- `/pages/boxing-ring-canvas-supplier-comparison`
- `/pages/custom-ring-canvas`
- `/pages/apply-for-wholesale-account`
- `/pages/thank-you` (noindex)
- `/pages/return-and-refund-policy`
- `/pages/terms-and-conditions`
- `/pages/shipping-policy`
- `/pages/privacy-policy`

#### Blog (9)
- `/blogs/news`
- Articles:
  - ultimate-guide-boxing-ring-canvas
  - why-brand-your-boxing-ring
  - training-pro-champion-boxing-ring-canvas-guide-2026
  - boxing-ring-safety-checklist
  - how-to-measure-a-boxing-ring-for-canvas-side-skirts-and-corner-pads
  - boxing-ring-canvas-cleaning-maintenance-complete-gym-guide
  - when-to-replace-boxing-ring-canvas-wear-grip-and-safety-warning-signs
  - boxing-ring-accessories-explained-canvas-side-skirts-corner-pads-rope-covers-and-turnbuckle-covers

#### Shopify policies (4)
- `/policies/privacy-policy`
- `/policies/terms-of-service`
- `/policies/refund-policy`
- `/policies/shipping-policy`

### 4.3 Global chrome (every theme page)

- Cart drawer (empty/full, qty, estimated total)
- Country/region selector → `/localization` POST
- Predictive search → `/search?q=…&options[prefix]=last`
- Header nav: Ring Canvas, Side Skirts, Corner Pad Covers, Request for Quotation, About (About Us, Guides, Why Us?, Gallery, FAQs, Contact)
- Footer: Quick Links, Policies, Contact (`+61 406 070 516`, `sales@theringauthority.com`, `19 Saffron Street, Greenvale VIC 3059, Australia`)
- Free shipping banner messaging (content inconsistent — see §4.8)
- Wishlist + account entry
- Privacy banner

### 4.4 Design system observed (parity baseline)

| Token | Current Shopify | TRA target note |
|-------|-----------------|-----------------|
| Body font | Questrial 400 | Replace with **Segoe UI / Selawik** per requirement while preserving scale/weight hierarchy |
| Headings | Roboto 600 | Same — map weights into Segoe/Selawik stack |
| Accent | Gold `#DAAF37` / yellows ~`#F7B229` | Preserve |
| Layout | Dark heroes, uppercase headings, square CTAs (0 radius), pill inputs (~26px), max width ~110rem | Preserve composition |
| Theme ancestry | Dawn-like (cards, cart drawer, predictive search) | Re-implement in Nuxt, not Dawn |

### 4.5 Template anatomy

#### Home
Hero → benefits ticker → best sellers → featured categories → premium custom canvas section → full customisation CTA → gallery → testimonials → FAQ → guide promo → quote form CTA.

#### Product (canvas-rich)
Media gallery, price, variants (size/colour), ATC, specs, grade comparison, FAQs, shipping/returns/warranty, testimonials, custom branding CTA, quote form, recommendations, Product + Breadcrumb JSON-LD.

#### Product pricing snapshot (AUD, public JSON at crawl)

| Product | Options | Price range |
|---------|---------|-------------|
| Training Grade | 12–24 ft × Black/Grey/Red/Blue | $329.99–$529.99 |
| Pro Grade | same | $499.99–$699.99 |
| Champion Grade | same | $599.99–$799.99 |
| Side Skirt Polyester | 12–24 ft | $149.99–$209.99 |
| Corner Pad Cover PU | Plain/Custom × Black/Red/Blue/White | $119.99 / $149.99 |

#### Collections
Count, filters (availability/price), sort, SEO “About This Range” / “Why The Ring Authority”, empty states for empty collections.

#### Forms
1. **Inline quote** (home/product): name, email, phone, ring size, requirements  
2. **Contact**: name, email, phone, message  
3. **RFQ page**: products, identity, business type, canvas type, timeline, branding brief, ring size, postcode, branding requirement, artwork link, notes  
4. **Wholesale apply**: currently HulkApps (poor crawlable HTML) — rebuild as first-party form  
5. Search form; localization form; newsletter if present

#### Blog articles
Long-form guides with internal links to products/quote, FAQs, Article schema.

### 4.6 Current third-party apps to replace internally

| Shopify app / vendor | TRA replacement module |
|----------------------|------------------------|
| GemPages | Page builder / CMS sections |
| HulkApps Form Builder | Forms + CRM |
| XO Gallery / EnormApps slider | Media + Gallery page |
| Wishlist app | Wishlist (P0-C / P1) |
| Shopify Chat | CRM inbox / chat widget |
| HubSpot tracking | First-party analytics + CRM |
| Microsoft Clarity | Optional; prefer first-party session analytics |
| Shop Pay | Payment provider wallets via PCI PSP |
| Shopify privacy banner | Consent management |

### 4.7 SEO issues found (must fix in rebuild)

- Duplicate Organization/WebSite JSON-LD
- Multiple H1s (home empty H1; some articles many H1s)
- Canvas PDPs use H2 for product name instead of H1
- Contact/RFQ missing server-rendered H1
- Wholesale page missing H1 + meta description
- Truncated blog titles / OG titles
- Blog index OG: “The Ring Authority \| The Ring Authority”
- Empty collections indexable in sitemap
- Policies duplicated under `/pages/` and `/policies/`

### 4.8 Content inconsistencies to resolve editorially

- Landing “from $299” vs Training from $329.99
- Warranty 12 months (landing) vs 6 months (product)
- Shipping free thresholds: $59.99 / $100 / $500 / quote-only — pick one policy
- Turnaround: under 1 week production vs 2–3 weeks delivery vs 4–8 weeks custom claims
- Material claims (cotton/poly vs polyester vs “heavy duty”)
- Training warranty email `info@daanmma.com.au` vs `sales@theringauthority.com`
- Measuring instructions conflict across FAQ / product / blog
- Social proof numbers differ (100+ vs 200+ gyms; 4.8 vs 4.9)
- Empty accessory collections still marketed

### 4.9 Redirects / 404s observed

- `/pages/about` → `/pages/about-us`
- Old blog `custom-branded-ring-canvas-events-sponsors` → why-brand article
- `/quote`, `/contact`, `/pages/checkout` → 404
- Account login → hosted `account.theringauthority.com`

**TRA action:** implement first-party customer accounts; preserve important redirects; canonicalize policies to one URL strategy.

---

## 5. Public frontend requirements and visual parity

### 5.1 Hard rules

1. **Design of public pages remains the same** — section order, imagery style, gold/black contrast, CTA patterns, product storytelling.
2. Font stack: `Segoe UI, Selawik, system-ui, sans-serif` with Apple detection preferring Selawik.
3. Icons: Lucide only for UI chrome (replace any emoji icons).
4. Mobile-first layouts; touch targets ≥ 44px.
5. Comprehensive on-page SEO and complete metadata on every indexable route.
6. PageSpeed: lab median **99 desktop / 95+ mobile**.

### 5.2 Route map (Nuxt)

| Route | Template | Index |
|-------|----------|-------|
| `/` | Home | yes |
| `/products/:handle` | PDP | yes |
| `/collections/:handle` | Collection | yes if non-empty or intentional |
| `/pages/:handle` | CMS page | configurable |
| `/blogs/news` | Blog index | yes |
| `/blogs/news/:handle` | Article | yes |
| `/policies/:handle` | Policy | yes (canonical; deprecate duplicate pages) |
| `/search` | Search | noindex or thin-guard |
| `/cart` | Cart | noindex |
| `/checkout` | Checkout | noindex |
| `/account/**` | Customer account | noindex |
| `/thank-you` | Confirmation | noindex |

### 5.3 Shared components

Header, MegaNav, CountrySwitcher, PredictiveSearch, CartDrawer, ProductCard, Price, VariantPicker, GalleryLightbox, AccordionFAQ, TestimonialCarousel, QuoteForm, ContactForm, Footer, ConsentBanner, Breadcrumbs, SchemaJsonLd.

### 5.4 Storefront behaviors to preserve / improve

- Cart drawer updates without full page reload
- Variant price/availability live update
- Collection filters + sort (server-friendly URLs; robots rules for traps)
- Country/currency display with clear currency labels (fix unlabeled conversions)
- Wishlist (first-party)
- Quote CTAs on home/PDP/landing
- Gallery page driven by media library tags/albums

### 5.5 Accessibility

WCAG 2.2 AA: labels, focus rings, skip links, accordion semantics, form errors, alt text, colour contrast on gold/black.

---

## 6. Target system architecture

### 6.1 High-level

```mermaid
flowchart LR
  User[Visitor_Customer] --> CF[Cloudflare_CDN_WAF]
  CF --> Nginx[Nginx]
  Nginx --> Nuxt[Nuxt4_Storefront]
  AdminUser[Staff] --> CF2[Cloudflare]
  CF2 --> Nginx2[Nginx]
  Nginx2 --> Admin[Vue3_Admin_SPA]
  Nuxt --> API[Laravel13_API]
  Admin --> API
  API --> MySQL[(MySQL_ronnie_tra)]
  API --> Redis[(Redis)]
  API --> Meili[(Meilisearch)]
  API --> Horizon[Horizon_Workers]
  API --> Reverb[Laravel_Reverb]
  API --> S3[Object_Storage]
  Horizon --> Mail[Email_Provider]
  Horizon --> Social[Social_Official_APIs]
  Horizon --> Pay[Payment_PSP]
```

### 6.2 Backend domains (modular monolith)

Catalog, Inventory, Pricing, CartCheckout, Orders, Payments, Fulfillment, Returns, Customers, Markets, Promotions, ContentCMS, Media, SEO, Search, CRM, Social, Accounting, Automation, Notifications, Analytics, IdentityRBAC, Integrations, Settings, Audit.

### 6.3 Cross-cutting patterns

- REST JSON API versioned (`/api/v1/...`)
- Sanctum / OAuth2 for admin; customer session cookies for storefront
- Idempotency keys on payments, order create, refunds, journals
- Domain events + **outbox** table → Horizon consumers
- Read models / cache tags in Redis; Meilisearch for catalog/admin search
- Reverb for admin presence, inbox, job progress, stock alerts
- Append-only ledgers for inventory, gift cards, store credit, accounting journals
- Soft deletes where referential history matters; hard delete only via privacy workflows

### 6.4 Rendering strategy (Nuxt)

- Prerender/ISR: home, static pages, policies
- SSR + SWR: collections, products, blog
- SPA/client: cart drawer interactions, checkout steps after shell
- Route rules for CDN cache + tag invalidation

---


## 7. Admin UX system

### 7.1 Design goals

Premium, modern, dense-but-clear operations UI: keyboard-first, low friction, high information density without clutter. Inspired by best-of Shopify Admin + Linear + Notion command patterns — not a generic bootstrap dashboard.

### 7.2 Visual system

- Tailwind design tokens: neutral surfaces, gold accent sparingly for brand moments, semantic status colours (success/warn/danger/info)
- Fonts: Segoe UI / Selawik
- Icons: Lucide
- Density modes: comfortable / compact
- Dark/light optional later; default light premium for ops clarity
- Motion: subtle transitions only (presence, drawers, toasts)

### 7.3 Information architecture (primary nav)

1. Home  
2. Orders (Orders, Drafts, Abandoned checkouts, Returns)  
3. Products (All, Categories, Inventory, Transfers, Purchase orders)  
4. Customers (Customers, Segments, Companies/B2B)  
5. CRM (Inbox, Leads, Pipelines, Quotes, Forms, Templates)  
6. Social (Calendar, Composer, Inbox, Accounts, Analytics)  
7. Discounts & Gift cards  
8. Content (Pages, Blog, Menus, Policies, Metaobjects)  
9. Media  
10. SEO  
11. Analytics & Reports  
12. Marketing Automations  
13. Accounting (Suppliers, Bills, Payments, Journals, Bank, Reports)  
14. Apps / Integrations  
15. Settings (Store, Staff/RBAC, Markets, Payments, Shipping, Taxes, Notifications, Privacy)

### 7.4 Global admin capabilities (every list module)

- Command palette (Ctrl/Cmd+K)
- Global search (orders, SKUs, customers, media, settings)
- Filters, sorting, pagination, saved views, column picker
- Status tabs + counts
- Bulk select / select-all-matching / bulk actions + progress report
- CSV import/export center (async, validation preview, error file)
- Tags, notes, metafields, attachments, internal comments
- Immutable timeline (human, API, automation)
- Optimistic locking / conflict toast
- Keyboard shortcuts and sticky action bars
- Empty states with next-best action
- Role-gated buttons (hide vs disable with tooltip policy)

### 7.5 Home dashboard widgets

Gross/net sales, orders, AOV, conversion, sessions; queues: unfulfilled, capture required, high risk, returns, low stock, failed jobs, open RFQs, SLA breaches; alerts feed; shortcuts create order/product/customer/discount/quote.

---

## 8. Shopify-parity commerce modules

Research baseline: Shopify Admin manuals (orders, products, inventory, customers, discounts, markets, analytics, payments, checkout, shipping, taxes, notifications, users, activity logs) and Shopify Apps by Shopify.

### 8.1 Home — P0

Features listed in §7.5 plus period comparison, channel/market/location filters, setup checklist, import/export notices, anomaly alerts (P1).

### 8.2 Orders — P0

**List/detail search:** number, customer, email, phone, SKU, product, tracking, transaction ID.

**State machines:**
- Order: open, archived, canceled  
- Payment: pending, authorized, partially_paid, paid, partially_refunded, refunded, voided, failed  
- Fulfillment: unfulfilled, scheduled, on_hold, in_progress, partially_fulfilled, fulfilled, not_required  
- Return: requested, open, inspected, completed, canceled  

**Features (granular):**
- Financial ledger: auth, capture, sale, refund, void, fees, disputes/chargebacks  
- Edit contact/address; notes/tags; shipping charge; eligible line edits with audit  
- Split/partial fulfillment by location; tracking; carrier; packing slips; invoices; labels; customs  
- Cancel with reason; full/partial refund; refund shipping; restocking fee; restock dispositions  
- Returns/exchanges; return labels; inspection; store-credit refund  
- Fraud risk score (low/med/high) + review queue  
- Timeline of emails/payments/fulfillments/edits/automation/API  
- Bulk capture/fulfill/print/archive/cancel/tag  
- CSV export with transaction details  
- Automations: auto-capture low risk; hold high risk; route warehouse; tag; notify; archive  

### 8.3 Draft orders — P0

Create from catalog or custom lines; customer; market/currency; tax treatment; addresses; custom prices; price lock; discounts; shipping; inventory reservation + expiry; tags/notes/metafields; duplicate; send invoice / payment link; payment terms (due on receipt/fulfillment/fixed/net 7–90); deposits; record manual/card payment; convert atomically to order; statuses open/invoice_sent/completed/expired; bulk tag/delete/export.

### 8.4 Abandoned checkouts — P0

Persist contact, lines, discounts, shipping, currency, market, UTM, step reached; recovery status; email/SMS; recovery URL; recovered order link; manual recover / copy to draft; archive/export; automated recovery with delay, consent, suppression, incentive; dedupe after purchase; retention purge; funnel + recovered revenue reports.

### 8.5 Products — P0

Title, rich HTML description, handle, vendor, type, taxonomy category; statuses active/draft/archived/unlisted; media (image/video/3D/file) with alt + order; price, compare-at, cost, margin, unit price, taxable, gift-card flag; SKU/barcode; weight/dims; HS code; country of origin; tags; categories; metafields; SEO fields; channel/market publication + schedule; duplicate/archive/restore/delete/preview; bulk status/tags/category/publish; CSV create/update/export with dry-run; change history; search index status.

**TRA-specific product fields:** grade (Training/Pro/Champion), custom branding flag, mockup required, production lead days, ring size chart reference, material specs blocks.

### 8.6 Variants and options — P0

Option names/values; combination generation; per-variant SKU/barcode/price/compare/cost/media/weight/tax/inventory policy/fulfillment service; market availability; metafields; ordering; duplication; bulk price adjust; prevent duplicate combinations; orphan inventory prevention.

**P0-C:** selling plans/subscriptions; preorder/backorder; bundles with component deduction.  
**P1:** configurators/add-ons (logo placements).

### 8.7 Categories / collections — P0

Hierarchical categories + manual collections + rule-based collections (tags, title, vendor, type, price, inventory, metafields) with AND/OR, preview, deterministic eval; image/description/SEO/template; market visibility; publication schedule; product ordering (manual/title/price/created/bestselling); bulk add/remove; menu assignment; handle-change redirects; **empty collection noindex policy**.

**P1:** pinned products, merchandising rules, market-specific order.

### 8.8 Inventory and locations — P0

Append-only inventory ledger. Locations with fulfillment capability and priority. Variant-location stocking. States: **available, committed, unavailable, incoming, on_hand**. Unavailable reasons: damaged, QC, safety stock, draft reservation, app hold. Adjustments with reason/note/reference/actor. Continue/stop selling OOS; backorder/preorder policies. Reservations + expiry. Cycle counts / stocktakes. Low-stock thresholds, reorder points, suggested qty. History by SKU/location/state. CSV import/export with concurrency. Bulk qty update; transfer create.

**P1:** lots/batches/serials/expiry/valuation reports (valuation also in Accounting).

### 8.9 Purchase orders and transfers — P0

**POs:** suppliers, currency, terms, destination, ETA, lines, taxes, shipping, notes; statuses draft/ordered (+ receiving partial/received/closed); irreversible ordered or amendment-controlled; PDF/email; duplicate/archive/export; landed-cost reconciliation.

**Transfers:** supplier→location and location→location; statuses draft/ready/in_progress/transferred/canceled; multi-shipment; reserve origin / incoming dest; partial accept/reject; discrepancy reasons; tracking; barcode receiving; freight cost adjust.

### 8.10 Customers and segments — P0

Profile, multi-address, language, market, account status; LTV metrics; notes/tags/metafields/timeline/attachments; consent ledger (email/SMS/WhatsApp) with evidence; tax exemptions; passwordless/magic-link or password accounts; order history; reorder; self-service returns; duplicate detect + audited merge; DSAR export/anonymize; CSV import/export; segment query builder (AND/OR, relative dates, purchases, geography, consent, tags, products, store credit); dynamic recalculation; use in discounts/marketing.

**P0-C B2B:** companies, locations, contacts, catalogs, payment terms, permissions (wholesale apply form → company workflow).

### 8.11 Discounts — P0

Code + automatic; % / fixed off product/collection/order; BXGY; free shipping; min subtotal/qty; eligibility by customer/segment/market/channel/product; schedule; usage limits; combination matrix; priority / best-discount resolution; usage + attributed revenue; rejection reasons; bulk activate/deactivate; code-set gen/import/export.

**P1:** volume tiers, employee, referral, discount functions.

### 8.12 Gift cards and store credit — P0-C / P1

Secure codes (masked admin); balances; expiry; statuses; issue/resend/disable/redeem; append-only ledger; refund to card; store credit accounts; liability reports; strict permissions; export masks secrets.

### 8.13 Content, files, metaobjects — P0

Pages, blog, menus, policies; draft/published/scheduled; author; revisions; SEO; metaobject definitions/entries; metafield definitions (type, validation, resource); revision history; bulk import/export.

**P1:** reusable sections, preview + approval workflow (replace GemPages).

### 8.14 Markets and localization — P0-C

Markets; currencies; price lists; catalogs; domains/subfolders; translations; rounding; FX strategy; tax/shipping overrides; geolocation recommend without forced redirect; hreflang/canonical; translation statuses; import/export.

### 8.15 Analytics and reports — P0 baseline / P1 parity

Canonical sales metrics; sales by time/product/variant/customer/channel/market/discount/location; fulfillment times; returns; inventory sell-through/aging; acquisition funnel; cohorts/RFM/LTV; attribution; finance reconciliation reports; report builder; scheduled delivery; CSV/XLSX; Live View (P1). See also §16 for advanced product analytics.

### 8.16 Marketing — P1 (consent/recovery P0)

Campaigns; UTM builder; short links/QR; subscriber lists; consent/suppression; template editor; automations (welcome, abandon, post-purchase, review, win-back, VIP, back-in-stock); frequency caps; quiet hours; forms; deliverability metrics; feed/channel sync adapters (P0-C if Google/Meta shopping used).

### 8.17 Payments — P0

PCI PSP adapters only (no raw PAN storage). Provider config by market/currency; cards/wallets/manual methods; intents; authorize/capture/partial/void/refund; async pending; idempotency; webhook reconcile; 3DS/SCA; AVS/CVV; fraud rules; payouts/fees/reserves; disputes; test mode; separate order/payment/payout ledgers.

### 8.18 Checkout — P0

Server-authoritative pricing; guest + customer; email/phone + marketing consent; addresses + validation; inventory revalidate + reserve at pay; discounts/gift cards/store credit; shipping/pickup/local delivery; taxes/duties; currency rounding; price-lock snapshot; payment orchestration; thank-you + order status; max qty; order notes; terms ack; anti-bot; rate limits; funnel telemetry (no PAN logging).

### 8.19 Shipping and delivery — P0

Locations; routing rules; shipping profiles; zones; flat/free/price/weight/carrier rates; backup rates; packages; processing/transit times; EDD; local delivery; pickup; split shipments; labels/manifests/tracking/voids/customs; returns labels; rate simulator.

### 8.20 Taxes and duties — P0

Registrations/tax IDs; destination/origin; product tax categories; exemptions; overrides; inclusive/exclusive; shipping/digital tax; immutable tax lines + evidence; HS/COO; de minimis; DDP/DAP; checkout duty estimates; jurisdiction reports; tax provider adapter preferred for multi-country.

### 8.21 Notifications — P0

Transactional email events (order, invoice, payment, fulfill, delivery, cancel, refund, return, account); SMS where consented; staff alerts; versioned templates (HTML/text), variables, locales; preview/test; sender/domain verification; bounce/complaint; retries; dedupe; marketing vs transactional separation.

### 8.22 Settings — P0

Store identity, legal, contact, timezone, units, currency; brand assets; domains/TLS/redirects/DNS; locations; checkout/accounts; payments/shipping/taxes/notifications/policies; markets/languages; custom data; privacy/cookies/consent/retention/DSAR; pixels; API credentials/webhooks; number sequences; document templates; feature flags; config export + audited changes.

### 8.23 Users / RBAC — P0

See §13.

### 8.24 Audit / observability — P0

See §13 and §21.

### 8.25 Apps / integrations / webhooks / API — P0

Versioned REST; pagination/filtering; OAuth apps + service accounts; scopes; app registry; rate limits; credential rotation; idempotency; bulk jobs; signed webhooks; outbox; delivery logs/replay; privacy webhooks (data request/delete); extension points (admin blocks, checkout, discounts, shipping, tax, automation); OpenAPI; sandbox.

---

## 9. Mandatory internal apps

### 9.1 Universal P0

| App | Purpose |
|-----|---------|
| Workflow / Flow engine | Triggers, conditions, actions, delays, history (§17) |
| Search & Discovery | Meilisearch index, synonyms, facets, boosts, redirects, zero-results, recommendations |
| Transactional Messaging | Email/SMS adapters, templates, delivery events |
| Forms & Consent | Contact/RFQ/wholesale/newsletter; evidence; spam controls |
| Fraud & Risk | Rules, velocity, review queue, hold/capture/cancel |
| Import/Export Center | Async CSV framework |
| Integration Hub | OAuth, webhooks, health, replay, reconciliation |

### 9.2 Conditional P0 (TRA likely needs)

| App | Why for TRA |
|-----|-------------|
| Returns & Exchanges | Physical goods |
| Shipping / Carrier Hub | Physical fulfillment |
| Tax/Duty Adapter | AU + international markets |
| Translate & Localize | If multi-language later |
| Product Feed / Channel Sync | Google/Meta shopping if used |
| B2B / Wholesale | Wholesale application page exists |
| Bundles | “Complete your ring setup” kits |
| Quote & Mockup | Core sales motion |

### 9.3 P1 apps

Marketing suite, Reviews/UGC, Loyalty, Advanced merchandising, Back-in-stock, Supplier forecasting, Customer portal enhancements.

### 9.4 Shopify apps replaced by first-party features

GemPages → CMS sections; HulkApps → Forms; Gallery apps → Media albums; Wishlist → Wishlist; Chat → CRM inbox; HubSpot → CRM + analytics; Clarity → first-party (optional keep); Shop Pay → PSP wallets.

---


## 10. Inbound CRM and pipelines

First-party CRM replaces HubSpot-style inbound for RFQs, wholesale, contact, and post-sale. Designed for quote-led custom canvas sales.

### 10.1 Customer data foundation

- Unified records: leads, contacts, companies, households, suppliers, partners, anonymous visitors
- Stable internal IDs + external IDs (ecommerce, email, social, accounting)
- Configurable fields/groups, required fields, validation, formulas, dependent fields, picklists, encrypted sensitive fields
- Multiple emails, phones, addresses, domains, social identities, tax IDs, currencies, languages, timezones, preferred channels
- Relationships: contact–company, parent–subsidiary, buying committee, owner, influencer, referrer
- Lifecycle: active, archived, merged, anonymized, blocked, do-not-contact
- Duplicate detection: exact, normalized, fuzzy, domain, phone
- Merge with survivor selection, relationship reassignment, ID redirects, reversible audit
- Bulk import/export with mapping, dry-run, row errors, dedupe, ownership, rollback
- Saved views, filters, tags, static/dynamic segments, column config, bulk actions, scheduled exports
- Permission-aware global search
- Activity timeline: emails, messages, calls, meetings, forms, web events, orders, returns, invoices, quotes, tasks, social, consent, automation
- Data quality dashboards: missing fields, stale leads, duplicates, invalid email/phone, bounces, unowned records

### 10.2 Consent, privacy, eligibility

- Consent ledger by person, purpose, brand, channel, jurisdiction, legal basis, source, policy version, timestamp, evidence
- Subscription center (topics + global unsubscribe)
- Suppression: unsubscribe, complaint, hard bounce, legal hold, employee, competitor, manual block
- Transactional vs marketing classification
- Quiet hours + frequency caps
- DSAR search/export/correct/delete/anonymize; retention; litigation hold
- Send-time eligibility gate before every send
- Jurisdiction adapters (AU Privacy Act, GDPR/ePrivacy, CCPA/CPRA, CAN-SPAM, CASL, PECR)

### 10.3 Lead capture and qualification

**Sources:** manual, CSV/API, web forms, chat, calls, inbound email, social, referrals, lead ads, events, abandoned carts, registrations, RFQ, wholesale apply.

**Features:**
- Source / original source / latest source, campaign, medium, content, keyword, referrer, landing page, UTM, click IDs
- Anonymous identity resolution (consent-gated)
- Qualification frameworks (BANT/MEDDICC/custom)
- Rules + predictive scoring with explainability, versioning, thresholds, override history
- Routing: territory, language, product, capacity, hours, VIP, round-robin, weighted, named account
- Accept/reject with reason + reassignment timer
- Convert to contact/company/opportunity/merge without losing attribution
- States: new, working, nurtured, qualified, recycled, disqualified, spam, lost

### 10.4 Companies / B2B accounts

Hierarchies, branches, domains, locations, territories, industries, size bands, tax status, health; account plans; ownership teams; ecommerce rollups (orders, revenue, returns, AOV, LTV, products, margin); engagement rollups; health score.

### 10.5 Pipelines and opportunities

- Multiple pipelines (retail, wholesale, event, custom mockup)
- Stages with entry/exit criteria, probabilities, required fields, approval gates, allowed transitions
- Opportunity products, qty, price books, discounts, tax, recurring, costs, margin, close date, competitor, loss reason
- Views: Kanban, list, forecast, calendar
- Stage history, time-in-stage, slippage, inactivity, next-step enforcement
- Split credit; forecast categories; quotas; coverage; snapshots
- Parent/child, renewal, expansion, replacement
- Quote/order/invoice linkage
- Approvals for discounts, margin floors, non-standard terms, credit limits

**TRA default pipeline example:** New RFQ → Qualification → Mockup brief → Mockup sent → Quote sent → Negotiation → Won (order) / Lost.

### 10.6 Unified inbox

- Shared/team + personal mailboxes
- Threading via provider IDs + RFC headers
- Assignment, followers, internal notes, mentions, collision detection, snooze, priority, tags, spam, close/reopen, bulk actions
- Channel-normalized conversation model with native IDs
- Suggested contact/company/opportunity matching
- Canned replies, snippets, signatures, attachments, knowledge links
- Send later, reminders, working hours
- Delivery/open/click/reply/bounce/complaint/unsubscribe events
- SPF/DKIM/DMARC + domain verification status
- Call logging (+ recordings with consent); calendar sync; handoff sales↔support↔finance↔social
- SLA timers with business calendars and pause states
- Token health / webhook replay / DLQ

### 10.7 Email templates and HTML builder

- Drag-and-drop: rows, columns, text, image, button, divider, spacer, hero, social, product, coupon, recommendation, footer
- Locked brand sections + design tokens
- Responsive controls, stacking, visibility, padding, alignment, dark-mode preview
- Raw HTML editor for authorized roles with sanitization
- Template/component revision history; clone; compare; restore; draft; approval; publish
- Merge fields with typed fallbacks, conditionals, loops, locale formatting
- Ecommerce product/order/cart blocks
- Personalization preview with test contacts
- Editable plain-text alternative
- Subject, preheader, sender, reply-to, campaign metadata, UTMs
- Link validation, alt-text checks, unsubscribe/address enforcement, accessibility + spam-risk checks
- Test sends, seed lists, multi-client previews, rendering snapshots
- CSS inlining, image hosting, sanitization
- Localization variants
- Four-eyes approval for high-volume sends
- Exact sent content retained for audit
- Experiments: subject/sender/content/send-time with holdouts

**Starter TRA templates:** RFQ acknowledgement, mockup ready, quote sent, quote reminder, order confirmation, production started, shipped, wholesale application received/approved/rejected, abandoned cart, review request, win-back.

### 10.8 Forms and landing capture

- Field types: text, email, phone, number, date, address, choice, consent, hidden, file, product, custom
- Conditional fields/pages, multi-step, progress, save/resume, prefill, progressive profiling
- Modes: standalone, hosted, embedded, modal, API/headless
- Map to CRM objects, tags, owners, campaigns, pipelines, automations
- Per-form duplicate/update policy
- Consent disclosure + policy version + optional double opt-in + evidence
- Spam: honeypot, rate limit, CAPTCHA/adaptive, disposable email checks
- Webhook/API with idempotency
- Success message/redirect/notification/autoresponder/asset/meeting booking
- Conversion analytics (views, starts, completions, field abandon, source, device)
- Form revisions preserve accepted schema/disclosure
- WCAG 2.2 compliance

**TRA forms (P0):** Contact, RFQ (full), Inline quote, Wholesale apply, Newsletter, Data sharing opt-out.

### 10.9 Quotes

- Draft from opportunity/cart/customer/manual
- Price books, variants, bundles, optionals, qty, discounts, shipping, tax, deposits, milestones
- Cost/margin visibility permission-gated
- Numbering, expiry, revision chains, duplicate/renewal, supersession
- Branded PDF + secure web quote
- Internal approvals (discount/margin/value/terms)
- Customer accept/decline/comments/optional selection; e-signature provider optional
- Acceptance evidence (signer, time, IP/device lawful, hash, final render)
- Convert to order/invoice/payment request
- Deposit + payment link + unpaid follow-up
- Tax/shipping recalculation policy with explicit price-lock

### 10.10 Tasks, activities, workload

Tasks/calls/emails/meetings/approvals; relative due dates; recurrence; dependencies; checklists; reminders; priority; effort; personal/team/queue/unassigned; calendar/agenda/list/Kanban/workload; business calendars; auto-create from stage/form/SLA/inactivity/quote/accounting; overdue escalation; playbooks.

### 10.11 SLAs

Policies by channel, tier, issue type, brand, timezone, priority; first/next/resolution/quote turnaround/lead acceptance/follow-up targets; business hours; pause states; warn/breach/escalation; dashboards; audited manual corrections.

### 10.12 Attribution and CRM analytics

Immutable touchpoints + models: first/last/lead-create/opp-create/linear/U/W/time-decay/position/custom; lookbacks; channel grouping; campaign hierarchy; influenced pipeline/revenue/margin/ROI; original vs latest attribution; refund/return treatment; funnel/velocity/win-loss/leakage/forecast accuracy/LTV/CAC/retention; label modeled vs causal.

### 10.13 CRM automation recipes (samples)

1. Form submit → dedupe → consent → enrich → score → route → SLA task → acknowledgement  
2. High-intent pricing visit → score ↑ → notify owner (consent-gated)  
3. Lead untouched 15m → warn; breach → reassign manager  
4. Stage advance → validate exit → playbook tasks → approval if discount/margin fail  
5. Quote accepted → lock revision → order/deposit → notify finance  
6. Hard bounce/complaint/unsub → suppress everywhere  
7. Inbound reply → stop sequence → reopen → assign  
8. Order/refund → update LTV + attribution (net policy)  
9. Ambiguous duplicate → human merge queue (never auto-merge legal entities)  
10. Consent expiry/policy change → pause marketing; re-consent  

---

## 11. Social media management

Single admin for brand pages. Official APIs only. Capability registry must drive UI — unsupported actions are explicitly blocked, never silently omitted.

### 11.1 Shared capabilities

- OAuth wizard; scopes shown pre-consent
- Multi brand/account/page/location/team
- Token vault, rotation, revoke, expiry monitoring, reconnect, permission health
- Capability registry: provider, account type, country, API version, scopes, app-review, entitlement
- Composer with network-specific limits, media ratios, codecs, thumbnails, captions, alt text, links, tags, location, privacy, interaction settings
- Per-network preview + validation (no silent downgrade)
- Drafts, calendar, campaigns, labels, queues, evergreen, duplication, localization, bulk schedule
- Approval chains, four-eyes, legal review, embargoes, comments, revisions, publish locks
- Native vs platform schedule; retry cutoff; duplicate prevention; partial-success reporting; native post IDs
- Asset library rights/license/expiry/alt/renditions/malware/usage
- Unified engagement inbox where APIs expose interactions
- Moderation rules; hide/delete/reply/escalate when supported
- Analytics normalized + native metric dictionary/provenance
- Listening only where entitled APIs allow
- Rate budgets, pagination checkpoints, webhook verify/replay, backfill limits, degraded mode
- API version/deprecation registry + contract tests
- **Never scrape consumer UIs**

### 11.2 Networks and limitations

#### Facebook Pages
**Supported:** publish/schedule/update(app-owned)/delete; photos/videos/links; comments/replies/reactions/mentions; moderation; Page Messenger; webhooks; Page Insights; lead retrieval if approved.  
**Limits:** Page roles/tokens/app review/rate limits; mostly update own posts; no general personal-profile publishing; messaging windows; no general firehose listening without approved public content access.

#### Instagram (professional)
**Supported:** image/carousel/video/Reels publish (mode-dependent); comments moderation; mentions; insights; DMs via messaging API; webhooks.  
**Limits:** no consumer accounts; Live + Advanced Access; ~100 API posts/24h (enforce platform value); media constraints; no inbox folders; 24h messaging window (+narrow extensions); listening limited to owned media/messages/mentions.

#### TikTok
**Supported:** Content Posting API upload/direct post; creator-info; privacy/comment/Duet/Stitch choices; owned profile/video retrieval if approved.  
**Limits:** unaudited private-only + low user caps; audited still capped (~15/day typical); no full comment-moderation/DM/organic analytics suite on general posting API; Research API ≠ commercial listening; respect user privacy choices.

#### X
**Supported (entitled tiers):** create/delete posts/replies; metrics; media; recent/full-archive search; DMs with user-context.  
**Limits:** paid entitlements; plan-specific rates/history/DM; private metrics need user context; fail closed when capability absent.

#### Reddit
**Supported:** OAuth link/text/image/video posts; comments; moderation + Modmail for moderated communities; search in scope.  
**Limits:** Modmail ≠ universal brand inbox; general PMs distinct; rate discretion; community rules still apply; commercial use may need agreement.

#### LinkedIn
**Supported (Community Management):** org posts (image/video/article); comments/reactions; page/share stats.  
**Limits:** org roles required; member social read restricted; Messages API partner-only — **do not advertise standard LinkedIn inbox**; no firehose listening; Ads/Lead Gen separate.

#### Pinterest
**Supported:** boards; Pin create/delete/list; analytics; ads if separate.  
**Limits:** no general DM inbox; don’t promise comment moderation/listening without documented entitlement.

#### YouTube
**Supported:** upload/metadata; playlists; thumbnails; captions; comments moderation; live + live chat while active; Analytics reports.  
**Limits:** no DM inbox; Community posts not general Data API; search listening quota-bound; default 10k units/day; analytics delayed/privacy-thresholded.

#### Google Business Profile
**Supported:** locations/attributes/photos; local posts/offers/events/CTAs; reviews + owner replies; notifications; performance keywords; multi-location governance.  
**Limits:** product posts not via local-post API currently; chat not API inbox; access request + quotas; authorized managers only; Q&A unavailable unless endpoint returns; storage/permitted-use constraints.

### 11.3 Social automation recipes (samples)

1. Draft → per-network validation → brand/legal approval → schedule → capture native IDs → analytics  
2. Partial multi-network failure → keep successes → retry failures → never duplicate successes  
3. Support/refund comment → CRM conversation + SLA  
4. Toxicity rule → hide if supported → moderator queue + evidence  
5. VIP comment → priority senior agent + account owner  
6. Low GBP review → recovery case → approved reply  
7. Token expiry → stop schedules → admin alert → list impacted capabilities  
8. Listening spike → PR incident (entitled data only)  
9. Media license expiry → block publish  
10. API budget threshold → prioritize publish/webhooks over analytics backfill  

---

## 12. Accounts, suppliers, and double-entry ledger

### 12.1 Accounting kernel

- Immutable posted journal lines; balanced debits/credits per entity/currency/ledger
- Draft → approved → posted; corrections via reversal + replacement only
- Posting source, document, actor, timestamps, batch, period, FX rate, dimensions, explanation
- Subledger ↔ GL control accounts + reconciliation status
- Idempotent posting; duplicate-document protection
- Multi-entity/warehouse/department/channel/project/cost-center/product dimensions
- Functional/transaction/reporting currencies; FX gains/losses; revaluation
- Accrual accounting; statement presentation configurable by jurisdiction

### 12.2 Chart of accounts

Account number/name/type/subtype/normal balance/parent/reporting category/tax mapping/currency restriction/control flag/active dates; templates; hierarchies; no direct post to headers/protected controls; effective-dated rename/reclass; dimension requirements; merge/deactivate after checks.

### 12.3 Supplier master (critical)

Legal/trading names; tax IDs; remittance addresses; contacts; bank accounts; currencies; payment terms; Incoterms; shipping modes; lead times; MOQs; certifications; hierarchy/sites; approved product lists; catalogs; price breaks; contracts/rebates; withholding; credit status/holds/disputes/risk; quality scorecards; spend analytics; **bank-detail change maker-checker + out-of-band verify + cooling period**; duplicate supplier/bank detection.

### 12.4 Procurement and receiving

Requisitions; budgets; RFQ compare; approvals; PO create/amend/change order/close/cancel; PO types: standard, blanket, scheduled, drop-ship, service, return; line qty/uom/price/discount/tax/freight/promised/warehouse/dimensions; partial receipts; over/under tolerances; inspection; reject/quarantine/returns/debit notes; GRNI accruals; service entry sheets; **3-way match** (PO/receipt/bill); 2-way / no-PO by policy; variance categories (price/qty/tax/freight/FX/timing).

### 12.5 Accounts payable

Bills, credit/debit notes, prepayments, deposits, recurring bills, expense claims, opening balances; OCR ingestion with confidence thresholds; duplicate detection; line matching + exception queues; terms/early pay discounts/installments/retainage/disputes/holds; approval matrix; AP aging; cash requirements; supplier statement reconcile; unapplied credits; payment proposals; batches; remittance; bank file/API; voids/stop/reversal; SoD: supplier maintain ≠ payment release ≠ bill approve.

Typical posts: bill DR inventory/expense/tax CR AP; payment DR AP CR cash (+FX/fees).

### 12.6 Accounts receivable

Invoices, credit notes, receipts, deposits, refunds, write-offs, opening balances; order/fulfillment/invoice links; allocations; AR aging; statements; reminders; disputes; credit limits; revenue/tax/receivable posts; COGS on shipment; bad-debt approval.

### 12.7 Source documents / receipts

Upload, email-in, scan/mobile, API; immutable original + checksum + OCR; split/combine; missing-document workflow; retention/legal hold/redaction/export.

### 12.8 Ledgers and financial reports

GL, AP, AR, inventory, tax, bank; trial balance; P&L; balance sheet; cash flow; equity changes; journal; account activity; AP/AR aging; vendor balances; spend by supplier/category; PPV; open PO; GRNI; tax; reconciliations; drill statement→account→journal→document; budgets/forecasts/dimensions/currency views; scheduled report packs with locked params.

### 12.9 Bank reconciliation

Accounts, feeds, statement files; matching rules; split/combine; transfers; fees/interest/FX; outstanding aging; prepare/approve/lock; no delete of reconciled rows; cash position/forecast.

### 12.10 Tax

Effective-dated codes/rates (sales/VAT-GST/use/reverse charge/import/withholding); inclusive/exclusive; rounding; input vs output controls; tax point; returns/workpapers; exemption certificates; locked tax periods; country adapters (AU GST first-class).

### 12.11 Inventory valuation, COGS, landed costs

Perpetual subledger; FIFO / weighted average (no LIFO under IFRS profile); cost layers; COGS on shipment; returns cost policy; counts/shrink/damage/obsolescence; NRV reviews.

**Landed costs:** freight, customs, duty, brokerage, insurance, handling, inspection; allocate by qty/weight/volume/value/equal/custom; estimate then true-up; capitalize eligible; split inventory vs COGS; recoverable tax excluded; discounts reduce cost; preview/approval/reversal/traceability.

### 12.12 Journals, periods, close

Standard/recurring/accrual/reversal/allocation/reclass/system journals; templates; attachments; approvers; fiscal calendars; soft/hard close; reopen approval; close checklist; subledger before GL; block on unposted/out-of-balance/stale recon/negative inventory/unmatched GRNI/suspense; privileged post-close journals; trial-balance snapshots + report hashes.

### 12.13 Accounting automation recipes (samples)

1. PO approved → budget reserve → send supplier PO  
2. Receipt before bill → DR inventory/expense CR GRNI  
3. Bill → OCR → duplicate check → 3-way match → auto-approve in tolerance else exception  
4. Matched bill → DR expense/inventory/tax CR AP; clear GRNI  
5. Payment proposal → exclude holds/unverified banks → maker → releaser → remittance  
6. Bank detail change → freeze payments → verify → dual approve  
7. Freight/customs → landed cost allocate → capitalize → true-up  
8. Shipment → reduce inventory + COGS; return reverses per policy  
9. Bank feed → deterministic match → suggestions → human approve → lock  
10. Period close → block if unreconciled → snapshot → lock  
11. Backdated into closed period → current-period adjusting entry  
12. Supplier credit → apply or retain unapplied with approval  

---

## 13. RBAC, security, privacy, and audit

### 13.1 Permission model

Deny-by-default; least privilege; server-side on every request; field-level + record-level; logged authz decisions.

Permissions combine:
- Module × action: view, create, edit, delete/archive, approve, publish, post, export, administer
- Record scope: own, team, territory, brand, entity, location, queue, all
- Field scope: PII, consent, margin, bank details, tax IDs, message bodies
- State constraints: draft vs approved; open vs closed period; unreconciled vs reconciled
- Value thresholds: quote discount, bill amount, payment amount, journal amount
- Channel/account constraints
- Temporary delegation with reason/window
- Service accounts scoped separately from humans

### 13.2 Baseline roles

CRM viewer, sales rep, sales manager, marketing creator, marketing approver, inbox agent, inbox supervisor, quote approver, CRM admin, privacy officer; social creator/publisher/moderator/analyst/legal approver/social admin; requester, buyer, receiver, AP clerk, AP approver, payment preparer, payment releaser, AR clerk, accountant, inventory accountant, tax accountant, controller, auditor, accounting admin; catalog manager, order manager, fulfillment, support; security admin; integration service account.

### 13.3 Incompatible duties (mandatory)

- Supplier create/bank change ≠ payment release  
- Bill entry ≠ final approval above threshold  
- Payment prepare ≠ release  
- Journal prepare ≠ approve/post  
- Reconciliation prepare ≠ approve  
- Social create ≠ final publish for high-risk  
- Quote create ≠ exceptional discount approve  
- Role admin ≠ audit-log admin  
- Automation author ≠ activate high-impact flows  
- Period reopen ≠ sole preparer of adjustments  

### 13.4 AuthN / session

MFA; recovery codes; session lifetime; device management; invite/activate/suspend; revoke sessions; optional SSO/OIDC (P1); password policies; login anomaly alerts.

### 13.5 Audit

Append-only events: authn, authz, exports, sensitive views, CRUD, merge, consent, sends, social actions, approvals, postings, reversals, reconciliations, role changes, token changes, automation runs. Fields: event ID, UTC, actor/impersonator, tenant/entity, session, correlation ID, IP/UA, action, object, before/after, reason, approval, policy version, result. Redact secrets. Tamper-evident storage; admins cannot alter history. Retention + legal holds. Alerts on privilege escalation, bulk export, payment anomalies, closed-period activity, suppression overrides, mass publish.

### 13.6 Privacy / security controls

Encryption in transit (TLS) and at rest for sensitive fields; OWASP ASVS-aligned coding; file-upload allowlists/malware scan; rate limits; WAF; secrets never in repo; backups encrypted; DSAR workflows; cookie/consent CMP; privacy policy versioning.

### 13.7 Disaster recovery

RPO/RTO targets documented; nightly DB backups + WAL/binlog; object storage versioning; restore drills quarterly; runbooks.

---

## 14. Media gallery (WordPress-parity + DAM)

### 14.1 WordPress parity features

- Drag/drop, multipart, resumable uploads
- Images, video, audio, PDF, approved documents
- Grid/list; bulk actions; filter by date/type/owner; full-text search
- Title, caption, alt, description, credit, copyright, tags, locale variants
- EXIF/IPTC/XMP extract with privacy stripping options
- Folders/collections (logical, not path-coupled)
- Crop, rotate, focal point, aspect presets; non-destructive edit history
- Attach to products/pages; **usage / attachment reporting**
- Trash, restore, retention; safe delete prevents broken refs
- MIME, dimensions, filesize, generated sizes metadata (WP Media API parity)

### 14.2 Advanced DAM

- Immutable originals + versioned derivatives
- AVIF/WebP/JPEG/PNG; responsive srcset
- Named crops: product card, zoom, social, marketplace, email
- Perceptual duplicate + checksum dedupe
- Optimization savings + quality controls + reprocess
- Video posters, transcripts, captions, streaming renditions
- License expiry + approval state
- Tenant/brand/collection permissions; signed private URLs
- S3-compatible storage + CDN invalidation + lifecycle tiers
- Malware quarantine; async processing via Horizon
- Gallery albums powering public `/pages/gallery`

### 14.3 Security

Type/signature allowlists; generated filenames; authz; size limits; store outside web root; meaningful alt text required for public images.

---

## 15. SEO platform (beyond Rank Math / Yoast)

### 15.1 SEO editor (every indexable entity)

Per-locale title, description, slug, canonical, robots, OG/X cards, image, breadcrumb label; variables (product, brand, price, inventory, category, location); inheritance global→type→taxonomy→item with provenance; pixel/character guidance; duplicate detection; SERP intent; schedule; approval; revisions/diff/rollback; bulk sheet/API dry-run; templates with collision detection; desktop/mobile SERP + social previews (labeled as simulations); role-gated advanced fields.

### 15.2 Audits

1. Editor-time checks  
2. Rendered crawler (SSR HTML, status, JS, canonical, robots, hreflang, pagination, orphans, redirect chains, schema)  
3. Production evidence (logs, Search Console, field CWV, index coverage)  

Findings include evidence, revenue impact, severity, confidence, owner, remediation, false-positive suppression, regression history.

### 15.3 Schema graph

Versioned JSON-LD with stable `@id`: Organization/OnlineStore, WebSite, WebPage, BreadcrumbList, Product/ProductGroup/Offer, reviews (eligibility-safe), shipping/returns, Article/NewsArticle/VideoObject/LocalBusiness/FAQ; visual graph editor; lint; Rich Results validation; snapshot tests. Fix current duplicate Organization/WebSite.

### 15.4 Redirects / canonicals / i18n

Exact/wildcard/regex; 301/302/307/308/410/451; import/export; hit counts; simulator; chain/loop/conflict detection; auto-suggest on slug/product change; canonical engine for variants/pagination/facets/tracking params; reciprocal hreflang + x-default; conflict prevention.

### 15.5 Sitemaps / robots

Incremental indexes by type/locale/freshness; product/image/video/news; only canonical indexable 200s; accurate lastmod; validation; Search Console compare; shard under 50k URL/50MB; versioned robots editor with staging simulation; detect robots/noindex contradictions; **empty collections excluded or noindexed**.

### 15.6 Internal linking and content intelligence

Link graph; orphan/dead-end; contextual anchors; related products; cannibalization; reviewable auto-link rules; keyword groups/entities/questions/intent; readability/originality/brand voice; content decay; revenue-weighted opportunities (not “green score” only).

### 15.7 Vertical packs

Local, Video, News, Commerce (GTIN/MPN/SKU, offers, inventory, shipping, returns, Merchant Center reconcile).

### 15.8 Search integrations and monitoring

Search Console OAuth + URL Inspection + sitemap submit + BigQuery bulk; GA4/Merchant/Bing adapters; edge/origin log ingestion; 404 dashboard with redirect recommendations; alerts on traffic/index/schema/sitemap anomalies.

### 15.9 Programmatic SEO guardrails

Indexable only if unique intent, substantive value, availability thresholds, unique title/H1/body, valid canonical/status/links/schema/hreflang, inbound link, quality score, approval for sensitive templates, index quota per template, auto-noindex empty facets, kill switch + bulk deindex.

### 15.10 TRA content SEO remediations (launch)

Fix H1s, meta gaps, policy canonical strategy, empty collection indexing, truncated titles, schema duplicates, currency labeling, editorial inconsistencies listed in §4.7–§4.8.

---

## 16. Product and business analytics

Far beyond typical third-party ecommerce plugins; first-party source of truth for money/inventory.

### 16.1 Surfaces

- Funnels: impression → view → cart → checkout → payment → purchase (open/closed, segmented)
- Cohorts: acquisition, first purchase, product, campaign, behavioral; retention; repeat; LTV
- Attribution: first/last/non-direct, linear, position/time-decay, controlled data-driven
- Merchandising: list position, search terms, zero-results, recommendations, bundles, attach rate, promo incrementality
- Inventory: sell-through, stockout exposure, lost demand, aging, weeks of supply, replenishment
- Profitability: net revenue, COGS, discounts, shipping, payment fees, fulfillment, returns, CAC, contribution margin
- Returns: rates, reasons, products, suppliers, cohorts, net-margin impact
- Forecasts: demand, revenue, stockout date, reorder qty, confidence intervals
- Experiments: sticky allocation, exposure events, primary + guardrail metrics, sample size, SRM, CIs, stopping rules

### 16.2 Event model

Immutable versioned events: identity (anon/session/customer/consent); context (ts, locale, currency, channel, device, campaign, referrer); commerce (product, variant, list, position, qty, price, discount, tax, inventory); event types; facts (order lines, inventory snapshots, costs, ad spend, returns, sessions); SCD2 product dimensions; experiment assignment immutable; money as integer minor units + FX snapshot; event IDs + idempotency + schema version.

### 16.3 TRA-specific KPIs

Quote request rate; RFQ→mockup→quote→won conversion; mockup turnaround; custom branding attach rate; grade mix (Training/Pro/Champion); size/colour mix; free-shipping threshold impact; wholesale vs retail margin.

### 16.4 Delivery of analytics

MySQL operational store; Redis aggregates for live widgets; Meilisearch for admin findability; optional columnar store later if volume requires; Pulse + custom dashboards; scheduled exports; reconciliation vs order/payment/inventory ledgers.

---


## 17. Automation engine

Central Flow engine used by ecommerce, CRM, social, and accounting.

### 17.1 Primitives

- Triggers: domain events, schedules, date-relative, webhooks, API, manual
- Logic: conditions, branches, waits (calendar-aware), loops with limits, random splits, goals, re-entry policies
- Actions: create/update records, assign owners, tasks, notifications, emails, webhooks, quotes, pipeline moves, social publish (approved), accounting handoffs, segments
- Controls: enrollment preview, dry run, test records, versioning, activation approval, rollback
- Reliability: idempotency keys, rate limits, retries, DLQ, recursion detection, per-step logs
- Mandatory gates: consent eligibility, capability registry (social), closed-period blocks (accounting), RBAC/SoD
- Analytics: enrolled, waiting, succeeded, skipped, failed, retried, suppressed, converted

### 17.2 Cross-domain recipes (ecommerce)

- Auto-capture low-risk payments; hold high-risk  
- Low stock → alert + draft PO suggestion  
- Abandoned cart/checkout recovery  
- Order paid → production task for custom branding  
- Fulfillment created → customer email + CRM timeline  
- Return requested → RMA + accounting hold  
- Price change → reindex Meilisearch + invalidate CDN tags  
- Empty collection detected → noindex + SEO alert  

### 17.3 Admin UX

Flow builder canvas; template gallery; run history; test mode; permissions (author vs activator); kill switch; impact estimates for bulk enrollments.

---

## 18. Domain model, data, APIs, events

### 18.1 Major entity groups (MySQL)

**Identity:** users, roles, permissions, role_user, sessions, personal_access_tokens, service_accounts, mfa_factors  
**Catalog:** products, product_options, product_option_values, variants, product_media, categories, category_product, collections, collection_rules, collection_product, metafield_definitions, metafields, metaobject_definitions, metaobjects  
**Inventory:** locations, inventory_items, inventory_levels, inventory_movements, reservations, transfers, transfer_lines, purchase_orders, purchase_order_lines, receipts, receipt_lines  
**Pricing/promo:** price_lists, prices, discount_codes, automatic_discounts, discount_redemptions, gift_cards, gift_card_transactions, store_credits, store_credit_transactions  
**Cart/order:** carts, cart_lines, checkouts, abandoned_checkouts, orders, order_lines, order_addresses, payments, refunds, fulfillments, fulfillment_lines, shipments, returns, return_lines, disputes  
**Customers:** customers, customer_addresses, companies, company_contacts, segments, segment_memberships, consents, suppressions  
**Content:** pages, posts, menus, menu_items, policies, redirects, seo_entities, schema_nodes, sitemaps  
**Media:** media_assets, media_variants, media_folders, media_attachments, media_licenses  
**CRM:** leads, contacts, crm_companies, pipelines, pipeline_stages, opportunities, opportunity_products, quotes, quote_lines, conversations, conversation_messages, tasks, sla_policies, sla_clocks, forms, form_submissions, email_templates, email_campaigns, attributions  
**Social:** social_accounts, social_capabilities, social_posts, social_media_items, social_approvals, social_engagements, social_metrics_daily  
**Accounting:** chart_of_accounts, journal_entries, journal_lines, suppliers, supplier_bank_accounts, bills, bill_lines, bill_payments, invoices_ar, ar_payments, bank_accounts, bank_statements, bank_statement_lines, reconciliations, tax_codes, tax_lines, landed_cost_pools, fiscal_periods, close_checklists  
**Automation:** automation_flows, automation_versions, automation_runs, automation_steps  
**Platform:** outbox_messages, webhook_endpoints, webhook_deliveries, audit_events, jobs/failed_jobs, feature_flags, settings, import_jobs, export_jobs  

### 18.2 Money and concurrency rules

- Store money as integer minor units + currency code  
- Snapshot product title/SKU/price/tax/discount on order lines  
- Inventory and accounting use append-only movements  
- Optimistic locking (`version` column) on editable commercial documents  
- DB transactions + outbox for event emission  

### 18.3 REST API families (`/api/v1`)

| Family | Examples |
|--------|----------|
| Auth | `/admin/login`, `/admin/mfa`, `/customer/session` |
| Catalog | `/products`, `/variants`, `/categories`, `/collections` |
| Inventory | `/locations`, `/inventory`, `/transfers`, `/purchase-orders` |
| Cart/Checkout | `/carts`, `/checkout`, `/shipping-rates`, `/payments/intents` |
| Orders | `/orders`, `/draft-orders`, `/returns`, `/fulfillments` |
| Customers | `/customers`, `/segments`, `/companies` |
| CRM | `/leads`, `/pipelines`, `/opportunities`, `/quotes`, `/inbox`, `/forms`, `/templates` |
| Social | `/social/accounts`, `/social/posts`, `/social/inbox` |
| Accounting | `/suppliers`, `/bills`, `/journals`, `/bank`, `/reports` |
| Media | `/media`, `/media/{id}/derivatives` |
| SEO | `/seo/entities`, `/redirects`, `/sitemaps`, `/audits` |
| Analytics | `/analytics/reports`, `/analytics/events` |
| Automations | `/automations`, `/automations/{id}/runs` |
| Admin util | `/search`, `/imports`, `/exports`, `/jobs`, `/audit` |
| Webhooks | `/webhooks` (management) + provider callback routes |

Conventions: JSON:API-ish or consistent `{ data, meta, errors }`; cursor/offset pagination; sparse fieldsets; `Idempotency-Key` header; RFC7807 errors; OpenAPI 3.1 published.

### 18.4 Domain events (sample catalogue)

`ProductPublished`, `InventoryAdjusted`, `CheckoutStarted`, `OrderPaid`, `OrderFulfilled`, `PaymentCaptured`, `RefundCreated`, `ReturnRequested`, `LeadCreated`, `OpportunityStageChanged`, `QuoteAccepted`, `FormSubmitted`, `EmailSuppressed`, `SocialPostPublished`, `BillMatched`, `JournalPosted`, `PeriodClosed`, `MediaProcessed`, `SeoIssueDetected`, `AutomationFailed`.

### 18.5 Meilisearch indexes

products, variants, categories, customers, orders, media, crm_records, help_settings, admin_global.

### 18.6 Reverb channels

`admin.notifications.{userId}`, `inbox.{teamId}`, `jobs.{jobId}`, `orders.live`, `presence.editing.{resource}`.

---

## 19. Integrations and official external APIs

| Need | Approach |
|------|----------|
| Card payments | PCI PSP (e.g. Stripe/Adyen/Braintree) — adapter pattern |
| Wallets | Via PSP (Apple Pay/Google Pay) |
| Email delivery | SMTP/API provider (SES/Postmark/etc.) — TRA owns templates |
| SMS/WhatsApp | Official provider APIs if enabled |
| Carriers | Optional rate/label adapters |
| Tax | Optional tax engine adapter + AU GST rules |
| Social | Official APIs per §11 |
| Search Console / GA4 | Official Google APIs |
| Cloudflare | CDN/WAF/API for purge |
| Object storage | S3-compatible |
| Maps/address | Optional autocomplete provider |

No HubSpot/Shopify apps/Klaviyo/Meta Business Suite as system-of-record. TRA is SoR; externals are pipes.

---

## 20. Performance, accessibility, and PageSpeed

### 20.1 Targets

| Metric | Target |
|--------|--------|
| Lighthouse desktop (5-run median) | ≥ 99 |
| Lighthouse mobile (5-run median) | ≥ 95 |
| Floor per run | ≥ 97 desktop / ≥ 92 mobile |
| Field LCP p75 | ≤ 2.5s |
| Field INP p75 | ≤ 200ms |
| Field CLS p75 | ≤ 0.1 |
| TTFB p75 | ≤ 500ms origin / ≤ 200ms CDN HIT |
| Initial JS (compressed) | ≤ 100 KB typical; ≤ 70 KB static landings |

### 20.2 Implementation strategy

- Hybrid Nuxt rendering + route rules + tag invalidation  
- Preload only LCP image + critical font; lazy-load rest  
- Correctly sized AVIF/WebP with dimensions + focal crops  
- Inline critical CSS; purge unused Tailwind  
- Self-host subset fonts (Segoe UI licensed where needed; Selawik for Apple)  
- Consent-gate third parties; prefer first-party analytics  
- Eliminate hydration on static islands; lazy hydrate below-fold  
- Laravel: cache read models; no N+1; queue noncritical work  
- Cloudflare edge cache HTML for anonymous catalog/content  

### 20.3 Accessibility

WCAG 2.2 AA storefront + admin critical flows; axe CI; keyboard nav; focus management in drawers/modals; form error association.

### 20.4 Mobile-first public UX

Single-column heroes; sticky ATC on PDP; filter drawers; large tap targets; no hover-only actions; cart drawer full-screen on small viewports.

---

## 21. Testing, CI/CD, DevOps, monitoring

### 21.1 Testing pyramid

- Unit/property: money, tax, inventory, canonical, hreflang, robots, redirect resolver  
- Contract: OpenAPI, JSON-LD, feeds, analytics schema  
- Feature: Laravel HTTP tests for checkout, refunds, journals, RBAC  
- Integration: Meilisearch, Redis, Horizon, Reverb, PSP sandbox, social sandbox  
- E2E Playwright: storefront browse→cart→checkout; admin order fulfill; RFQ→quote; media upload; SEO editor  
- Security: upload malware/MIME spoof; authz matrix; IDOR suite  
- Performance: Lighthouse CI budgets; load/soak checkout + admin lists  
- Accessibility: axe + manual audits  
- Data quality: reconciliation jobs (orders vs payments vs inventory vs GL)  
- A/A experiments before real A/B  

### 21.2 CI/CD

- PR: lint (PHP/TS), static analysis (PHPStan/Psalm, vue-tsc), unit, contract, Lighthouse smoke  
- Staging deploy: migrate, seed demo, smoke E2E  
- Prod: blue/green or rolling; migrate forward-only; feature flags; CDN purge tags  
- Never commit secrets; `.env.example` only  

### 21.3 Runtime ops

- Nginx + PHP-FPM + Node SSR (Nuxt)  
- Supervisor/systemd: Horizon, Reverb, Nuxt, Meilisearch  
- Laravel Pulse + server metrics (CPU, RAM, disk, queue depth, Redis hit rate)  
- Structured logs → central store; OpenTelemetry traces optional  
- Uptime checks on storefront + API health  
- Alerting: payment failures, queue backlog, 5xx spike, social token expiry, low disk, SSL expiry  

### 21.4 Backups

Nightly MySQL dump + binlog; object storage versioning; Meilisearch snapshots; encrypted offsite; restore drill quarterly.

---

## 22. Phased delivery roadmap

### Phase 0 — Foundations (Weeks 1–3)

Repo scaffold; Laravel modules skeleton; Nuxt + Admin Vue apps; MySQL/Redis/Meilisearch/Horizon/Reverb local; CI; auth + RBAC skeleton; audit middleware; settings; media core; SEO entity model; design tokens (Segoe/Selawik, gold palette).

### Phase 1 — Storefront parity + catalog (Weeks 4–8)

CMS pages/blog/menus/policies; product/variant/category CRUD; Meilisearch storefront search; cart; quote/contact forms → CRM leads; visual rebuild of all public templates; redirects from old Shopify URLs; schema + metadata; PageSpeed pass on home/PDP/collection.

### Phase 2 — Checkout & orders (Weeks 9–12)

Checkout, payments PSP, taxes shipping, inventory reservations, orders/drafts/abandoned, fulfillments, notifications, customer accounts, abandoned recovery, Pulse dashboards.

### Phase 3 — Ops depth (Weeks 13–16)

POs/transfers; returns; discounts; markets currency; import/export center; fraud rules; packing docs; staff RBAC matrix complete; admin UX polish (command palette, saved views).

### Phase 4 — CRM & quotes (Weeks 17–20)

Pipelines, inbox, HTML email builder, templates library, SLAs, RFQ/wholesale flows, quotes→orders, CRM automations, attribution baseline.

### Phase 5 — Accounting & suppliers (Weeks 21–25)

COA, suppliers, bills, 3-way match, payments SoD, journals, bank recon, GST AU, inventory valuation, landed costs, period close, financial reports.

### Phase 6 — Social + SEO + analytics advanced (Weeks 26–30)

Social connectors (FB/IG first, then others), calendar/approvals, SEO crawler audits, GSC, log/404, product analytics funnels/cohorts/profitability, experiments foundation.

### Phase 7 — Hardening & manual migration (Weeks 31–34)

Content/product manual migration playbooks; redirect map; UAT; load tests; security review; go-live checklist; cutover; hypercare.

*Durations indicative; parallelize frontend parity with backend modules where staffed.*

---

## 23. Risks, dependencies, launch checklist

### 23.1 Risks

| Risk | Mitigation |
|------|------------|
| Scope explosion (CRM+social+accounting) | Phased P0 gates; capability flags |
| Social API app review delays | Start Meta/Google review early; capability registry |
| Payment PCI complexity | Use hosted PSP fields / Checkout |
| PageSpeed vs design parity | Image pipeline + hybrid rendering from day 1 |
| Content inconsistencies migrate as truth | Editorial cleanup sprint before cutover |
| Accounting correctness | Dual control, accountant UAT, closed-period tests |
| PHP 8.5 / Laravel 13 ecosystem lag | Pin versions; CI matrix; fall back only if blocked (document change control) |

### 23.2 Dependencies

DNS/Cloudflare; TLS; object storage; PSP account; transactional email domain auth (SPF/DKIM/DMARC); social developer apps; staging hardware; licensed fonts if Segoe UI redistribution requires it (use system Segoe on Windows; Selawik webfont for Apple).

### 23.3 Launch checklist (abbreviated)

- [ ] All P0 modules feature-complete with RBAC  
- [ ] Storefront visual QA signed off (mobile+desktop)  
- [ ] Lighthouse budgets green  
- [ ] Schema/sitemaps/robots validated  
- [ ] Redirect map imported  
- [ ] Payments live + test refunds  
- [ ] Inventory ledger reconciled on staging  
- [ ] CRM RFQ→quote→order path verified  
- [ ] Backups + restore drill  
- [ ] Monitoring/alerts live  
- [ ] Privacy/consent/DSAR paths tested  
- [ ] Staff training + runbooks  
- [ ] Cutover window + rollback plan  

---

## 24. Requirements traceability checklist

Status values: `Planned` | `In progress` | `Done` | `Deferred`.

| ID | Module / feature | Priority | Phase | Status | Notes |
|----|------------------|----------|-------|--------|-------|
| TRA-001 | Public design parity | P0 | 1 | Planned | Segoe/Selawik + Lucide |
| TRA-002 | Home template | P0 | 1 | Planned | |
| TRA-003 | PDP + variants | P0 | 1 | Planned | Size×colour |
| TRA-004 | Collections + filters | P0 | 1 | Planned | Empty noindex |
| TRA-005 | Blog + articles | P0 | 1 | Planned | |
| TRA-006 | CMS pages + policies | P0 | 1 | Planned | Canonical policies |
| TRA-007 | Search + cart drawer | P0 | 1 | Planned | |
| TRA-008 | Country/currency UX | P0 | 1–3 | Planned | Markets P0-C |
| TRA-009 | Contact + RFQ + quote forms | P0 | 1/4 | Planned | CRM |
| TRA-010 | Wholesale apply | P0-C | 4 | Planned | B2B |
| TRA-011 | Wishlist | P1 | 3 | Planned | |
| TRA-012 | Gallery (media albums) | P0 | 1 | Planned | |
| TRA-013 | Customer accounts | P0 | 2 | Planned | |
| TRA-014 | Checkout + payments | P0 | 2 | Planned | PSP |
| TRA-015 | Shipping + taxes | P0 | 2 | Planned | |
| TRA-016 | Orders + drafts + abandoned | P0 | 2 | Planned | |
| TRA-017 | Fulfillments + returns | P0 | 2–3 | Planned | |
| TRA-018 | Inventory ledger + locations | P0 | 2–3 | Planned | |
| TRA-019 | POs + transfers | P0 | 3 | Planned | |
| TRA-020 | Discounts | P0 | 3 | Planned | |
| TRA-021 | Gift cards / store credit | P1 | 5 | Planned | |
| TRA-022 | Notifications templates | P0 | 2 | Planned | |
| TRA-023 | Customers + segments | P0 | 2–3 | Planned | |
| TRA-024 | B2B companies | P0-C | 4 | Planned | |
| TRA-025 | Content metafields/metaobjects | P0 | 1–3 | Planned | |
| TRA-026 | Admin home + global search | P0 | 0–3 | Planned | |
| TRA-027 | Import/Export center | P0 | 3 | Planned | |
| TRA-028 | Flow automation engine | P0 | 2–4 | Planned | |
| TRA-029 | Fraud/risk | P0 | 2 | Planned | |
| TRA-030 | Search & Discovery app | P0 | 1 | Planned | Meilisearch |
| TRA-031 | Integration Hub | P0 | 2 | Planned | |
| TRA-032 | CRM foundation + leads | P0 | 4 | Planned | |
| TRA-033 | Pipelines + opportunities | P0 | 4 | Planned | |
| TRA-034 | Unified inbox | P0 | 4 | Planned | |
| TRA-035 | HTML email builder | P0 | 4 | Planned | |
| TRA-036 | Quotes + mockup workflow | P0 | 4 | Planned | |
| TRA-037 | Forms builder | P0 | 1/4 | Planned | |
| TRA-038 | SLAs + tasks | P0 | 4 | Planned | |
| TRA-039 | CRM attribution | P1 | 4–6 | Planned | |
| TRA-040 | Social accounts + composer | P0 | 6 | Planned | Official APIs |
| TRA-041 | Social calendar + approvals | P0 | 6 | Planned | |
| TRA-042 | Social inbox/moderation | P0 | 6 | Planned | Capability-gated |
| TRA-043 | Social analytics | P1 | 6 | Planned | |
| TRA-044 | FB/IG connectors | P0 | 6 | Planned | First |
| TRA-045 | TikTok/X/Reddit/LinkedIn/Pinterest/YT/GBP | P1 | 6 | Planned | Staged |
| TRA-046 | Chart of accounts + journals | P0 | 5 | Planned | |
| TRA-047 | Supplier accounts + bank SoD | P0 | 5 | Planned | |
| TRA-048 | AP bills + 3-way match | P0 | 5 | Planned | |
| TRA-049 | AR invoices | P0 | 5 | Planned | |
| TRA-050 | Bank reconciliation | P0 | 5 | Planned | |
| TRA-051 | Tax GST AU | P0 | 5 | Planned | |
| TRA-052 | Inventory valuation + COGS | P0 | 5 | Planned | |
| TRA-053 | Landed costs | P0 | 5 | Planned | |
| TRA-054 | Period close | P0 | 5 | Planned | |
| TRA-055 | Financial reports | P0 | 5 | Planned | |
| TRA-056 | Comprehensive RBAC | P0 | 0–3 | Planned | |
| TRA-057 | Audit log immutable | P0 | 0 | Planned | |
| TRA-058 | Media library WP parity | P0 | 0–1 | Planned | |
| TRA-059 | DAM derivatives + CDN | P0 | 1 | Planned | |
| TRA-060 | SEO editor + schema graph | P0 | 1 | Planned | Beyond Rank Math/Yoast |
| TRA-061 | Redirects + sitemaps + robots | P0 | 1 | Planned | |
| TRA-062 | SEO audits + GSC + logs/404 | P1 | 6 | Planned | |
| TRA-063 | Programmatic SEO guardrails | P1 | 6 | Planned | |
| TRA-064 | Product analytics advanced | P0–P1 | 2/6 | Planned | |
| TRA-065 | Experiments | P2 | 6 | Planned | |
| TRA-066 | PageSpeed 99/95 | P0 | 1–2 | Planned | CI gated |
| TRA-067 | Horizon + Reverb + Pulse | P0 | 0–2 | Planned | |
| TRA-068 | Cloudflare + Nginx | P0 | 0 | Planned | |
| TRA-069 | Manual migration playbooks | P0 | 7 | Planned | Post-build |
| TRA-070 | Editorial inconsistency cleanup | P0 | 1/7 | Planned | §4.8 |

---

## 25. Appendix: references

### Storefront
- [https://theringauthority.com/](https://theringauthority.com/)
- [https://theringauthority.com/robots.txt](https://theringauthority.com/robots.txt)
- [https://theringauthority.com/sitemap.xml](https://theringauthority.com/sitemap.xml)
- [https://theringauthority.com/agents.md](https://theringauthority.com/agents.md)

### Shopify (parity research)
- [Shopify admin overview](https://help.shopify.com/en/manual/shopify-admin/shopify-admin-overview)
- [Managing orders](https://help.shopify.com/en/manual/fulfillment/managing-orders)
- [Product details](https://help.shopify.com/en/manual/products/details/product-details-page)
- [Inventory states](https://help.shopify.com/en/manual/products/inventory/fundamentals/inventory-states)
- [Purchase orders](https://help.shopify.com/en/manual/products/inventory/purchase-orders/creating-purchase-orders)
- [Customer segments](https://help.shopify.com/en/manual/customers/customer-segmentation/create-customer-segments)
- [Discounts](https://help.shopify.com/en/manual/discounts/discount-types)
- [Markets](https://help.shopify.com/en/manual/markets)
- [Shopify analytics](https://help.shopify.com/en/manual/reports-and-analytics/shopify-reports)
- [Checkout settings](https://help.shopify.com/en/manual/checkout-settings)
- [Shipping setup](https://help.shopify.com/en/manual/shipping/setting-up-and-managing-your-shipping)
- [Taxes](https://help.shopify.com/en/manual/taxes/registration/manage)
- [Users & permissions](https://help.shopify.com/en/manual/your-account/users/roles/permissions/store-permissions)
- [Activity logs](https://help.shopify.com/en/manual/shopify-admin/activity-logs)
- [Apps by Shopify](https://help.shopify.com/en/manual/apps/app-types/apps-by-shopify)
- [GraphQL Admin API](https://shopify.dev/docs/api/admin-graphql/latest)
- [Webhooks](https://shopify.dev/docs/apps/build/webhooks)

### SEO / media
- [Rank Math Analytics](https://rankmath.com/kb/analytics/)
- [Yoast content analysis](https://yoast.com/help/optimize-your-content-with-yoast-seo-sidebar/)
- [Google Product structured data](https://developers.google.com/search/docs/appearance/structured-data/product)
- [Google sitemaps](https://developers.google.com/search/docs/crawling-indexing/sitemaps/build-sitemap)
- [Core Web Vitals](https://web.dev/articles/vitals)
- [WordPress Media REST](https://developer.wordpress.org/rest-api/reference/media/)
- [OWASP File Upload](https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html)
- [WCAG 2.2](https://www.w3.org/TR/WCAG22/)

### Social APIs
- [Facebook Pages API](https://developers.facebook.com/docs/pages-api/overview/)
- [Instagram Platform](https://developers.facebook.com/docs/instagram-platform/overview)
- [TikTok Content Posting](https://developers.tiktok.com/doc/content-posting-api-reference-direct-post)
- [X API](https://docs.x.com/x-api/introduction)
- [Reddit OAuth API](https://www.reddit.com/dev/api/oauth/)
- [LinkedIn Posts API](https://learn.microsoft.com/en-us/linkedin/marketing/community-management/shares/posts-api)
- [Pinterest Pins API](https://developers.pinterest.com/docs/api/v5/pins-create/)
- [YouTube Data API](https://developers.google.com/youtube/v3/getting-started)
- [Google Business Profile API](https://developers.google.com/my-business/reference/rest)

### Accounting / security
- [IAS 2 Inventories](https://www.ifrs.org/issued-standards/list-of-standards/ias-2-inventories/)
- [IAS 1 Presentation](https://www.ifrs.org/content/dam/ifrs/publications/html-standards/english/2021/issued/ias1.html)
- [IRS Pub 583](https://www.irs.gov/publications/p583) (document evidence patterns)
- [OWASP Authorization](https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html)
- [NIST SP 800-53](https://csrc.nist.gov/pubs/sp/800/53/r5/upd1/final)

### Stack
- [Laravel 13 docs](https://laravel.com/docs/13.x)
- [Nuxt 4 docs](https://nuxt.com/docs/4.x/getting-started/introduction)
- [Nuxt performance](https://nuxt.com/docs/4.x/guide/best-practices/performance)
- [Laravel Horizon](https://laravel.com/docs/13.x/horizon)
- [Laravel Reverb](https://laravel.com/docs/13.x/reverb)
- [Laravel Pulse](https://laravel.com/docs/13.x/pulse)
- [Meilisearch](https://www.meilisearch.com/docs)

---

## Document control

| Field | Value |
|-------|-------|
| Project | TRA |
| DB | `ronnie_tra` (credentials via env) |
| Nature | Greenfield build; manual data migration later |
| Public design | Preserve TRA storefront visual language |
| Ownership | First-party modules for commerce, CRM, social, accounting, SEO, media, analytics |
| External pipes | Official payment, email, carrier, social, and search APIs only |

**End of plan.md** — this document is the implementation source of truth until superseded by an approved revision.