Skip to main content

🚀 DPPS Quick Start Guide

Goal: Ship a working Digital Product Publishing System in ≤ 2 weeks

✅ What Already Exists (Foundation Validated)​

Backend (Java/Spring)​

  • ✅ Product, Invoice, LineItem — ThorAPI-generated models
  • ✅ DigitalAsset, DownloadAccess, FileRecord — Digital fulfillment entities
  • ✅ DigitalFulfillmentService — ACL-based download grants + signed URLs
  • ✅ FileController — Multipart uploads (/files/uploads/init, /files/uploads/complete)
  • ✅ StripeCheckoutModule, StripeWebhookModule — Payment integration
  • ✅ ProductFunnelWizard — Funnel generation workflow
  • ✅ AclService — Permission management (/v1/auth/acl/grant, /v1/auth/acl/revoke)

Frontend (React/TypeScript)​

  • ✅ RTK Query services — Auto-generated for all entities
  • ✅ FileUploadSession — Upload state management
  • ✅ ProductFunnelWizard — Funnel creation hooks

🎯 What Needs to Be Built (6 Key Pieces)​

1. OpenAPI Schema Enhancement (30 min)​

Add missing fields to Product schema for digital delivery:

# Add to valkyrai/src/main/resources/openapi/api.hbs.yaml
Product:
  properties:
    contentDataId: # Link to uploaded file
      type: string
      format: uuid
    deliveryMode: # NEW: Digital vs Physical
      type: string
      enum: [DIGITAL_DOWNLOAD, STREAMING, LICENSE_KEY, PHYSICAL]
      default: DIGITAL_DOWNLOAD
    maxDownloads: # NEW: Download limits
      type: integer
    expiresAfterDays: # NEW: Entitlement expiry
      type: integer

Action: Regenerate ThorAPI models after adding these fields.

2. Backend: DPPS Orchestration Service (2 hours)​

File: valkyrai/src/main/java/com/valkyrlabs/valkyrai/service/DppsOrchestrationService.java

Purpose: Coordinates Upload → Product → Funnel → Checkout flow

Key Methods:

public Product createProductFromUpload(UUID fileRecordId, CreateProductRequest request)
public ProductFunnelWizard publishProduct(UUID productId, PublishRequest request)

Dependencies:

  • FileRecordService (existing)
  • DigitalAssetService (existing)
  • ProductService (existing)
  • ProductFunnelWizardService (existing)
  • AclService (existing)

Action: Copy implementation from DPPS_IMPLEMENTATION_PLAN.md Phase 2.2

3. Backend: Purchase Fulfillment Workflow (3 hours)​

File: valkyrai/src/main/java/com/valkyrlabs/workflow/definitions/DppsPurchaseFulfillmentWorkflow.java

Purpose: Auto-register workflow that fires on payment success

Tasks:

  1. VerifyPayment (StripeWebhookModule)
  2. GrantAccess (DigitalFulfillmentModule — wrapper around existing DigitalFulfillmentService)
  3. NotifyBuyer (MailtrapSendModule)
  4. PostPurchase (optional: Slack, CRM webhook)

Action: Copy implementation from DPPS_IMPLEMENTATION_PLAN.md Phase 2.3

4. Backend: Download Endpoint with Signed URLs (2 hours)​

File: valkyrai/src/main/java/com/valkyrlabs/valkyrai/controller/DownloadController.java

Endpoint: GET /v1/download/{downloadAccessId}?validityMinutes=15

Logic:

  1. Verify ACL READ permission
  2. Check DownloadAccess status (ACTIVE, not expired)
  3. Enforce max downloads limit
  4. Generate signed URL via DigitalFulfillmentService
  5. Increment download counter

Security: Uses existing Spring ACL @PreAuthorize on DownloadAccess entity

Action: Copy implementation from DPPS_IMPLEMENTATION_PLAN.md Phase 2.5

5. Frontend: DPPS Wizard Component (4 hours)​

Files:

  • web/typescript/valkyr_labs_com/src/components/dpps/FileUploader.tsx
  • web/typescript/valkyr_labs_com/src/components/dpps/ProductForm.tsx
  • web/typescript/valkyr_labs_com/src/components/dpps/PublishProduct.tsx
  • web/typescript/valkyr_labs_com/src/pages/DppsWizard.tsx

Flow:

Upload File → Create Product (Draft) → Configure Funnel → Publish → Get Landing Page URL

Key Hooks:

  • usePostFileUploadSessionMutation() — Upload
  • useCreateProductMutation() — Product creation
  • useStartFunnelWizardMutation() — Funnel generation
  • usePublishFunnelMutation() — Publish funnel

Action: Copy implementations from DPPS_IMPLEMENTATION_PLAN.md Phase 3

6. Email Template (30 min)​

File: valkyrai/src/main/resources/db/migration/V999__dpps_email_templates.sql

INSERT INTO email_template (id, template_name, subject, body_html, category)
VALUES (
  gen_random_uuid(),
  'dpps_download_ready',
  'Your download is ready: {{productTitle}}',
  '<html>...</html>',
  'FULFILLMENT'
);

Action: Run migration after implementation

📝 Step-by-Step Implementation (Day-by-Day)​

