Edge Request Proxy & Routing
Relevant source files
The following files were used as context for generating this wiki page:
KudosWall utilizes a high-performance Edge Request Proxy system to manage testimonial sharing, media delivery, and custom domain routing. Built on Next.js 16 and optimized for serverless environments, this system ensures zero-latency requests by routing traffic through a lightweight edge handler. The architecture is specifically designed to bridge raw web speed with enterprise-grade reliability, utilizing edge-compatible proxies for optimized execution on Cloudflare.
The routing system handles public-facing testimonial pages, collection campaigns, and secure media streams. It integrates directly with the platform's billing state to enforce plan-gated features, such as video playback and white-labeling, at the edge before assets are served to the visitor.
Sources: README.md:14-18, README.md:46-47, AGENTS.md:57-59
Core Architecture & Execution
The edge routing logic is centralized in src/proxy.ts (referenced as the primary handler). For Next.js 16 compatibility and stable execution on Cloudflare, the project explicitly avoids standard middleware.ts in favor of this edge proxy handler. This component serves as the gateway for all visitor-facing requests, specifically handling the /t/:testimonialId and /collect/:slug patterns.
Request Flow Overview
When a visitor accesses a testimonial or collection page, the request is processed through the following sequence:
The diagram shows the logic flow from the initial visitor request through the plan-gating check to final asset delivery.
Sources: README.md:46-47, README.md:73-86, AGENTS.md:57-59
Media Signing and Delivery
A critical function of the edge proxy system is the secure delivery of video testimonials. KudosWall utilizes HMAC-SHA256 signed paths powered by Cloudflare R2. This ensures that media assets are only accessible via temporary, secure URLs with a specific Time-To-Live (TTL).
Video Playback Sequence
The sequence for media playback involves verifying the plan tier and generating secure tokens:
This sequence illustrates how the edge proxy mediates between the browser and storage to provide secure, gated video streaming.
Sources: README.md:41-43, README.md:73-86
Storage & Security Components
| Component | Technology | Role |
|---|---|---|
| Edge Proxy | Next.js Edge Runtime | Lightweight routing and request proxying |
| Media Storage | Cloudflare R2 | Object storage for high-fidelity video recordings |
| Security Secret | R2_SIGNING_SECRET | HMAC-SHA256 seed for generating signed media URLs |
| Database | Neon Postgres | Plan tier and testimonial metadata storage |
Sources: README.md:103-107, README.md:73-86
Dynamic Routing & Sitemap Integration
The routing system dynamically handles two primary types of public URLs: collection pages and "Wall of Love" pages. These are generated based on the collectionSlug property of a project. The sitemap generation logic fetches these slugs directly from the database to ensure search engines can index public testimonial walls.
Route Patterns
| Path Pattern | Purpose | Priority |
|---|---|---|
/collect/[slug] | Public campaign page for gathering new testimonials | 0.8 |
/wall/[slug] | Public "Wall of Love" displaying approved testimonials | 0.9 |
/t/[testimonialId] | Direct sharing link for an individual testimonial | N/A |
Sources: apps/web/src/app/sitemap.ts:24-35, apps/web/src/app/wall/[slug]/page.tsx:88-100
Wall Data Fetching Logic
For Wall pages, the system employs unstable_cache with specific tags (collection, wall) to optimize performance at the edge. The fetcher resolves the project by either its primary slug or its collectionSlug, then aggregates testimonials in a single query.
Sources: apps/web/src/app/wall/[slug]/page.tsx:49-57, apps/web/src/app/wall/[slug]/page.tsx:102-106
Edge Environment Configuration
The proxy and routing behavior are governed by strictly validated environment variables. The system uses a centralized @my-better-t-app/env package to ensure that all required secrets for edge execution are present at runtime.
Relevant Edge Variables
R2_SIGNING_SECRET: Required for the HMAC-SHA256 media signing sequence.DATABASE_URL: Neon serverless connection string for state lookups.DATABASE_READ_URL: Optional replica for high-scale widget reads at the edge.
Sources: README.md:100-108, README.md:120
Conclusion
The Edge Request Proxy and Routing system is the backbone of KudosWall's performance strategy. By offloading routing logic to a specialized edge proxy (src/proxy.ts) and leveraging HMAC signing for R2 storage, the platform achieves sub-100ms loading times for testimonial widgets while maintaining strict plan-based access controls.