---

name: serpapi-reference-architecture description: 'Design a governed SerpAPI search service with engine adapters, policy enforcement, caching, capacity management, observability, and privacy boundaries. Use when conducting architecture review. Trigger with "design a SerpAPI architecture".' argument-hint: "[use-case] [engines] [data-classification]" allowed-tools: Read, Glob, Grep, WebFetch, Write, Edit version: 1.6.0 author: Jeremy Longshore jeremy@intentsolutions.io license: MIT tags: [saas, serpapi, architecture, governance, reliability] model: inherit effort: high compatibility: Designed for Claude Code; architecture output is a review artifact and does not authorize infrastructure, account, or production changes

SerpAPI Governed Reference Architecture

Overview

Place SerpAPI behind an application boundary that controls identity, parameters, data, allowance, and failure behavior for every engine.

Prerequisites

• Business use cases, caller identities, engines, data classes, freshness and latency objectives
• Volume model, account contract, downstream systems, and regulatory/retention requirements
• Security, product, finance, reliability, and platform owners

Tool Discipline

Use Read, Glob, and Grep to ground the design in repository and infrastructure topology, WebFetch to verify current vendor contracts, and Write or Edit for diagrams, decision records, interfaces, threat models, and rollout evidence.

Current Contract

SerpAPI has engine-specific requests and variable response sections, private-key authentication, account-level search and throughput capacity, optional async/archive processing, one-hour exact-query server caching, and Enterprise ZeroTrace. Async depends on archive retrieval, while ZeroTrace intentionally prevents stored search records.

Authentication

Keep SERPAPI_KEY in a server-side secret boundary. Authenticate application callers independently and enforce use-case authorization before the gateway maps input to allowlisted vendor parameters.

Instructions

1. Map callers, trust zones, engines, queries, results, stores, consumers, data classes, and systems of record.
2. Define an authenticated gateway with use-case-specific input schemas, engine adapters, output projections, and policy enforcement.
3. Add an application cache with credential-free semantic keys, freshness TTLs, encryption and retention appropriate to the data class.
4. Coordinate admission, concurrency, pagination, retries, and background work against live Account API capacity.
5. Separate synchronous calls from async/archive jobs and prove that any ZeroTrace path does not rely on archive replay.
6. Emit safe metrics and search-ID correlation without query, result, key-bearing URL, or account leakage.
7. Design fixture-first tests, canary, reconciliation, degradation, support escalation, key rotation, disaster recovery, and rollback.
8. Record alternatives, constraints, approvals, unresolved risks, and a staged implementation plan.

Approval Boundaries

Do not provision infrastructure, expose routes, create secrets, enable account features, or send production searches from an architecture exercise.

Output

Return context and container diagrams, trust/data flows, gateway and adapter contracts, cache/capacity design, privacy decision, failure model, test/rollout plan, risks, and decision owners.

Error Handling

Condition	Response
Gateway is a generic parameter pass-through	Replace it with use-case schemas and allowlists.
Capacity is managed per instance only	Add shared admission control across credential-sharing workers.
ZeroTrace path requires replay	Redesign the diagnostic and recovery model.
Search results become a system of record	Define provenance, refresh, deletion, and reconciliation explicitly.

Example

caller -> authenticated policy gateway -> engine adapter -> capacity limiter -> SerpAPI
                                      \-> semantic cache
search metadata -> redacted telemetry; normalized results -> governed consumer

Resources

• SerpAPI documentation
• Account API
• ZeroTrace Mode
• Searches Archive API

Next Steps

Validate the design with security, product, finance, and reliability owners before creating an implementation tranche.