# web-agent-master/google-search architecture

> Architecture diagram of the GitHub repository web-agent-master/google-search, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/web-agent-master/google-search
- Repository: https://github.com/web-agent-master/google-search

## Overview

##### Project Type and Purpose
- This project is a Playwright-based Node.js tool designed to perform Google searches locally while bypassing anti-scraping mechanisms. It serves as both a command-line utility and an MCP server that can integrate with AI assistants (such as Claude).
- Its key focus is on browser automation (using Playwright) and robust search result extraction, along with a server component for real-time search capabilities.

##### Analyzing the File Structure
- At the top level, you have configuration files (package.json, tsconfig.json), build artifacts (bin for executables), and the src/ directory that contains the core TypeScript code.
- The src/ folder includes:
- index.ts (the main entry point for command-line usage and the initial parsing logic)
- search.ts (contains the logic responsible for handling the browser automation to perform searches)
- mcp-server.ts (implements the MCP server functionality for AI assistant integration)
- logger.ts and types.ts (for logging and type definitions)
- The bin directory contains executable scripts, which indicate that the project is designed to be used as a command-line tool (with both standard search and MCP-specific entry points).

##### Architectural Components
- Command-Line Interface (CLI):
- Entry point (index.ts) which handles argument parsing (likely using Commander) and triggers search functionalities.
- Search Module:
- Search.ts component that manages browser automation via Playwright.
- Interactions with the logger for detailed output and error handling.
- MCP Server:
- Mcp-server.ts component which stands apart from the CLI, providing a long-running server process to serve search queries in real-time.
- Integration with external AI assistants (e.g., Claude) using the Model Context Protocol.
- Shared Utilities:
- Supporting modules such as logger.ts for logging and types.ts for shared type definitions.
- Underlying Infrastructure:
- Node.js runtime environment, TypeScript transpilation (indicated by tsconfig.json and package.json), and dependency management via pnpm.
- Playwright for browser automation across different modes (headless/headed) with state management for anti-bot detection.

##### Relationships and Data Flow
- For MCP functionality, illustrate the mcp-server.ts component receiving external requests via a standardized protocol (MCP) and then internally calling the search functionality.
- Error handling flows where errors from the browser automation and network issues are captured and logged via logger.ts.

##### Architectural Patterns and Design Principles
- The separation of concerns: clearly divide the application into a CLI part vs. a server component.
- Encapsulation of browser automation in the search module, ensuring that complexities like fingerprint management, state saving, and error recovery are modularized.
- Integration via a protocol (MCP), which isolates the search service from the client (e.g., Claude).
- Use of TypeScript for type safety and structured coding with domain-specific types in types.ts.

##### Including Relevant Technologies
- Node.js as the execution environment.
- TypeScript as the development language.
- Playwright for browser interaction.
- Commander (or similar) for command line parsing.
- MCP SDK and Zod for protocol implementation and schema validation.
- pnpm for package management.

- Deployment aspects—mention that the tool uses compiled JavaScript (via tsconfig.json) and that executable scripts reside in the bin/ directory.
- Error handling and logging as a cross-cutting concern (show that errors from search.ts and mcp-server.ts are handed off to the logger).
- Use annotations to note special handling for Windows environments (like .cmd files and cross-platform path handling), which might affect deployment or runtime behavior.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Actors
    U["User Terminal"]:::external
    V["External AI Assistant"]:::external
    N["Playwright Browser - Automation Engine"]:::external

    %% CLI Components Subgraph
    subgraph "CLI Components"
        A["src/index.ts - CLI Entry"]:::cli
        B["bin/google-search"]:::cli
        C["bin/google-search.cmd"]:::cli
        B -->|"launches"| A
        C -->|"launches"| A
    end

    %% Search Module
    D["src/search.ts - Playwright Search Module"]:::search

    %% MCP Server Components Subgraph
    subgraph "MCP Server Components"
        E["src/mcp-server.ts - MCP Server for AI Integration"]:::mcp
        F["bin/google-search-mcp"]:::mcp
        G["bin/google-search-mcp.cmd"]:::mcp
        F -->|"launches"| E
        G -->|"launches"| E
    end

    %% Utilities
    subgraph "Shared Utilities"
        H["src/logger.ts - Logging Utility"]:::utility
        I["src/types.ts - Type Definitions"]:::utility
    end

    %% Infrastructure & Configurations
    subgraph "Infrastructure & Config"
        J["package.json - Project Config"]:::config
        K["tsconfig.json - TypeScript Config"]:::config
        L["pnpm-lock.yaml - Package Lock"]:::config
    end

    %% Data Flow & Interactions
    U -->|"triggers"| A
    A -->|"executes search"| D
    V -->|"sends search request"| E
    E -->|"delegates to search"| D

    %% Error Logging connections
    A -->|"logs errors"| H
    D -->|"logs errors"| H
    E -->|"logs errors"| H

    %% External Browser Automation connection
    D -->|"manages"| N

    %% Click Events
    click A "https://github.com/web-agent-master/google-search/blob/main/src/index.ts"
    click B "https://github.com/web-agent-master/google-search/tree/main/bin/google-search"
    click C "https://github.com/web-agent-master/google-search/blob/main/bin/google-search.cmd"
    click D "https://github.com/web-agent-master/google-search/blob/main/src/search.ts"
    click E "https://github.com/web-agent-master/google-search/blob/main/src/mcp-server.ts"
    click F "https://github.com/web-agent-master/google-search/tree/main/bin/google-search-mcp"
    click G "https://github.com/web-agent-master/google-search/blob/main/bin/google-search-mcp.cmd"
    click H "https://github.com/web-agent-master/google-search/blob/main/src/logger.ts"
    click I "https://github.com/web-agent-master/google-search/blob/main/src/types.ts"
    click J "https://github.com/web-agent-master/google-search/blob/main/package.json"
    click K "https://github.com/web-agent-master/google-search/blob/main/tsconfig.json"
    click L "https://github.com/web-agent-master/google-search/blob/main/pnpm-lock.yaml"

    %% Styles
    classDef cli fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef search fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef mcp fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef utility fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef config fill:#D8BFD8,stroke:#000,stroke-width:2px;
    classDef external fill:#F5DEB3,stroke:#000,stroke-width:2px;
```
