Vercel API Routes & Auth Bouncer

Relevant source files

The following files were used as context for generating this wiki page:

• GEMINI.md
• CLAUDE.md
• README.md
• conductor/tracks.md
• web/app/admin/dashboards/page.tsx
• web/middleware.ts
• web/app/api/analyses/route.ts

Introduction

The "Vercel API Routes & Auth Bouncer" represents the high-security gateway and orchestration layer of the hex-yt-intel platform. Operating within the Vercel Serverless environment, this system is responsible for high-security authentication, atomic quota enforcement, and initial request handling before offloading long-running synthesis tasks to the Cloudflare Streaming Engine.

The "Bouncer" pattern ensures that all requests are validated via Supabase Auth and checked against usage limits (using Upstash Redis) within a tight execution window (approximately 8 seconds). This architecture allows the platform to maintain a secure perimeter while providing a seamless transition to the high-latency LLM synthesis processes handled by the edge worker.
Sources: README.md:21-25, CLAUDE.md:14-17

Hybrid Edge Architecture

The platform implements a multi-cloud hybrid flow known as the Hybrid Edge Symphony (ADR 005). This architecture splits responsibilities between Vercel and Cloudflare to optimize for security and execution time limits.

Architectural Breakdown

• Vercel (The Bouncer): Handles authentication, quota enforcement via Upstash Redis, and initial metadata lookups.
• Cloudflare (The Streamer): Handles high-latency LLM synthesis and Server-Sent Events (SSE) streaming for durations up to 58-90 seconds.
• HMAC Persistence: Ensures data integrity during server-to-server (S2S) writes back to the database.

Sources: README.md:21-25, CLAUDE.md:14-17, GEMINI.md:139-143

Request Lifecycle Flow

The following diagram illustrates the lifecycle of a synthesis request as it passes through the Vercel Bouncer to the Cloudflare Worker.

The diagram shows the dual-path logic: an instant return on cache hits and the bouncer-to-streamer handoff on cache misses.
Sources: GEMINI.md:112-115, GEMINI.md:139-143, CLAUDE.md:14-17

Authentication & Security Protocols

Auth Bouncer Logic

The system enforces a strict authentication pattern using Supabase Auth. Server-side operations must use the getSupabaseClientWithAuth() pattern to ensure request-scoped isolation. The Vercel middleware and route handlers act as a "Bouncer," rejecting unauthenticated requests before they reach expensive LLM processing logic.
Sources: GEMINI.md:41-43, GEMINI.md:195-197

Cryptographic Signatures (HMAC)

To prevent unauthorized database writes and tampering during the handoff between Vercel and Cloudflare, the system utilizes HMAC signatures:

• StreamToken: Vercel signs a token that the user presents to Cloudflare.
• ContentSignature: The Cloudflare Worker signs its output, which the Vercel /persist endpoint verifies before updating the Supabase database.

Sources: README.md:25, conductor/tracks.md:23-26

Security Configuration Table

Component	Security Mechanism	Purpose
API Routes	getSupabaseClientWithAuth()	Server-side identity verification
Quota Management	Upstash Redis Lua Scripts	Atomic enforcement of user limits
Edge Handoff	HMAC SHA-256	Validating cross-cloud requests
Persistence	S2S /persist Endpoint	Secure DB updates from workers

Sources: GEMINI.md:41-43, CLAUDE.md:27-28, README.md:25

API Route Implementation

Route Handler Requirements

All analytical route handlers in Vercel MUST implement specific behaviors to remain compatible with the Hybrid Edge Symphony:

1. Response Streaming: Routes must use chunked response streaming to extend connection lifetimes beyond the standard 10-second Vercel limit, aiming for a 25-second window.
2. Stratified Timeouts: Handlers utilize a 3-second connection handshake timeout and a 25-second token streaming window.
3. Cache-First Logic: Before initiating any analysis, routes must query the analyses table for a video_id and user_id match.

Sources: GEMINI.md:112-125, CLAUDE.md:8-13

Observability and Health

The admin dashboard provides real-time monitoring of the API infrastructure, tracking latency and component status.

The monitoring system tracks connectivity and latency across the triple-cloud infrastructure (Vercel, Cloudflare, Supabase).
Sources: web/app/admin/dashboards/page.tsx:85-115

Key API Endpoint Parameters

Endpoint	Method	Parameter	Description
/api/analyses	POST	video_id	The YouTube video identifier to synthesize.
/api/analyses	POST	user_id	The authenticated user's ID for quota tracking.
/api/analyses/persist	POST	ContentSignature	HMAC signature required for S2S persistence.
/api/health	GET	N/A	Returns status of DB, Worker, and Sentry.

Sources: GEMINI.md:112-115, conductor/tracks.md:26, web/app/admin/dashboards/page.tsx:88

Conclusion

The Vercel API Routes & Auth Bouncer system provides a robust security perimeter and orchestration layer for the hex-yt-intel platform. By combining Supabase Auth, Upstash-based atomic quotas, and HMAC-signed handoffs, the system effectively manages the transition from Vercel's secure environment to Cloudflare's high-performance streaming edge, ensuring that deep UCIS v5.1 analyses are delivered reliably and securely.
Sources: README.md:21-26, CLAUDE.md:14-17