Skip to main content

ADR-001: QR Code Download Feature using Supabase

Status: Superseded by Amendment 2026-03-08

Context​

The project requires a new feature for the "next stage" of development. After a user takes photos using the photobooth, the final image (soft file) should be uploaded to a cloud service. The user should then be presented with a QR code on-screen, which they can scan with their mobile device to download the image.

A key business requirement is to keep recurring operational costs, specifically for file storage and downloads, as close to zero as possible.

Decision​

We will use Supabase to implement this feature. The initial architecture will be a client-side upload model:

  1. The Next.js frontend application will handle the image upload directly to Supabase Storage.
  2. Supabase Storage will be configured to provide a public URL for the uploaded image.
  3. The frontend will use this public URL to generate and display the QR code.
  4. A public-read bucket named photobooth-images will be used.

Consequences​

Positive​

  • Excellent Developer Experience: Supabase offers an integrated suite of tools (Storage, Database, Auth) that simplifies development and project management.
  • Rapid Implementation: Using the supabase-js client library allows for quick integration with the existing Next.js frontend.
  • Low Initial Cost: The Supabase free tier is sufficient to launch and operate the feature with no initial cost, provided usage stays within the defined limits.
  • Scalable Architecture: While we are starting with a simple client-side upload, Supabase provides paths to more advanced, secure-by-default architectures (e.g., using Edge Functions or a dedicated backend with signed URLs) if needed in the future.

Negative & Risks​

  • Bandwidth Cost Risk: This is the most significant risk. The Supabase free tier includes 2 GB of egress (downloads) per month. If total user downloads exceed this limit, the project will incur costs ($0.09/GB). For a high-traffic event or a successful business, this limit could be reached, compromising the "zero cost" goal.
  • Storage Limit: The free tier includes 1 GB of storage. While more constrained than alternatives, this is still sufficient for thousands of photos.
  • Go Backend Complexity: A stated preference for a Go backend cannot be met directly within the integrated Supabase ecosystem, as Supabase Edge Functions are TypeScript/JavaScript-based. Implementing a Go backend would require hosting it as a separate service, which adds architectural complexity and another potential point of cost.

Throughput & Performance Analysis​

A performance analysis was conducted to assess the limitations of this approach:

  1. Primary Bottleneck: The end-user's local network connection (i.e., the event's Wi-Fi) will be the primary limiter on upload speed for any single photobooth session.
  2. Service Throughput: Supabase's API and Storage infrastructure are built to handle high concurrency and are not expected to be a bottleneck for this use case. API rate limits are generous and unlikely to be hit.
  3. Volume, not Throughput: The most critical limitation is the monthly download volume (2 GB/month on the free tier), not the simultaneous request speed.

Alternatives Considered​

Cloudflare R2 + Workers​

This was the primary alternative considered and remains a highly viable option.

  • Pros:
    • No Egress Fees: Cloudflare R2 offers unlimited, free egress. This completely eliminates the risk of incurring costs from user downloads, perfectly aligning with the "zero cost" goal.
    • Generous Free Tier: The free tier includes 10 GB of storage and millions of Worker invocations per month.
  • Cons:
    • Less Integrated: While extremely powerful, it doesn't offer the same "all-in-one" database/auth/storage dashboard experience as Supabase out-of-the-box.

Amendment 2026-03-08: Pivot to Cloudflare R2​

Status: Accepted

Rationale​

During the finalization of the Phase 3 Architecture (documented in ADR-008), it was determined that the 2.0 GB monthly egress limit on Supabase's free tier posed a high operational risk for events. To ensure a strictly "Zero Egress Cost" model, we decided to pivot to Cloudflare R2.

Changes​

  1. Storage: Replaced Supabase Storage with Cloudflare R2 buckets.
  2. Cost Model: Zero bandwidth fees regardless of download volume.
  3. Unified Stack: Integrated with existing Cloudflare Workers/D1 infrastructure, moving away from the Supabase ecosystem.