Yoink — Architecture and Execution

Yoink is a multi-service platform for authenticated social video extraction and download. It combines a browser extension, a web dashboard, a backend control plane, and Lambda-based execution for heavy media work.

Supported targets include YouTube, LinkedIn, X/Twitter, Instagram, Threads, Pinterest, and Facebook. The core focus is reliability under changing platform behavior, strict auth boundaries, and measurable operations.

Why This Exists

Most media download tooling breaks at scale because it mixes extraction logic, auth, billing, and user state in a single runtime. Yoink separates these concerns:

• Extension UX for in-context user actions.
• Web dashboard for account, billing, and analytics.
• Backend as the single source of truth for auth, plans, limits, and writes.
• Lambda workers for metadata extraction and streamed downloads.

This design keeps the fast path fast while preserving strong governance over usage and subscription enforcement.

Service Architecture

Yoink is implemented as four explicit service surfaces:

1. yoink-extension (WXT): detects media context and triggers options/download calls.
2. yoink-web (Next.js): dashboard/admin UX with authenticated backend proxy.
3. yoink-backend (NestJS): auth, key/device management, billing lifecycle, analytics, and data persistence.
4. yoink-lambdas (Go + Lambda Function URL): yt-dlp/ffmpeg execution with response streaming.

The backend owns all persistent business state in PostgreSQL. Lambda intentionally has no direct DB access and writes through internal backend APIs.

Trust Boundaries and Security Model

Yoink enforces three distinct auth modes:

• API key mode (X-API-Key) for extension-driven flows.
• Web service-token mode (Bearer BACKEND_SERVICE_TOKEN + X-User-*) for dashboard proxy traffic.
• Lambda internal mode (Bearer BACKEND_SERVICE_TOKEN) for internal authorize/log/start/complete/fail operations.

For browser-managed downloads, the extension uses short-lived signed download tickets:

1. Extension requests POST /api/auth/download-ticket from backend.
2. Browser calls Lambda GET /download?downloadTicket=....
3. Lambda exchanges ticket through backend internal API before authorizing execution.

This avoids exposing long-lived API keys in URL query strings while preserving native browser download UX.

End-to-End Data Flows

1) Extension options flow (Lambda execution)

• Extension calls Lambda /options.
• Lambda calls backend internal /api/internal/authorize.
• Backend validates plan/rate/monthly limits and updates key activity.
• Lambda extracts formats and logs usage asynchronously via backend internal API.

2) Extension download flow (ticket + streaming)

• Extension mints a short-lived download ticket.
• Lambda validates ticket by internal exchange.
• Backend creates download_history start record.
• Lambda runs extraction/download and streams bytes to browser.
• Completion/failure is posted asynchronously and persisted.

3) Web dashboard flow (no Lambda requirement)

• Web proxy forwards authenticated requests to backend with service token.
• Backend serves account/bootstrap/key management from PostgreSQL.
• Web download endpoints can execute direct backend download path where needed.

Data Model and Persistence

The PostgreSQL schema is designed around explicit ownership and lifecycle writes:

• Identity & access: users, api_keys, device_bindings
• Execution telemetry: usage_logs, download_history, extension_installations
• Billing lifecycle: user_subscriptions, billing_coupons, billing_coupon_redemptions

Key implementation choice: backend is the single writer for persistent business data, including events initiated by Lambda.

This keeps consistency guarantees centralized and makes admin analytics queries predictable.

API Surfaces

Public backend surfaces include health, auth validation, options/download, user/key management, billing, and telemetry. Internal backend surfaces power Lambda authorization and download lifecycle callbacks.

The web app exposes a constrained proxy (/api/backend/[...path]) that:

• injects service token + user context headers,
• blocks non-admin internal paths,
• streams backend responses (including download payloads).

This keeps browser clients out of direct backend-secret management.

Operations and Reliability

Operationally, Yoink runs with clear service contracts:

• Local port map: extension 3000, web 3001, backend 3002, lambdas 3003
• Shared critical secret alignment: BACKEND_SERVICE_TOKEN
• Signed ticket secret and TTL enforcement: DOWNLOAD_TICKET_SECRET
• Neon strategy split: pooled DB URL for runtime, unpooled for migrations

Runbook triage explicitly covers failure modes like stale key deactivation, ticket expiry, monthly limit violations, and stuck download_history records.

What Makes This Interesting

• Separation of control plane and execution plane keeps data integrity and compute flexibility.
• Ticket-based browser download flow improves key hygiene without hurting UX.
• Single-writer backend model simplifies auditing, analytics, and billing state transitions.
• Extension install/version telemetry gives operational visibility into live client distribution.

Current Status

Yoink is in active development, with production architecture already aligned around explicit trust boundaries, internal service contracts, and measurable lifecycle telemetry.

• Live: yoink.piyushgambhir.com