21 — Route & File Map Execution Plan (Blueprint §6)
Cursor-ready implementation map for admin routes, public routes, webhook routes, and theme extension structure for the testimonial app.
21 — Route & File Map Execution Plan (Blueprint §6)
Section titled “21 — Route & File Map Execution Plan (Blueprint §6)”Source: 02-Implementation-Blueprint.md — §6) Suggested Route/File Map (Boilerplate-Aligned).
Product alignment: 01-Post-Purchase-Video-Testimonial-Collector-Plan.md — complete surface area (admin + public + automation + storefront).
This document is a build spec only. No code changes are implied until a task references this file.
Related: all previously created screen-specific plans (05 to 20) and cleanup plan 04.
0) Goal (one sentence)
Section titled “0) Goal (one sentence)”Provide one authoritative route/file implementation map so Cursor can build the testimonial app in a predictable order without route collisions, dead links, or inconsistent naming.
1) Scope
Section titled “1) Scope”This plan covers only wiring and structure:
- Admin route files
- Public/customer route files
- Webhook route files
- Theme extension file layout
- Navigation mapping
- Suggested implementation phases
Out of scope:
- Deep business logic for each screen (covered in individual numbered plans).
2) Naming strategy (critical)
Section titled “2) Naming strategy (critical)”Use blueprint route names as canonical:
app/routes/app.testimonial-*.jsxfor adminapp/routes/t.$token.jsx+app/routes/api.testimonial-*.jsxfor public APIsapp/routes/webhooks.orders.*.jsxfor Shopify order automation
Keep this naming stable across all plans to avoid drift.
3) Admin routes map
Section titled “3) Admin routes map”Implement (or alias) these admin routes exactly:
app/routes/app.testimonial-dashboard.jsxapp/routes/app.testimonial-campaigns.jsxapp/routes/app.testimonial-campaign.$id.jsxapp/routes/app.testimonial-templates.jsxapp/routes/app.testimonial-submissions.jsxapp/routes/app.testimonial-submission.$id.jsxapp/routes/app.testimonial-published.jsxapp/routes/app.testimonial-widget.jsxapp/routes/app.testimonial-moderation.jsxapp/routes/app.testimonial-requests.jsxapp/routes/app.testimonial-analytics.jsxapp/routes/app.testimonial-billing.jsx
3.1 URL mapping (recommended)
Section titled “3.1 URL mapping (recommended)”| Route file | URL |
|---|---|
app.testimonial-dashboard.jsx | /app (or /app/testimonials/dashboard) |
app.testimonial-campaigns.jsx | /app/testimonial-campaigns |
app.testimonial-campaign.$id.jsx | /app/testimonial-campaigns/:id |
app.testimonial-templates.jsx | /app/testimonial-templates |
app.testimonial-submissions.jsx | /app/testimonials |
app.testimonial-submission.$id.jsx | /app/testimonials/:id |
app.testimonial-published.jsx | /app/testimonials/published |
app.testimonial-widget.jsx | /app/testimonials/widget |
app.testimonial-moderation.jsx | /app/testimonials/moderation |
app.testimonial-requests.jsx | /app/testimonials/requests |
app.testimonial-analytics.jsx | /app/testimonials/analytics |
app.testimonial-billing.jsx | /app/testimonials/billing |
3.2 Backward compatibility with existing app shell
Section titled “3.2 Backward compatibility with existing app shell”Current repo already has app._index.jsx and non-testimonial nav items.
For migration:
- Either repurpose
app._index.jsxas dashboard adapter toapp.testimonial-dashboard.jsx - Or keep dashboard logic in
app._index.jsxand route-link to it from testimonial nav.
Document chosen approach in a short README in this folder when implementing.
4) Public/customer routes map
Section titled “4) Public/customer routes map”Required:
app/routes/t.$token.jsxapp/routes/api.testimonial-upload-url.jsxapp/routes/api.testimonial-submit.jsx
Optional:
app/routes/api.testimonial-media-callback.jsx
4.1 Public route guardrails
Section titled “4.1 Public route guardrails”- Must not require
authenticate.admin - Must enforce token validation and rate limits (
06+08) - Must keep response contracts stable for widget/public clients
5) Webhook routes map
Section titled “5) Webhook routes map”Required by blueprint:
app/routes/webhooks.orders.paid.jsxapp/routes/webhooks.orders.fulfilled.jsx
5.1 Existing webhooks coexistence
Section titled “5.1 Existing webhooks coexistence”Keep existing mandatory Shopify routes:
webhooks.compliance.jsxwebhooks.app.uninstalled.jsxwebhooks.app.scopes_update.jsxwebhooks.app_subscriptions.update.jsx
Ensure order webhooks are registered in app config and HMAC-verified.
6) Theme extension file map
Section titled “6) Theme extension file map”Blueprint recommendation aligned with Screen 8.1:
Option A (recommended)
Section titled “Option A (recommended)”extensions/<testimonial-extension>/blocks/testimonial-widget-home.liquidextensions/<testimonial-extension>/blocks/testimonial-widget-pdp.liquidextensions/<testimonial-extension>/assets/testimonial-widget.js
Option B (alternative)
Section titled “Option B (alternative)”- single block:
extensions/<testimonial-extension>/blocks/testimonial-widget.liquid- schema mode:
home_top_videos | product_reviews
Recommendation: Option A for clearer merchant mental model and easier support.
7) Navigation wiring map (app/routes/app.jsx)
Section titled “7) Navigation wiring map (app/routes/app.jsx)”Add links in testimonial section:
- Dashboard
- Campaigns
- Templates
- Submissions
- Published
- Widget
- Moderation
- Requests
- Analytics
- Billing
Keep existing support/promo/settings modules per plan 04.
8) Implementation sequencing by route groups
Section titled “8) Implementation sequencing by route groups”Phase 1: Core automation and intake
Section titled “Phase 1: Core automation and intake”- Campaigns list/create
- Templates
- Order webhooks
- Request pipeline
- Public submission routes
Phase 2: Moderation and publication
Section titled “Phase 2: Moderation and publication”- Submissions inbox/detail
- Published manager
- Widget settings + storefront API + theme extension
Phase 3: Observability and monetization
Section titled “Phase 3: Observability and monetization”- Requests log
- Analytics
- Billing & usage
This phase split aligns with milestone intent from blueprint section 9.
9) Route dependency matrix
Section titled “9) Route dependency matrix”| Route | Depends on |
|---|---|
Campaigns (2,3) | DB models TestimonialCampaign* |
Templates (4) | TestimonialTemplate, send-test adapters |
Submissions (5,6) | TestimonialSubmission, TestimonialMediaAsset, moderation log |
Published (7) | submission publish fields + placement visibility |
Widget (8) | shop widget settings storage + public read API |
Requests (10) | TestimonialRequest, TestimonialRequestEvent |
Analytics (11) | request/submission data (+ optional rollups) |
Billing (12) | subscription + usage counters |
| Public token page | TestimonialRequest + submission APIs |
| Order webhooks | campaign definitions + request creation pipeline |
10) Route-level acceptance checklist
Section titled “10) Route-level acceptance checklist”- Every route resolves under expected URL.
- No collisions with existing legacy routes.
- Every admin route uses
authenticate.admin. - Public routes avoid admin auth and have explicit validation/rate limit.
- Webhook routes are idempotent and verified.
- Nav links point to working routes.
11) Implementation order (for Cursor)
Section titled “11) Implementation order (for Cursor)”- Finalize route naming and URL conventions from this file.
- Scaffold all route files with TODO stubs and shared auth/error patterns.
- Wire nav entries in
app.jsx. - Implement route logic incrementally per phase.
- Keep this file as route source of truth; update only when intentional changes are made.
12) References
Section titled “12) References”02-Implementation-Blueprint.md— Section 6 route/file map04-Delete All Existing Code and DB Tables.md— retained modules + cleanup constraints05through20plans — route-level implementation detail
13) Note on numbering
Section titled “13) Note on numbering”This folder already includes 05 through 20 plans. This file is 21-....