Epic 2 - QR Code Generation [TBD]

To Be Done

Epic 2 implements QR code generation to complement the audio generation from Epic 1.

Objective

Add QR code generation to existing audio generations, enabling physical distribution of audio content.

User Flow:

Existing Audio → Generate QR Code → Download QR Image → Print & Distribute

What You Get:

• QR code image (PNG) linked to audio playback URL
• High-quality, scannable QR codes
• QR code download functionality
• Ability to print and distribute QR codes physically

Building on Epic 1

Epic 2 adds QR code generation to the audio generation system built in Epic 1. Users will be able to generate QR codes for their audio content.

---

Priorities Covered

• P2: QR Code Generation (QR Tiger API)

Prerequisites from Epic 1:

• Audio generation working (P1)
• AWS S3 storage configured (P3)
• User interface operational (P4)

---

What Changes

Result Page Updates

Add QR Code Card:

• Display generated QR code image
• Download QR code button
• Scanning instructions
• QR code dimensions and format info

Update API Response:

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "slug": "happy-birthday-john",
    "audioUrl": "https://s3.amazonaws.com/micdots/audio/550e8400.mp3",
    "playbackUrl": "https://micdots.com/play/happy-birthday-john",
    "qrCodeUrl": "https://qrtiger.com/qr/550e8400.png",
    "createdAt": "2024-11-02T12:00:00Z"
  }
}

New Field:

• qrCodeUrl - URL to downloadable QR code PNG image

---

Technical Details

QR Generation Technology - Decision Pending

Before implementing Epic 2, we need to decide between QR Tiger API (cloud service with costs) vs QRCoder (free open-source library).

See QR Generation Research & Decision for evaluation questions and comparison.

Implementation Options

• Option 1: QR Tiger API Documentation - Cloud service
• Option 2: QRCoder (open-source) - Details in research document
• Option 3: Hybrid approach (start with QRCoder, fallback to QR Tiger)

Data Storage Updates

Add new field to generation records:

• QR Code URL: S3 URL to QR code image (not QR Tiger direct URL)

Example QR Code URL: https://s3.amazonaws.com/micdots-qr/welcome-audio-123456789.png

API Flow Overview

Flow Highlights:

• Blue section: Epic 1 audio generation (unchanged)
• Red section: Epic 2 QR code additions

QR Tiger Integration Summary

API Endpoint: POST https://api.qrtiger.com/v1/qr

Basic Request:

{
  "url": "https://micdots.com/play/welcome-audio-123456789",
  "size": 500,
  "format": "png",
  "errorCorrection": "H"
}

Process:

1. Generate QR code via QR Tiger API
2. Download QR image from QR Tiger
3. Upload QR image to S3 (micdots-qr bucket)
4. Store S3 URL in database

For complete API documentation, request/response examples, error handling, and integration code, see QR Tiger API Technical Details.

---

Success Criteria

Epic 2 is complete when:

1. ✅ QR codes are generated for each audio
2. ✅ QR codes link to correct playback URL
3. ✅ QR code images are downloadable
4. ✅ QR codes scan correctly on mobile devices
5. ✅ QR codes are displayed on result page
6. ✅ QR code download button works
7. ✅ Manual testing completed and verified
8. ✅ Deployed to production

---

Timeline

Duration: 3 weeks

Weeks	Focus	Deliverables
Week 11	QR Tiger API Integration	QR code generation working
Week 12	UI Updates	QR code display on result page
Week 13	Testing & Deployment	QR code download and validation

---

QR Code Specifications

Technical Requirements

• Size: 500x500px minimum for printing
• Format: PNG with transparent background
• Error Correction: High (30% damage tolerance)
• Content: Playback URL (e.g., https://micdots.com/play/happy-birthday-john)

Use Cases

Physical Distribution:

• Print on menus (restaurants)
• Add to posters and signage
• Include on business cards
• Place on product packaging
• Print on table tents
• Add to marketing materials

Digital Distribution:

• Share QR code image via email
• Include in PDF documents
• Add to presentations
• Share on social media
• Embed in websites

---

Related Documentation

UI & Pages

• Result Page (Epic 2) - Updated UI with QR code display and download
• QR Playback Page - Public page users see when scanning QR codes

Technical Details

• QR Generation Research & Decision - Evaluate QR Tiger vs QRCoder
• QR Tiger API Documentation - Complete QR Tiger API implementation (Option 1)
• Text-to-Speech API - Epic 1 API that's extended in Epic 2

General

• Epic 1 Overview - Prerequisites and audio generation
• MVP Priorities - P2 QR Code Generation details
• System Architecture - Complete architecture