Showcase API Proxy Setup
Relevant source files
The following files were used as context for generating this wiki page:
The Showcase API Proxy serves as a same-origin serverless bridge between the Portfolio frontend and the live GestaltView runtime. It facilitates communication by signing requests and managing secrets without exposing them to the client-side browser environment. This setup enables live demos like Billy Chat, the Tribunal of Understanding, and the Generative Render Engine to function using production-grade AI synthesis.
Sources: showcase/README.md:1-9, showcase.html:107-108
System Architecture
The proxy architecture prevents secret leakage by isolating the INSIGHT_BOT_SIGNING_SECRET within the server-side environment. Client-side artifacts POST data to a local endpoint, which then validates, signs, and forwards the payload to the external GestaltView runtime URL.
Data Flow Pattern
This diagram illustrates the request lifecycle from the user interface through the secure proxy to the external runtime.
Sources: showcase/README.md:12-19, showcase/showcase-config.js:1-10
Configuration and Environment Variables
The system relies on a central configuration file and specific environment variables defined in the Vercel project settings. The proxy path is standardized as /api/showcase-proxy.
Configuration Tokens
| Variable | Scope | Description |
|---|---|---|
INSIGHT_BOT_SIGNING_SECRET | Server (Proxy) | Shared adapter secret used to sign requests. Never exposed to client. |
INSIGHT_BOT_RUNTIME_URL | Server (Proxy) | The base URL of the live runtime (defaults to gestaltview-three.vercel.app). |
SHOWCASE_ADMIN_TOKEN | Server (Proxy) | Optional token for bypassing rate limits during testing. |
PROXY_PATH | Client (JS) | The relative path used by fetch calls in demo pages. |
CHANNEL | Client (JS) | The allowlisted channel identity (default: "showcase"). |
Sources: showcase/README.md:21-42, showcase/showcase-config.js:12-30
Implementation Example: Configuration Object
window.SHOWCASE_CONFIG = {
INSIGHT_BOT_RUNTIME_URL: "https://gestaltview-three.vercel.app",
PROXY_PATH: "/api/showcase-proxy",
CHANNEL: "showcase",
RATE_LIMIT_PER_MIN: 10,
TRIBUNAL_STAGGER_MS: 4000,
TIMEOUT_MS: 20000
};
Sources: showcase/showcase-config.js:14-35
Operational Constraints
To maintain stability and prevent abuse, the proxy implements rate limiting and staggering logic. These constraints ensure the runtime orchestrator does not trip its internal circuit breakers.
Staggering and Rate Limits
The system enforces a limit of 10 requests per IP per minute. For complex demos like the Tribunal of Understanding, which requires seven sequential calls, the client-side logic staggers requests by 4000ms. This prevents the runtime from serving fallback/stubbed content due to rapid back-to-back hits.
This sequence ensures each "voice" in the multi-call demos remains live and avoids circuit breaker interference.
Sources: showcase/showcase-config.js:25-30, showcase/README.md:69-75, showcase/render-engine.html:410-415
Integration with Showcase Artifacts
The proxy handles synthesis requests for several core demos defined in the project registry. While the synthesis logic (prompting, style guides) is requested via the proxy, the final rendering of artifacts (Markdown, HTML) often occurs locally in the browser for performance and privacy.
Wired Components
- Billy Chat: Live conversation via signed proxy; ephemeral by design.
- Tribunal of Understanding: Sequential synthesis using persona-specific framing.
- Render Engine: Concatenates system and user blocks into a single-text field for the signed proxy.
Sources: showcase/registry.json:72-108, showcase/render-engine.html:283-300
Security and Administrative Bypass
For administrative testing, a SHOWCASE_ADMIN_TOKEN can be set. When a browser carries a showcase_admin cookie matching this token, the proxy skips the standard rate limiter while still requiring a valid signing secret and runtime contract.
Sources: showcase/README.md:32-42
The Showcase API Proxy Setup ensures that the Portfolio site remains a secure, high-performance window into the GestaltView runtime while strictly adhering to an "evidence-first" architecture that separates client-side presentation from server-side security.
Sources: README.md:52-57, showcase/README.md:78-82