QR Code Generation: Technology Decision

Research & Decision Required

This document outlines the decision between QR Tiger API (cloud service) vs QRCoder (open-source library) for QR code generation in Epic 2.

Status: Pending decision before Epic 2 implementation

Options Overview

Option 1: QR Tiger API (Cloud Service)

What it is: Third-party cloud API for QR code generation

Pros:

✅ Managed service (no maintenance)
✅ Highly reliable and tested
✅ Professional support
✅ Guaranteed uptime and SLA
✅ Scalable without server resources

Cons:

❌ Ongoing API costs
❌ Rate limits based on plan
❌ External dependency (service could go down)
❌ Privacy concerns (sending data to third party)
❌ Requires API key management
❌ Network latency for API calls

Cost: Varies by plan (see QR Tiger pricing)

Documentation: QR Tiger API (Option 1)

Option 2: QRCoder (Open Source Library)

What it is: Open-source .NET library for generating QR codes

GitHub: https://github.com/Shane32/QRCoder

Pros:

✅ Zero cost (MIT license)
✅ No rate limits
✅ No external dependencies (self-hosted)
✅ Fast (no network calls)
✅ Privacy (data never leaves our servers)
✅ PNG format support (our required format)
✅ Full control over implementation
✅ Cross-platform (.NET 5+, .NET Framework 3.5+)
✅ Supports all error correction levels (L, M, Q, H)
✅ Active maintenance and community support

Cons:

❌ Community-maintained (not a commercial product)
❌ We're responsible for maintenance/updates
❌ No professional support or SLA
❌ Uses server CPU/memory resources
❌ Need to handle our own error scenarios

Cost: Free (MIT license)

Technical Specs:

Format: PNG only (our requirement)
Error Correction: L (7%), M (15%), Q (25%), H (30%)
.NET Support: .NET 5+, .NET Framework 3.5+, .NET Core 1.0+
Dependencies: Zero (beyond framework)
Cross-platform: Yes

Evaluation Questions

1. Technical Requirements

Q1.1: What QR code format do we need?

PNG only (for web display, download, and printing)

Current Answer: PNG only (500x500px) - No other formats needed

QRCoder Support: ✅ Yes - PngByteQRCode

Q1.2: What error correction level do we need?

L (7% damage tolerance)
M (15% damage tolerance)
Q (25% damage tolerance)
H (30% damage tolerance) - Recommended for printing

Current Answer: H (30%) for printing use cases

QRCoder Support: ✅ Yes - All levels (L, M, Q, H)

Q1.3: What QR code size do we need?

Fixed size (e.g., 500x500px)
Multiple sizes (responsive)
Custom sizes per use case

Current Answer: 500x500px minimum for printing

QRCoder Support: ✅ Yes - Configurable pixel size

Q1.4: Do we need any special QR features?

Current Answer: None for MVP

QRCoder Support: ⚠️ Partial - Basic generation only, no branding/analytics

2. Cost & Scale

Q2.1: What is our expected QR code generation volume?

Period	Estimated Volume	QR Tiger Cost	QRCoder Cost
Month 1	_____ QR codes	$_____	$0
Month 6	_____ QR codes	$_____	$0
Year 1	_____ QR codes	$_____	$0

Notes: Consider API tier limits and overage costs for QR Tiger

Q2.2: What is our budget for QR code generation?

Unlimited budget (cost not a concern)
Limited budget (need to minimize costs)
No budget (must be free)

Current Answer: _________________

Q2.3: Are we willing to pay for guaranteed uptime and SLA?

Yes - reliability is critical
No - we can handle occasional issues
Depends on cost vs risk

Current Answer: _________________

3. Performance & Reliability

Q3.1: What is acceptable QR generation time?

Less than 100ms (instant)
Less than 500ms (fast)
Less than 2 seconds (acceptable)
More than 2 seconds is ok

Performance Comparison:

QRCoder: ~10-50ms (local generation, no network)
QR Tiger API: ~1-2 seconds (includes network call + API processing)

Q3.2: How critical is QR code generation to our user flow?

Critical - Users can't proceed without QR code
Important - Users should get QR code but can work without it
Optional - Nice to have feature

Current Answer: Important (audio still works if QR fails)

Impact:

If critical → QRCoder (no external dependency)
If important/optional → Either option viable

Q3.3: Can we handle QR generation failures gracefully?

Yes - we can show audio without QR code
No - QR code is mandatory

