25 — Core Modules Breakdown (Blueprint §2.2)

25 — Core Modules Breakdown (Blueprint §2.2)

Source: 02-Implementation-Blueprint.md — §2.2 Core modules.

Product alignment: 01-Post-Purchase-Video-Testimonial-Collector-Plan.md — end-to-end app architecture for post-purchase testimonial capture.

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

Related: 20 (schema), 21 (route map), 22 (integration flow), 23 (milestones).

---

0) Goal (one sentence)

Define clear module boundaries and interfaces so Cursor can implement each subsystem independently while preserving a coherent end-to-end flow.

---

1) Blueprint module list (canonical)

From blueprint §2.2:

1. Campaign engine (who gets request + when)
2. Request delivery (email/SMS)
3. Public submission page (secure token URL)
4. Media ingestion/processing
5. Moderation queue
6. Storefront widget publication
7. Analytics/billing

This plan maps each module to concrete responsibilities and handoff contracts.

---

2) Module contracts (input -> output)

M1) Campaign Engine

Responsibility

• Determine campaign eligibility from order webhook data.
• Produce one request unit per eligible delivered product line item.

Input

• shop + order webhook payload
• active campaign definitions and targeting

Output

• persisted TestimonialRequest rows with token, schedule, and campaign linkage

Owned models

• TestimonialCampaign, TestimonialCampaignProduct, TestimonialRequest

Plan refs

• 17, 18, 07, 20

---

M2) Request Delivery

Responsibility

• Send due requests via email/SMS.
• Track request lifecycle events and reminder sends.

Input

• due TestimonialRequest rows
• rendered template content
• provider credentials

Output

• provider dispatch + updated request status + TestimonialRequestEvent rows

Owned models

• TestimonialTemplate, TestimonialRequestEvent

Plan refs

• 16, 07, 13

---

M3) Public Submission Page

Responsibility

• Validate tokenized links.
• Capture testimonial payload and consent.
• Persist submission draft + media linkage.

Input

• submissionToken, user form data
• upload artifact references

Output

• TestimonialSubmission (pending/auto-approved path) + request marked submitted

Owned routes

• /t/:token, /api.testimonial-upload-url, /api.testimonial-submit

Plan refs

• 06, 08

---

M4) Media Ingestion/Processing

Responsibility

• Accept uploaded media references.
• Process/transcode and extract metadata.
• Update readiness state for moderation/storefront.

Input

• uploaded media asset row

Output

• TestimonialMediaAsset status transitions + metadata fields

Owned models

• TestimonialMediaAsset

Plan refs

• 06, 22, 20

---

M5) Moderation Queue

Responsibility

• Present pending content to merchants.
• Apply moderation decisions and merchandising edits.
• Record immutable audit logs.

Input

• TestimonialSubmission + media metadata

Output

• updated status, published, featured, sortOrder, moderation logs

Owned screens

• Screen 5, Screen 6, Screen 9

Plan refs

• 09, 10, 12, 08

---

M6) Storefront Widget Publication

Responsibility

• Expose approved/published data via public read API.
• Render home and PDP blocks in theme extension.

Input

• published testimonial dataset + placement config

Output

• storefront widget UI with proper filtering/sorting/fallback behavior

Owned screens/routes

• Screen 7, Screen 8/8.1, read API, theme blocks

Plan refs

• 11, 05

---

M7) Analytics/Billing

Responsibility

• Provide operational and ROI metrics.
• Track billable usage and overage conditions.

Input

• requests/events/submissions/media lifecycle data

Output

• dashboard KPIs, analytics charts, billing counters and alerts

Owned screens

• Screen 1, Screen 10, Screen 11, Screen 12

Plan refs

• 19, 13, 14, 15

---

3) Inter-module dependency graph

Execution order:

M1 Campaign Engine -> M2 Request Delivery -> M3 Public Submission -> M4 Media Processing -> M5 Moderation -> M6 Publication -> M7 Analytics/Billing

3.1 Hard dependencies

• M2 cannot operate without M1 request rows.
• M3 cannot operate without M1 tokenized request rows.
• M5 requires outputs from M3 + M4.
• M6 requires approved/published outputs from M5.
• M7 depends on all prior module events.

---

4) Shared cross-cutting concerns

These are not standalone modules but required in every module:

1. Tenant isolation
   • Every query filtered by shopId.
2. Idempotency
   • Webhook and worker safe retries.
3. Security/compliance
   • Token expiry, rate limits, GDPR webhook coverage.
4. Time semantics
   • UTC timestamps and buckets.
5. Observability
   • Correlated IDs in logs (shopId, campaignId, requestId, submissionId).

Reference plans: 08, 22, 24.

---

5) Module ownership matrix (routes/files)

Module	Primary files/routes
M1	webhooks.orders.*, app.testimonial-campaigns*
M2	cron sender route + template resolver + provider adapters
M3	t.$token, api.testimonial-upload-url, api.testimonial-submit
M4	api.testimonial-media-callback (optional) + worker files
M5	app.testimonial-submissions, app.testimonial-submission.$id, app.testimonial-moderation
M6	app.testimonial-published, app.testimonial-widget, storefront read API, theme extension blocks/assets
M7	app._index/dashboard, app.testimonial-requests, app.testimonial-analytics, app.testimonial-billing

Use 21 as the canonical route naming source.

---

6) Integration acceptance by module

M1 acceptance

• Active campaign + eligible order creates deterministic request rows.

M2 acceptance

• Due rows send once; retries do not duplicate final state.

M3 acceptance

• Valid token path submits; invalid/expired token blocked.

M4 acceptance

• Media transitions to ready with metadata.

M5 acceptance

• Merchant moderation actions persist and write audit logs.

M6 acceptance

• Storefront displays only approved+published+ready items by placement.

M7 acceptance

• KPI and billing screens reconcile with source records.

---

7) Suggested implementation order (module-first)

1. Foundation: schema + route scaffolding (20, 21)
2. M1 Campaign Engine
3. M2 Request Delivery
4. M3 Public Submission
5. M4 Media Processing
6. M5 Moderation Queue
7. M6 Storefront Publication
8. M7 Analytics/Billing
9. Cross-cutting hardening (08, 24)

---

8) Risks if module boundaries are ignored

1. Tight coupling between moderation and storefront queries can leak unpublished content.
2. Template logic duplicated across UI/worker can cause message drift.
3. Billing metrics derived from UI-only counters become untrustworthy.
4. Missing module ownership causes route naming inconsistency and regressions.

---

9) References

• 02-Implementation-Blueprint.md — Section 2.2
• 01-Post-Purchase-Video-Testimonial-Collector-Plan.md
• 20-database-design-and-migrations-blueprint-section-5.md
• 21-route-and-file-map-blueprint-section-6.md
• 22-integration-and-processing-plan-blueprint-section-7.md
• 23-release-plan-and-milestones-blueprint-section-9.md

---

10) Note on numbering

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