Refract — Private Media Library

---

title: "Refract — Private Media Library" client: "Ramiro Labs" category: "Full-stack MVP" date: "2026-02-01" outcome_metric: "200K+ media items per user — zero cloud storage cost" description: "Designed and built a full-stack SaaS media player that lets users rediscover their photo and video collections from Google Drive and Dropbox — without uploading a single byte to a third-party server." tech_stack:

• React
• TypeScript
• Node.js
• PostgreSQL
• Prisma
• Stripe
• Google Drive API
• Dropbox OAuth
• Google Gemini
• UploadThing
• Vercel live_url: "https://userefract.com" cover_image: "/case-studies/case-study-3/cover.png" isFeatured: true featured_order: 5

---

Problem

Most people have years of photos and videos scattered across Google Drive, Dropbox, and old hard drives — and almost never look at them. The existing tools either require uploading everything to another service (a privacy tradeoff most people quietly resent), or they live inside the cloud provider's own mediocre interface.

There was a gap: a genuinely good media browser that works across sources, surfaces random memories through shuffle playback, and never touches your actual files server-side.

The additional constraint that shaped the entire architecture: users had to be able to trust it with personal photos. That meant the server could never store media content — only the lightweight metadata needed to find and play files from their original location.

Approach

The core architecture decision — metadata-only server storage — drove everything else. The server stores file IDs, names, MIME types, and thumbnail URLs. The actual photos and videos stay in Google Drive, Dropbox, or the user's device. Playback fetches directly from the original source on demand.

For large libraries (up to 200,000 items on the Power tier), a three-tier metadata storage system keeps reads fast without database queries per request: a hot index in Vercel KV for small lookups, gzip-compressed JSON chunks in Vercel Blob for bulk data, and a local filesystem fallback in development.

The shuffle player is the heart of the product — a full-screen, distraction-free viewer with configurable intervals and auto-hiding controls. AI-powered search (Google Gemini 2.0 Flash) lets users run natural language queries like "sunset at the beach" and surfaces results by expanding the query into visual keywords matched against indexed metadata, with results cached in IndexedDB to minimize API costs.

Subscription tiers (Free → Pro at $4.99/mo early adopter → Power at $19.99/mo) are managed through Stripe with a customer portal, usage metering, and promotional code support.

Outcome

Refract supports libraries up to 200,000 media items at the top tier while maintaining zero server-side media storage — the core privacy promise holds at every scale point. The AI search system generates 5–10 visual keyword tags per query and returns results in under two seconds on a warm cache.

The tiered subscription model with an early-adopter pricing lock ($4.99/mo for the first 200 Pro subscribers) creates a direct path to initial revenue while the user base grows.

Technical highlights

• Privacy by design: metadata-only architecture — no media bytes ever stored server-side
• AI search: Gemini 2.0 Flash tag expansion with IndexedDB caching
• Multi-source: Google Drive (OAuth), Dropbox (PKCE), and direct uploads via UploadThing
• HEIC/HEIF support: progressive loading via Web Worker (thumbnail → full resolution)
• Scale: 3-tier storage (Vercel KV hot index → Blob chunks → /tmp) handles 200K items without per-request DB queries