Day 1: Backend Foundation​

  1. ✅ Validate existing entities (DigitalAsset, DownloadAccess)
  2. 🔧 Enhance Product schema (OpenAPI)
  3. 🔧 Regenerate ThorAPI models (mvn clean install in thorapi, then valkyrai)
  4. 🔧 Implement DppsOrchestrationService
  5. 🧪 Unit tests for orchestration service

Day 2: Workflow & Fulfillment​

  1. 🔧 Implement DppsPurchaseFulfillmentWorkflow
  2. 🔧 Implement DigitalFulfillmentModule (ExecModule wrapper)
  3. 🔧 Implement DownloadController with signed URLs
  4. 🧪 Integration test (upload → product → mock payment → download)

Day 3-4: Frontend Components​

  1. 🔧 Build FileUploader component (drag-drop + resumable)
  2. 🔧 Build ProductForm (Formik + validation)
  3. 🔧 Build PublishProduct component
  4. 🔧 Wire up DppsWizard orchestration page
  5. 🧪 End-to-end frontend test

Day 5: Integration & Testing​

  1. 🔧 Create email template + migration
  2. 🔧 Test full flow: Upload → Product → Funnel → Stripe (test mode) → Download
  3. 🔧 Fix ACL permission issues
  4. 🔧 Add Grafana dashboard for metrics

Day 6-7: Polish & Beta Launch​

  1. 🔧 Admin panel: Orders, Entitlements, Revoke access
  2. 🔧 Error handling + user-friendly messages
  3. 🔧 Documentation (API docs, user guide)
  4. 🚀 Deploy to staging
  5. 🚀 Internal dogfood (3 test products)

🧪 Testing Checklist​

Unit Tests​

  • DppsOrchestrationService.createProductFromUpload()
  • DppsOrchestrationService.publishProduct()
  • DownloadController.getDownloadUrl() (ACL checks)

Integration Tests​

  • Full flow: Upload → Product → Funnel → Payment → Download
  • ACL permissions: Creator vs Buyer vs Admin
  • Download limits enforcement
  • Expiry date handling

E2E Tests​

  • Upload 100MB file (resume on failure)
  • Stripe test mode payment
  • Email delivery (Mailtrap)
  • Download link redemption (TTL validation)

🚀 Deployment Checklist​

Environment Variables​

# Required
STRIPE_SECRET_KEY=sk_test_...
MAILTRAP_API_KEY=...
FILE_STORAGE_DRIVER=s3  # or 'local' for dev

# Optional
STRIPE_WEBHOOK_SECRET=whsec_...
AWS_S3_BUCKET=valkyr-digital-assets
AWS_REGION=us-east-1

Database Migrations​

cd valkyrai
mvn flyway:migrate

Rebuild & Deploy​

cd thorapi
mvn clean install
cd ../valkyrai
mvn clean package
make harness-up  # Docker local dev

📊 Success Metrics (Week 1)​

  • 3 internal products created successfully
  • TTFP (Time-to-First-Product) < 60 seconds
  • Upload success rate > 95%
  • Download link redemption rate 100%
  • Zero ACL permission errors in staging logs

🆘 Troubleshooting​

"FileRecord not found"​

  • Check FileUploadSession.completedAt is set
  • Verify file completed multipart upload
  • Check FileRecord.status = AVAILABLE

"Entitlement not found"​

  • Verify payment success webhook fired
  • Check DownloadAccess table for buyer principal ID
  • Inspect workflow execution logs (Workflow.status)

"Permission denied"​

  • Check ACL grants: SELECT * FROM acl_entry WHERE object_id_identity = '<productId>';
  • Verify buyer's Principal exists in system
  • Test with admin role: ROLE_ADMIN bypasses ACL
  • Default TTL is 15 minutes
  • Check DownloadAccess.expiresAt timestamp
  • Regenerate link via /v1/download/{id} endpoint

🎓 Next Steps After MVP​

Phase 2 Features​

  • Multi-file products (zip on demand with FileZipModule)
  • License key generation (add LicenseModule)
  • Shopify payment bridge (via RestApiModule)
  • Coupon codes (add Discount entity integration)
  • Guest checkout (auto-create Principal on payment success)

Phase 3 Features​

  • Subscription products (recurring payments)
  • Streaming delivery (HLS/DASH)
  • Webhook notifications (Zapier, Make)
  • Affiliate tracking (referral links)
  • Analytics dashboard (purchase funnel, conversion rates)

📚 Reference Documentation​

  • Full Implementation Plan: DPPS_IMPLEMENTATION_PLAN.md
  • PRD: Original requirement doc (Section 1-26)
  • Existing Services: DigitalFulfillmentService.java (reference implementation)
  • Frontend Patterns: ValorIDE_docs/techContext.md
  • ACL Guide: web/src/main/resources/templates/typescript-redux-query/README.ACL.md

✅ Definition of Done​

  • All acceptance criteria from PRD pass in staging
  • No mocks remain; all generated services used
  • Observability dashboards deployed (Grafana)
  • Security review signed off (ACL tests, link TTL, revocation)
  • Runbooks updated for Support & Ops
  • 3 internal products successfully published and purchased

Estimated Total Time: 40-50 hours (1-2 weeks for solo developer)

Ready to start? Begin with Day 1, Step 2 (OpenAPI schema enhancement).

Run: code valkyrai/src/main/resources/openapi/api.hbs.yaml