serpapi-reference-architecture

name	serpapi-reference-architecture
description	Production architecture for SerpApi search services with caching, monitoring, and multi-engine support. Use when designing search features, building SERP tracking systems, or architecting search-powered applications. Trigger: "serpapi architecture", "serpapi project structure", "serpapi design".
allowed-tools	Read, Grep
version	1.4.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","search","seo","serpapi"]
compatibility	Designed for Claude Code

SerpApi Reference Architecture

Overview

Production architecture for search-powered applications using SerpApi. Core components: cached search service, multi-engine abstraction, SERP monitoring pipeline, and credit budget management.

Architecture Diagram

┌──────────────────────────────────┐
│          API Layer               │
│  /search  /track  /health        │
├──────────────────────────────────┤
│        Search Service            │
│  Multi-engine  Caching  Parsing  │
├──────────────────────────────────┤
│       SerpApi Client             │
│  Rate Limiting  Retry  Archive   │
├──────────────────────────────────┤
│       Infrastructure             │
│  Redis Cache  PostgreSQL  Cron   │
└──────────────────────────────────┘
         │
         ▼
┌──────────────────────────────────┐
│        SerpApi REST API          │
│  google  youtube  bing  news     │
│  1 credit/search, 100-50K/mo     │
└──────────────────────────────────┘

Project Structure

search-service/
├── src/
│   ├── serpapi/
│   │   ├── client.ts          # Cached search with rate limiting
│   │   ├── engines.ts         # Engine-specific param mapping
│   │   └── types.ts           # Typed result interfaces
│   ├── services/
│   │   ├── search.ts          # Multi-engine search facade
│   │   ├── tracking.ts        # Keyword rank tracking
│   │   └── credits.ts         # Usage monitoring
│   ├── api/
│   │   ├── search.ts          # /search proxy endpoint
│   │   └── health.ts          # /health with credit check
│   └── jobs/
│       └── rank-tracker.ts    # Daily keyword monitoring
├── tests/
│   ├── fixtures/              # Recorded SerpApi responses
│   └── search.test.ts         # Fixture-based tests
└── config/

Key Components

Search Service Facade

class SearchService {
  constructor(private client: CachedSerpApiClient, private db: Database) {}

  async search(query: string, options?: { engine?: string; num?: number }) {
    const engine = options?.engine || ;
     result =  ..({
      engine, : query, : options?. || ,
    });

    
     {
      : result. || result. || [],
      : result. || ,
      : result. || ,
      : result..,
      : result. || ,
    };
  }

   () {
     result =  ..({
      : , : keyword, : ,
    });
     position = result.?.(
       r.?.(domain)
    );
     ..(keyword, domain, position >=  ? position +  : );
  }
}