# revealbot/panda architecture

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

- Interactive diagram: https://gitdiagram.com/revealbot/panda
- Repository: https://github.com/revealbot/panda

## Overview

##### Main Components
- Client Interface (Panda::Client): This is the primary class that a user instantiates with an access token. It is the entry point for performing any API call (e.g., retrieving advertisers, campaigns, ad groups, ads, reports, etc.).
- Configuration Module (Panda::Configuration): This handles the gem’s configuration settings (API keys, base URLs, API versions). Its role is to provide a globally accessible configuration via a dedicated configure block.
- HTTP Communication (Panda::HTTP_Request and Panda::HTTP_Response): These modules manage the actual sending of HTTP requests and processing of responses from the TikTok Ads API.
- Error Handling (Panda::Error_Middleware and specific custom errors from Panda::Errors): These handle exceptions and problem states. The custom exceptions like APIError, NoPermissionsError, NotAuthorizedError, and TooManyRequestsError are used to signal and handle different error conditions.
- Data Structures (such as Panda::Collection and Panda::Item): These components could assist in mapping and manipulating collections of advertiser details, campaigns, etc.

##### Relationships and Interactions
- The client (Panda::Client) acts as a façade that ties various components together. When a method such as client.advertisers is invoked, the client uses configuration details, builds an HTTP request, and sends it.
- The HTTP_Request component packages the necessary request details (URL, headers, parameters) using configuration.
- The HTTP_Response component processes the raw response and routes it either as valid data or passes errors to the error handling middleware.
- The Error Middleware catches error responses and then raises appropriate custom exceptions.
- Additionally, utility components for handling collections or individual items help parse and structure the results coming back from the API.

##### Additional Architectural and Design Insights
- The gem follows a modular design where different responsibilities (client operations, configuration, HTTP communication, and error management) are separated.
- The configuration design pattern (configuration block) centralizes API key management and endpoint details.
- The error handling design is robust, with distinct classes for various API issues ensuring clarity for client applications that use the gem.
- The tests (in the spec/ directory) have been set up to ensure each of these components works as expected, which reinforces a clean separation of concerns.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Logic"
        CLIENT["Panda::Client"]:::client
    end

    subgraph "Configuration"
        CONFIG["Panda::Configuration"]:::config
    end

    subgraph "HTTP Communication"
        HTTP_REQ["Panda::HTTP_Request"]:::http
        HTTP_RES["Panda::HTTP_Response"]:::http
    end

    subgraph "Error Handling"
        ERR_MW["Panda::Error_Middleware"]:::error
        CUSTOM_ERR["Panda::Errors"]:::error
    end

    subgraph "Data Structures"
        COL["Panda::Collection"]:::data
        ITEM["Panda::Item"]:::data
    end

    CLIENT -->|"uses"| CONFIG
    CLIENT -->|"builds_request"| HTTP_REQ
    HTTP_REQ -->|"sends_request"| HTTP_RES
    HTTP_RES -->|"error_propagation"| ERR_MW
    ERR_MW -->|"raises"| CUSTOM_ERR
    HTTP_RES -->|"parses_to"| COL
    HTTP_RES -->|"parses_to"| ITEM

    click CLIENT "https://github.com/revealbot/panda/blob/main/lib/panda/client.rb"
    click CONFIG "https://github.com/revealbot/panda/blob/main/lib/panda/configuration.rb"
    click HTTP_REQ "https://github.com/revealbot/panda/blob/main/lib/panda/http_request.rb"
    click HTTP_RES "https://github.com/revealbot/panda/blob/main/lib/panda/http_response.rb"
    click ERR_MW "https://github.com/revealbot/panda/blob/main/lib/panda/error_middleware.rb"
    click CUSTOM_ERR "https://github.com/revealbot/panda/blob/main/lib/panda/errors.rb"
    click COL "https://github.com/revealbot/panda/blob/main/lib/panda/collection.rb"
    click ITEM "https://github.com/revealbot/panda/blob/main/lib/panda/item.rb"

    classDef client fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef config fill:#E6E6FA,stroke:#000,stroke-width:2px;
    classDef http fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef error fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef data fill:#90EE90,stroke:#000,stroke-width:2px;
```
