26 — Project Conventions Execution Guide (Blueprint §2.1)

26 — Project Conventions Execution Guide (Blueprint §2.1)

Source: 02-Implementation-Blueprint.md — §2.1 Existing project conventions to follow.

Product alignment: 01-Post-Purchase-Video-Testimonial-Collector-Plan.md — implement testimonial features in a way that matches this repo’s established patterns.

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

Related: 20 (schema), 21 (route map), 24 (build standards).

---

0) Goal (one sentence)

Turn blueprint convention bullets into practical coding standards so every testimonial feature feels native to this boilerplate and avoids one-off patterns.

---

1) Blueprint §2.1 convention bullets -> required standards

Blueprint states:

1. Keep merchant-level config in Shop where possible.
2. New app entities should include standard fields (id, shopId, timestamps, shop relation with cascade).
3. Add route files as app/routes/app.<screen>.jsx.
4. Use authenticate.admin(request) in loaders/actions.
5. Use webhook routes for automation (app/routes/webhooks.*.jsx).

This plan expands each into enforceable implementation rules.

---

2) Tenant configuration standard (Shop as primary config home)

2.1 Required behavior

• Store per-shop feature toggles, defaults, and lightweight UI settings on Shop when they are singleton config.
• Example testimonial config fields:
  • widget defaults
  • moderation defaults
  • consent version
  • support contact channels for handoff copy (if reused)

2.2 When not to use Shop

Use dedicated tables when data is:

• repeatable (campaigns, requests, submissions),
• high-volume (events, media assets),
• history/audit oriented.

2.3 Acceptance criteria

• No repeated “settings rows” tables for singleton values unless justified.
• Shop-scoped config reads/writes are simple and indexed by shopId.

---

3) Entity skeleton standard (Prisma)

For each new tenant-owned model, include:

• id String @id @default(uuid())
• shopId String @map("shop_id")
• createdAt DateTime @default(now()) @map("created_at")
• updatedAt DateTime @updatedAt @map("updated_at") (if mutable)
• relation:
  • shop Shop @relation(fields: [shopId], references: [id], onDelete: Cascade)

Also:

• add @@map("snake_case_table")
• add indexes matching expected query patterns

3.1 Exceptions

Join tables without updates may omit updatedAt if truly immutable.

3.2 Acceptance criteria

• Every testimonial model follows this skeleton unless a documented exception exists.
• No orphaned rows remain on shop deletion/redact due to missing cascade chain.

---

4) Route naming standard

4.1 Admin routes

Follow:

• app/routes/app.testimonial-*.jsx

Examples:

• app.testimonial-campaigns.jsx
• app.testimonial-templates.jsx
• app.testimonial-submissions.jsx

4.2 Detail routes

Use $id files:

• app.testimonial-campaign.$id.jsx
• app.testimonial-submission.$id.jsx

4.3 Public routes

Not under app. namespace:

• t.$token.jsx
• api.testimonial-*.jsx

4.4 Acceptance criteria

• Route filenames match route URLs from 21.
• No mixed naming conventions (app.video-testimonials-* vs app.testimonial-*) without migration note.

---

5) Admin auth standard

5.1 Required behavior

All admin loaders/actions must:

1. call authenticate.admin(request)
2. resolve current shop identity from session
3. scope all data operations by that shop

5.2 Write-path guardrail

Even with record id present in URL/form:

• re-check that record belongs to current shop before mutate.

5.3 Acceptance criteria

• Every admin route contains explicit auth call in loader/action.
• Cross-shop ID probing returns not found/forbidden without data leakage.

---

6) Webhook automation standard

6.1 File pattern

Use dedicated files under:

• app/routes/webhooks.orders.paid.jsx
• app/routes/webhooks.orders.fulfilled.jsx

6.2 Required behaviors

• Verify webhook signature before side effects.
• Keep handlers idempotent for retries.
• Return fast response paths where possible.

6.3 Shared helper recommendation

Create utility wrapper for webhook verification + shop lookup to avoid duplication.

6.4 Acceptance criteria

• Replayed webhook does not duplicate request rows.
• Invalid signature never writes DB state.

---

7) Boilerplate consistency standards (practical)

7.1 DB naming

• Keep snake_case @map columns.
• Keep table @@map names stable and descriptive.

7.2 Action intent pattern

• Use form/action intents (intent=...) for multi-action routes.
• Validate intent and payload server-side.

7.3 Error shape consistency

• Admin routes: user-friendly errors via Polaris banners/toasts.
• Public APIs: JSON error contract with HTTP status + stable error code.

7.4 Time handling

• Persist UTC timestamps.
• Convert only at presentation layer.

---

8) Convention compliance checklist (for PR review)

• Shop config fields placed on Shop unless repeatable/high-volume.
• New models include id/shopId/timestamps/shop relation/cascade.
• Route naming follows app.testimonial-* + $id details.
• Admin auth + shop scoping implemented in every loader/action.
• Webhooks follow dedicated files, signature verification, idempotency.
• UTC and naming conventions respected in schema + queries.

Add this checklist to every testimonial PR description.

---

9) Suggested implementation order

1. Apply this conventions guide before scaffolding any new file.
2. Implement schema (20) and route map (21) using these standards.
3. Implement feature plans (05 onward) while validating this checklist.
4. If deviations are necessary, document them in the relevant plan file.

---

10) References

• 02-Implementation-Blueprint.md — Section 2.1
• 20-database-design-and-migrations-blueprint-section-5.md
• 21-route-and-file-map-blueprint-section-6.md
• 24-build-notes-execution-standards-blueprint-section-10.md

---

11) Note on numbering

This folder already includes 05 through 25 plans. This file is 26-....