# htdangkhoa/google-ads architecture

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

- Interactive diagram: https://gitdiagram.com/htdangkhoa/google-ads
- Repository: https://github.com/htdangkhoa/google-ads

## Overview

##### Project Type and Purpose
- This is a Node.js client library for the Google Ads API. It wraps the gRPC definitions (generated via ts-proto), exposes a friendly TypeScript/JavaScript API (classes like GoogleAds, Customer, QueryBuilder), and manages authentication, request building, logging, and streaming/mutation calls.

##### File Structure Analysis
- Top-level directories:
- src/ – core TS code: ServiceProvider, Service, LoggingInterceptor, QueryBuilder, constants, utils, and entry point index.ts
- scripts/build/ – build scripts producing CJS, ESM, and type declarations
- example/ – sample usage scripts (ad-group, campaign, search, etc.)
- tests/ – unit tests for each module
- .github/workflows/ – CI pipelines (build, test, publish)
- Config: multiple tsconfig.json for base/CJS/ESM/types, vitest.config.ts for testing.
- package.json orchestrates dependencies (grpc-js, google-auth-library, ts-proto) and build/test scripts.

##### README Insights
- Describes instantiation of auth clients (UserRefreshClient, JWT)
- Shows core abstractions: Customer service, GoogleAds service, search/searchStream, mutate
- Explains logging and interceptor configuration
- Notes build steps: generate protos, compile TS, run tests

##### Main Components
a. Library API Layer (TypeScript classes)
- ServiceProvider → dynamic loader of generated gRPC service clients
- Service (base class) → common request wrapper, error handling
- GoogleAds / Customer classes → specific API entry points
- QueryBuilder → DSL for building GAQL queries
- LoggingInterceptor → logs summary/detail of each RPC
b. Generated gRPC Layer
- ts-proto–generated stubs (imported under src via codegen)
- grpc-js Client channels
c. Authentication Layer
- google-auth-library clients (UserRefreshClient, JWT)
d. Google Ads API Backend (external gRPC service at ads.googleapis.com)
e. Build & CI Pipeline
- scripts/build → cjs, esm, types outputs in dist/
- .github/workflows → test, publish, version bump

##### Interactions and Data Flows
- The user’s Node.js app imports @htdangkhoa/google-ads → instantiates a Service (Customer or GoogleAds)
- ServiceProvider uses auth credentials to create a grpc-js channel to the Google Ads API endpoint
- On each API call (search, mutate):
- QueryBuilder (if used) builds GAQL string
- Service invokes the corresponding gRPC method on the generated client
- LoggingInterceptor intercepts request/response for logging
- grpc-js transmits over TLS to Google Ads backend and returns results
- Build pipeline compiles TS → JS (CJS/ESM) + .d.ts and publishes to npm

##### Architectural Patterns & Principles
- Wrapper + Facade pattern: ServiceProvider hides low-level gRPC details
- Interceptor pattern: LoggingInterceptor conforms to grpc-js interceptor API
- DSL for queries: QueryBuilder enforces type-safe GAQL composition
- Separation of concerns: Auth, transport, logging, request building, and service definitions are modular

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Application Layer
    subgraph "Client Application"
        direction TB
        App["example/*.ts"] 
    end

    %% SDK Layer
    subgraph "SDK Layer"
        direction TB
        Index["index.ts"] 
        SP["ServiceProvider"] 
        BaseService["Service (base class)"] 
        GA["GoogleAds client class"] 
        CU["Customer client class"] 
        QB["QueryBuilder (GAQL DSL)"] 
        LI["LoggingInterceptor"] 
        CONST["constants.ts"] 
        UTIL["utils.ts"] 
        TYPES["types.ts"] 
    end

    %% Generated gRPC Layer
    subgraph "Generated gRPC Layer"
        direction TB
        Stubs["ts-proto generated stubs"] 
        Channel["grpc-js Client Channel"] 
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Auth["google-auth-library clients"] 
        AdsAPI["Google Ads API (ads.googleapis.com)"] 
    end

    %% Build & CI
    subgraph "Build & CI Pipeline"
        direction TB
        CJS["scripts/build/cjs.mjs"] 
        ESM["scripts/build/esm.mjs"] 
        TYPES_BUILD["scripts/build/types.mjs"] 
        CI[".github/workflows/*.yml"] 
    end

    %% Relationships
    App -->|"imports SDK"| Index
    Index --> SP
    Index --> GA
    Index --> CU
    SP -->|"loads stub"| Stubs
    SP --> Auth
    Auth --> Channel
    Channel --> AdsAPI
    GA --> SP
    CU --> SP
    GA -->|"uses base"| BaseService
    CU --> BaseService
    BaseService --> Stubs
    BaseService --> LI
    QB --> BaseService
    GA --> QB
    CU --> QB
    LI -->|"intercepts"| Channel
    CONST --> BaseService
    UTIL --> BaseService
    TYPES --> BaseService

    %% Build & CI flow
    CJS -->|"outputs to dist/cjs"| Index
    ESM -->|"outputs to dist/esm"| Index
    TYPES_BUILD -->|"outputs types"| Index
    CI --> CJS
    CI --> ESM
    CI --> TYPES_BUILD

    %% Click Events
    click SP "https://github.com/htdangkhoa/google-ads/blob/main/src/ServiceProvider.ts"
    click BaseService "https://github.com/htdangkhoa/google-ads/blob/main/src/Service.ts"
    click GA "https://github.com/htdangkhoa/google-ads/blob/main/src/GoogleAds.ts"
    click CU "https://github.com/htdangkhoa/google-ads/blob/main/src/Customer.ts"
    click QB "https://github.com/htdangkhoa/google-ads/blob/main/src/QueryBuilder.ts"
    click LI "https://github.com/htdangkhoa/google-ads/blob/main/src/LoggingInterceptor.ts"
    click Index "https://github.com/htdangkhoa/google-ads/blob/main/src/index.ts"
    click CONST "https://github.com/htdangkhoa/google-ads/blob/main/src/constants.ts"
    click UTIL "https://github.com/htdangkhoa/google-ads/blob/main/src/utils.ts"
    click TYPES "https://github.com/htdangkhoa/google-ads/blob/main/src/types.ts"
    click CJS "https://github.com/htdangkhoa/google-ads/blob/main/scripts/build/cjs.mjs"
    click ESM "https://github.com/htdangkhoa/google-ads/blob/main/scripts/build/esm.mjs"
    click TYPES_BUILD "https://github.com/htdangkhoa/google-ads/blob/main/scripts/build/types.mjs"
    click CI "https://github.com/htdangkhoa/google-ads/tree/main/.github/workflows/"

    %% Styles
    class SP,BaseService,GA,CU,QB,LI,Index,CONST,UTIL,TYPES sdk
    class Stubs,Channel generated
    class Auth,AdsAPI external
    class CJS,ESM,TYPES_BUILD,CI build

    classDef sdk fill:#BBDEFB,stroke:#333,stroke-width:1px
    classDef generated fill:#C8E6C9,stroke:#333,stroke-width:1px
    classDef external fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef build fill:#E0E0E0,stroke:#333,stroke-width:1px
```