Current Answer: Yes (Epic 1 works without QR codes)

4. Maintenance & Operations

Q4.1: Do we have .NET development expertise to maintain QRCoder?

Yes - we can update/debug library issues
No - prefer managed service

Current Answer: _________________

Q4.2: Are we comfortable with community-maintained libraries?

Yes - MIT license, active community is sufficient
No - prefer commercial support
Depends on library maturity

QRCoder Stats (as of 2025):

⭐ GitHub Stars: Check current count
🔧 Last Updated: Active (2025)
📦 NuGet Downloads: Check current count
📝 License: MIT
👥 Maintenance: Community + Shane32 (active maintainer)

Q4.3: What happens if QRCoder is abandoned?

We fork and maintain it ourselves
We migrate to another library
We switch to cloud service
This is acceptable risk

Current Answer: _________________

Q4.4: Can our servers handle QR generation load?

Yes - we have sufficient CPU/memory
No - prefer offloading to external service
Need to measure

Resource Requirements (QRCoder):

CPU: ~5-10ms per QR code
Memory: Minimal (less than 1MB per generation)
Disk: None (generated in memory)

5. Privacy & Security

Q5.1: Are we comfortable sending playback URLs to third-party API?

Yes - URLs are public anyway
No - prefer keeping all data in-house
Depends on data sensitivity

Data Shared with QR Tiger:

