24 — Build Notes Execution Standards (Blueprint §10)

24 — Build Notes Execution Standards (Blueprint §10)

Source: 02-Implementation-Blueprint.md — §10) Build Notes for This Boilerplate.

Product alignment: 01-Post-Purchase-Video-Testimonial-Collector-Plan.md — maintain delivery velocity while keeping implementation consistent with this repository’s conventions.

This document is a build spec only. No code changes are implied until a task references this file.

Related: 04 cleanup plan, 20 schema/migrations, 21 route map, and all screen plans (05–23).

---

0) Goal (one sentence)

Convert blueprint build notes into enforceable implementation standards so all testimonial features are built consistently and safely in this existing codebase.

---

1) Blueprint §10 notes (verbatim intent -> actionable rule)

Blueprint notes:

1. Reuse current nav pattern in app/routes/app.jsx.
2. Reuse page composition style from app.settings.jsx and app.appearance.jsx.
3. Keep actions idempotent where webhook retries can happen.
4. Use UTC date buckets for analytics.
5. Keep optional fields nullable to avoid migration friction.

This plan turns each into concrete engineering checks.

---

2) Navigation standard (app/routes/app.jsx)

2.1 Required behavior

• Add testimonial links to existing nav shell instead of creating a parallel admin shell.
• Keep existing retained modules (settings/support/promo) visible per 04.
• Group testimonial routes in logical order:
  • Dashboard
  • Campaigns
  • Templates
  • Submissions
  • Published
  • Widget
  • Moderation
  • Requests
  • Analytics
  • Billing

2.2 Acceptance criteria

• All links in nav resolve to existing route files.
• No duplicate nav systems or route wrappers introduced.
• Route names follow app.testimonial-* conventions (21).

---

3) Page composition standard (Polaris + route patterns)

3.1 Required behavior

• Use existing page skeleton patterns from app.settings.jsx / app.appearance.jsx:
  • Page + Card + BlockStack layout rhythm
  • consistent button placements and toast behavior
  • loader/action shape consistent with current Remix/React Router usage

3.2 Shared UI expectations

• All admin pages:
  • authenticate in loader/action
  • scope queries by shopId
  • support loading, empty, and error states
• Avoid introducing a completely different component system for testimonial screens.

3.3 Acceptance criteria

• Testimonial pages visually match existing admin pages in spacing and card rhythm.
• Action success/failure feedback uses same toast/banner style across screens.

---

4) Idempotency standard (webhooks + workers)

4.1 Where mandatory

• Shopify webhook routes:
  • webhooks.orders.paid.jsx
  • webhooks.orders.fulfilled.jsx
  • existing compliance/billing routes that remain
• Cron/worker routes:
  • due send processor
  • media callback/processor

4.2 Required techniques

• Unique keys on business identity (e.g. campaign+order+product)
• Upsert or ignore-on-conflict patterns
• Safe retries that do not duplicate side effects
• 2xx response on duplicate webhook replays

4.3 Acceptance criteria

• Replaying same webhook payload does not create duplicate TestimonialRequest.
• Re-running worker job does not duplicate sends/submissions/log rows unexpectedly.

---

5) UTC analytics standard

5.1 Required behavior

• All aggregation buckets use UTC days.
• Date filters parse/emit YYYY-MM-DD in UTC.
• TestimonialDailyAnalytics.date is UTC bucket start.

5.2 UI rule

• Display dates in merchant-friendly format, but aggregation/storage remains UTC.

5.3 Acceptance criteria

• Daily counts do not shift around timezone boundaries in staging tests.
• Dashboard and analytics totals match raw SQL UTC-window spot checks.

---

6) Nullable-first migration standard

6.1 Required behavior

• Introduce new fields as nullable/defaulted when feature paths are not fully live.
• Tighten constraints only after:
  • routes are deployed
  • write paths backfill expected values
  • monitoring confirms no null leaks

6.2 Migration phases

1. Add columns/models nullable + defaults
2. Deploy write paths
3. Backfill if needed
4. Add stricter constraints (optional)

6.3 Acceptance criteria

• No deploy blocked by missing values for newly introduced testimonial fields.
• Existing installs migrate without manual intervention.

---

7) Standards by feature area

7.1 Campaigns/Templates

• Reuse existing admin form conventions.
• Ensure action idempotency for duplicate submit clicks.

7.2 Request pipeline

• Webhook and worker idempotency mandatory.
• UTC scheduling semantics documented.

7.3 Submissions/moderation

• Keep optional media metadata nullable during processing.
• Do not assume durationSec/thumbnailUrl exist at initial ingest.

7.4 Widgets/public API

• Keep public contracts stable; do not leak internal nullable fields.
• Default missing styling/config from shop settings safely.

7.5 Analytics/billing

• Use UTC for all counters.
• Nullable-first for optional advanced metrics (opened, UTM dimensions, etc.).

---

8) Code review checklist (enforce §10)

Every testimonial PR should include:

• Route uses existing shell/nav patterns.
• Page composition follows existing admin style.
• Idempotency notes for webhook/worker writes.
• UTC handling explicitly documented for date logic.
• New schema fields evaluated for nullability/backfill impact.

Add this checklist to PR template comments if possible.

---

9) Suggested lint/static guardrails (optional)

• Utility wrapper for UTC date range parsing (single source).
• Shared idempotency helper for webhook handlers.
• Shared schema constants for statuses/enums to avoid string drift.

These reduce implementation variance across teams.

---

10) Implementation order (for Cursor)

1. Adopt this standards doc before coding new testimonial routes.
2. Apply route map (21) and schema plan (20) with nullable-first strategy.
3. Build milestone features (23) while checking section 8 checklist on each PR.
4. After MVP stabilizes, tighten constraints and optimize indexes.

---

11) References

• 02-Implementation-Blueprint.md — Section 10 (Build Notes)
• 04-Delete All Existing Code and DB Tables.md
• 20-database-design-and-migrations-blueprint-section-5.md
• 21-route-and-file-map-blueprint-section-6.md
• 23-release-plan-and-milestones-blueprint-section-9.md

---

12) Note on numbering

This folder already includes 05 through 23 plans. This file is 24-....