v1.9 Operations and Tech

Short reference for timeouts, env, and debugging failed runs.

Timeouts

Route level: maxDuration = 300 on /api/analyze, /api/roles/crawl, /api/roles/cmo, /api/roles/cdo; 120s on /api/roles/coo, /api/roles/bd, /api/analyze-cdo. On Vercel Hobby the default is 60s; Pro/Enterprise allow 300s.
Pipeline steps: Discovery/crawl use AbortSignal.timeout(5–30s) per fetch; enrichment and external services have their own timeouts (e.g. 10–15s). No single pipeline-level timeout; the request can run up to maxDuration.
When a run times out: The platform may close the request (e.g. Vercel FUNCTION_INVOCATION_TIMEOUT). The analyze route sends a user-facing "Analysis took too long. Please try again." on timeout-like errors. The client shows "Connection lost" or "Connection lost or request cancelled" when the stream ends without complete/error.

Variable	Purpose	Required for
`OPENAI_API_KEY`	All AI steps (category, component analysis, synthesis)	Every run
`BRAVE_SEARCH_API_KEY`	Brand validation and competitor search (fallback when Serper not set)	Enrichment
`SERPER_API_KEY`	Brand/competitor search (preferred over Brave)	Enrichment (optional)
`ENABLE_EXTERNAL_ENRICHMENT`	When `false`, skip external enrichment (brand, traffic, etc.)	Set to `false` in prod for MVP to reduce dependency
`MAX_PAGES`	Cap discovery page count (e.g. `5`)	Optional; default max 8
`ENABLE_CDO_MODE`	Allow CDO (design audit) in production	CDO only; default off

Execution log: Each run has an executionLog (streamed to the client and stored with the run). Check the last entries for the step that failed and the error message.
Database: analysis_runs stores error_message and execution_log on failure. Join with run_id from the client or from report snapshots.
URL validation: All entry points that accept a URL use validateUrl (core/security/url-guard). Invalid or private URLs return 400 with a clear error (e.g. "URL must not point to localhost, private, or internal addresses").

Per user: Usage limits (5/15/50 analyses per month by plan) are enforced in the analyze and roles routes.
Per domain (scraping): Crawl and external services use per-domain rate limiters to avoid blocking.
Production: For abuse resistance, enable IP-based or per-user request rate limiting (e.g. Vercel or middleware) to cap analyses per hour per IP/user. Not required for MVP if usage limits are sufficient.