Playback URL (e.g., https://micdots.com/play/slug-123)
Generation timestamp (implicit)
API key (for authentication)

Q5.2: Do we have data residency or compliance requirements?

Yes - data must stay in our infrastructure
No - third-party services are acceptable
Unsure - need legal review

Current Answer: _________________

6. Future Requirements

Q6.1: Will we need QR code analytics in the future?

Yes - tracking scans is important
No - basic generation is sufficient
Maybe - not sure yet

Notes:

QR Tiger offers scan analytics (paid feature)
QRCoder has no built-in analytics (need custom tracking)

Q6.2: Will we need dynamic QR codes (changeable destinations)?

Yes - need to update where QR codes point
No - QR codes are permanent
Maybe - not sure yet

Notes:

QR Tiger supports dynamic QR codes
QRCoder generates static QR codes only

Q6.3: Will we need custom branding (colors, logos)?

Yes - brand consistency is important
No - standard black/white QR codes are fine
Maybe - future enhancement

Notes:

QR Tiger offers branded QR codes (paid feature)
QRCoder basic generation only (would need custom implementation)

Decision Matrix

Criteria	Weight	QR Tiger	QRCoder	Notes
Cost	High	⚠️ 3/10 (ongoing costs)	✅ 10/10 (free)	Budget impact
Performance	High	⚠️ 6/10 (1-2s latency)	✅ 10/10 (under 50ms)	User experience
Reliability	High	✅ 9/10 (SLA backed)	⚠️ 7/10 (self-managed)	Service quality
Privacy	Medium	⚠️ 6/10 (third party)	✅ 10/10 (in-house)	Data control
Maintenance	Medium	✅ 9/10 (managed)	⚠️ 6/10 (self-maintained)	Operational burden
Features	Low	✅ 8/10 (analytics, dynamic)	⚠️ 6/10 (basic only)	Future needs
Scalability	Medium	✅ 9/10 (automatic)	✅ 8/10 (server-dependent)	Growth handling

Scoring Guide: 1 (Poor) - 10 (Excellent)

Recommended Decision Framework

Choose QR Tiger API if:

✅ Budget allows for ongoing API costs
✅ Need guaranteed uptime with SLA
✅ Want professional support
✅ Need analytics or dynamic QR codes
✅ Prefer minimal maintenance burden
✅ Don't want to manage library updates

Choose QRCoder if:

✅ Zero cost is priority (no budget for API)
✅ Need fastest possible generation (under 50ms)
✅ Privacy/data residency is important
✅ Have .NET development expertise
✅ Comfortable with community libraries
✅ Only need basic QR code generation
✅ Want no external dependencies/rate limits

Implementation Comparison

QR Tiger Implementation Effort

Complexity: Medium

Steps:

Sign up for QR Tiger account
Configure API key in environment
Implement API client with retry logic
Download QR image from API
Upload to S3
Handle API errors and rate limits

Estimated Time: 2-3 days

QRCoder Implementation Effort

Complexity: Low-Medium

Steps:

Install QRCoder NuGet package
Generate QR code in memory (PngByteQRCode)
Upload byte array directly to S3
Handle generation errors

Estimated Time: 1-2 days

Sample Code:

using QRCoder;

// Generate QR code
var qrGenerator = new QRCodeGenerator();
var qrCodeData = qrGenerator.CreateQrCode(
    playbackUrl,
    QRCodeGenerator.ECCLevel.H
);

var qrCode = new PngByteQRCode(qrCodeData);
byte[] qrCodeBytes = qrCode.GetGraphic(20); // 20 pixels per module

// Upload directly to S3
await s3Client.PutObjectAsync(new PutObjectRequest
{
    BucketName = "micdots-qr",
    Key = $"{slug}.png",
    InputStream = new MemoryStream(qrCodeBytes),
    ContentType = "image/png"
});

Testing Considerations

QR Tiger Testing

QRCoder Testing

QR code scannability (iOS/Android)
Error correction effectiveness
Image quality at various sizes
Memory usage under load
Concurrent generation performance

Risk Analysis

QR Tiger Risks

Risk	Likelihood	Impact	Mitigation
Service downtime	Low	Medium	Graceful degradation (show audio without QR)
Cost overruns	Medium	High	Monitor usage, set alerts
Rate limit hit	Medium	Medium	Implement queuing/retry
API deprecation	Low	High	Have backup plan
Vendor lock-in	Medium	Medium	Abstract QR generation interface

QRCoder Risks

Risk	Likelihood	Impact	Mitigation
Library abandonment	Low	Medium	Fork repo, maintain ourselves
Bugs/vulnerabilities	Low	Medium	Monitor GitHub issues, test thoroughly
Performance issues at scale	Low	Medium	Load testing, caching
Missing features	Medium	Low	Custom implementation or switch later
.NET compatibility	Very Low	High	Test across target frameworks

Hybrid Approach

Option 3: Start with QRCoder, fallback to QR Tiger

Strategy:

Implement QRCoder for Epic 2 (fast, free)
Abstract QR generation behind interface
If issues arise, swap to QR Tiger without code changes
Monitor performance and reliability in production

Benefits:

✅ Start with zero cost
✅ Easy to switch if needed
✅ Best of both worlds

Implementation:

public interface IQRCodeGenerator
{
    Task<byte[]> GenerateQRCodeAsync(string url);
}

public class QRCoderGenerator : IQRCodeGenerator { }
public class QRTigerGenerator : IQRCodeGenerator { }

// Easy to swap in DI container
services.AddSingleton<IQRCodeGenerator, QRCoderGenerator>();

Next Steps

Answer evaluation questions above
Fill in decision matrix with weighted scores
Discuss with team - development, product, finance
Make decision and document rationale
Update Epic 2 documentation with chosen approach
Implement POC with selected option
Test thoroughly before Epic 2 launch

Decision Record

Date: _________________

Decision:

Use QR Tiger API
Use QRCoder
Use Hybrid Approach (QRCoder with QR Tiger fallback)

Rationale:

Decided By: _________________

Stakeholders: _________________

Options Overview​

Option 1: QR Tiger API (Cloud Service)​

Option 2: QRCoder (Open Source Library)​

Evaluation Questions​

1. Technical Requirements​

2. Cost & Scale​

3. Performance & Reliability​

4. Maintenance & Operations​

5. Privacy & Security​

6. Future Requirements​

Decision Matrix​

Recommended Decision Framework​

Choose QR Tiger API if:​

Choose QRCoder if:​

Implementation Comparison​

QR Tiger Implementation Effort​

QRCoder Implementation Effort​

Testing Considerations​

QR Tiger Testing​

QRCoder Testing​

Risk Analysis​

QR Tiger Risks​

QRCoder Risks​

Hybrid Approach​

Next Steps​

Decision Record​

Related Documentation​

Options Overview

Option 1: QR Tiger API (Cloud Service)

Option 2: QRCoder (Open Source Library)

Evaluation Questions

1. Technical Requirements

2. Cost & Scale

3. Performance & Reliability

4. Maintenance & Operations

5. Privacy & Security

6. Future Requirements

Decision Matrix

Recommended Decision Framework

Choose QR Tiger API if:

Choose QRCoder if:

Implementation Comparison

QR Tiger Implementation Effort

QRCoder Implementation Effort

Testing Considerations

QR Tiger Testing

QRCoder Testing

Risk Analysis

QR Tiger Risks

QRCoder Risks

Hybrid Approach

Next Steps

Decision Record

Related Documentation