# bcat95/shopee-aff architecture

> Architecture diagram of the GitHub repository bcat95/shopee-aff, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bcat95/shopee-aff
- Repository: https://github.com/bcat95/shopee-aff

## Overview

1. This repository is primarily a **reference and demo workspace for Shopee Affiliate APIs**, not a full production application. The root `README.md` is the canonical architecture/documentation entry point and explains the official Shopee Open API and GraphQL surfaces this repo targets.

2. The repo has **two documentation domains**:
   - `README.md` for the **official Shopee Affiliate API**.
   - `product-data-api.md` for the **non-official Product Data API**.
   This is an important boundary: the repo intentionally separates “official integration” from “unofficial scraping/data extraction” material.

3. The main external dependency is the **Shopee Affiliate platform itself**:
   - REST/OpenAPI endpoints for product lookups.
   - GraphQL queries/mutations for offer lists, affiliate link generation, and conversion/validated reports.
   The architecture is therefore an **API consumer toolkit** around Shopee, with no internal persistence layer shown in the tree.

4. `Code/` contains **runnable sample clients** for the official API in two runtimes:
   - `Code/nodejs/` for Node.js.
   - `Code/php/` for PHP.
   Both have `.env.example` files, which indicates secrets and credentials are expected to be injected externally rather than committed.

5. The Node.js sample is the most “application-like” part of the repo:
   - `index.js` is the execution entry point.
   - `index.test.js` shows there is at least some automated validation.
   - `package.json` defines the runtime and dependencies.
   Architecturally, this sample likely wraps Shopee request signing/authentication and demonstrates one or more API calls end to end.

6. The PHP sample under `Code/php/` is the parallel implementation of the same idea:
   - `index.php` is the entry point.
   - `.env.example` suggests it also relies on credential/config injection.
   This gives the repo a **language-agnostic integration pattern** for Shopee API access.

7. `Postman/` is a **manual testing and exploration layer**:
   - `Shopee-Product-Data.postman_collection.json`
   - `Shopee-Product-Data.postman_environment.json`
   These artifacts are for reproducing requests, experimenting with parameters, and validating responses without writing code.

8. `bc-custom-link/` is a separate **PHP-based utility/demo app** with its own mini front-end:
   - `index.php`, `link.php`, `conn.php`, `func.php`
   - `assets/javascript` and `assets/stylesheets/custom.css`
   This looks like a small web tool for generating or managing affiliate/custom links, with a lightweight server-side PHP backend and browser UI assets.

9. The data flow across the repo is consistent:
   **developer or end user inputs Shopee credentials/config** → **sample code or custom-link UI builds authenticated requests** → **requests go to Shopee Affiliate Open API / GraphQL** → **responses are displayed, tested, or used to create affiliate links / inspect conversions**.
   There is no evidence of a local database, message queue, or background worker architecture.

10. The important functional boundaries are by API capability, not by service tier:
   - **Product data** retrieval.
   - **Offer discovery**.
   - **Affiliate link generation**.
   - **Conversion/validated reporting**.
   These are mapped directly in the docs and likely mirrored in the sample code and Postman collection.

11. From an architecture-diagram perspective, the repo should be drawn as a **tooling and documentation hub** centered on Shopee APIs, with three consumer surfaces:
   - scripted API clients (`Code/`)
   - manual API client artifacts (`Postman/`)
   - a browser-based PHP helper app (`bc-custom-link/`)
   All of them depend on the same external Shopee Affiliate API platform.

12. The repo’s operational assumptions are important:
   - credentials/signatures/tokens are required,
   - rate limits and cursor expiry matter,
   - GraphQL and REST coexist,
   - affiliate link creation and conversion reporting are the key business flows.
   These constraints shape the implementation, but they are enforced by the Shopee platform rather than by internal infrastructure in this repo.

Main entry points: [`Code/nodejs/index.js`](https://github.com/bcat95/shopee-aff/blob/main/Code/nodejs/index.js) (Node sample), [`Code/php/index.php`](https://github.com/bcat95/shopee-aff/blob/main/Code/php/index.php) (PHP sample), [`bc-custom-link/link.php`](https://github.com/bcat95/shopee-aff/blob/main/bc-custom-link/link.php) (Link builder), [`Postman/Shopee-Product-Data.postman_collection.json`](https://github.com/bcat95/shopee-aff/blob/main/Postman/Shopee-Product-Data.postman_collection.json) (Postman collection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_docs["Documentation"]
  node_readme["README<br/>entry docs<br/>[README.md]"]
  node_product_docs["Product API<br/>docs boundary"]
end

subgraph group_samples["Code Samples"]
  node_code_readme["Code README<br/>samples docs<br/>[README.md]"]
  node_node_sample["Node sample<br/>client demo<br/>[index.js]"]
  node_node_tests["Node tests<br/>validation<br/>[index.test.js]"]
  node_node_pkg["Node config<br/>runtime config<br/>[package.json]"]
  node_php_sample["PHP sample<br/>client demo<br/>[index.php]"]
end

subgraph group_manual["Manual Testing"]
  node_postman_collection["Postman collection<br/>request set"]
  node_postman_env["Postman env<br/>environment"]
end

subgraph group_tool["Custom Link Tool"]
  node_bc_app["Link tool<br/>php web tool<br/>[index.php]"]
  node_bc_link["Link builder<br/>link workflow<br/>[link.php]"]
  node_bc_conn["Connection<br/>integration helper<br/>[conn.php]"]
  node_bc_func["Helpers<br/>utility layer<br/>[func.php]"]
end

subgraph group_external["Shopee Platform"]
  node_shopee_api[("Shopee API<br/>external platform")]
  node_rest_api(("REST/OpenAPI<br/>product lookup surface"))
  node_graphql_api(("GraphQL<br/>affiliate surface"))
  node_affiliate_flows{{"Affiliate flows<br/>business capability"}}
end

node_readme -->|"documents"| node_shopee_api
node_product_docs -->|"references"| node_shopee_api
node_code_readme -->|"guides"| node_node_sample
node_code_readme -->|"guides"| node_php_sample
node_node_sample -->|"uses"| node_node_pkg
node_node_sample -.->|"validated by"| node_node_tests
node_node_sample -->|"calls"| node_rest_api
node_node_sample -->|"calls"| node_graphql_api
node_php_sample -->|"calls"| node_graphql_api
node_php_sample -->|"calls"| node_rest_api
node_postman_collection -->|"exercises"| node_rest_api
node_postman_collection -->|"exercises"| node_graphql_api
node_postman_env -->|"configures"| node_postman_collection
node_bc_app -->|"drives"| node_bc_link
node_bc_link -->|"uses"| node_bc_conn
node_bc_link -->|"uses"| node_bc_func
node_bc_conn -->|"calls"| node_graphql_api
node_affiliate_flows -->|"implemented by"| node_graphql_api
node_affiliate_flows -->|"supported by"| node_rest_api
node_shopee_api -->|"includes"| node_rest_api
node_shopee_api -->|"includes"| node_graphql_api

click node_readme "https://github.com/bcat95/shopee-aff/blob/main/README.md"
click node_product_docs "https://github.com/bcat95/shopee-aff/blob/main/product-data-api.md"
click node_code_readme "https://github.com/bcat95/shopee-aff/blob/main/Code/README.md"
click node_node_sample "https://github.com/bcat95/shopee-aff/blob/main/Code/nodejs/index.js"
click node_node_tests "https://github.com/bcat95/shopee-aff/blob/main/Code/nodejs/index.test.js"
click node_node_pkg "https://github.com/bcat95/shopee-aff/blob/main/Code/nodejs/package.json"
click node_php_sample "https://github.com/bcat95/shopee-aff/blob/main/Code/php/index.php"
click node_postman_collection "https://github.com/bcat95/shopee-aff/blob/main/Postman/Shopee-Product-Data.postman_collection.json"
click node_postman_env "https://github.com/bcat95/shopee-aff/blob/main/Postman/Shopee-Product-Data.postman_environment.json"
click node_bc_app "https://github.com/bcat95/shopee-aff/blob/main/bc-custom-link/index.php"
click node_bc_link "https://github.com/bcat95/shopee-aff/blob/main/bc-custom-link/link.php"
click node_bc_conn "https://github.com/bcat95/shopee-aff/blob/main/bc-custom-link/conn.php"
click node_bc_func "https://github.com/bcat95/shopee-aff/blob/main/bc-custom-link/func.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_readme,node_product_docs toneBlue
class node_code_readme,node_node_sample,node_node_tests,node_node_pkg,node_php_sample toneAmber
class node_postman_collection,node_postman_env toneMint
class node_bc_app,node_bc_link,node_bc_conn,node_bc_func toneRose
class node_shopee_api,node_rest_api,node_graphql_api,node_affiliate_flows toneIndigo
```

## Components

### Documentation

Repository guidance and API references

- [README](https://github.com/bcat95/shopee-aff/blob/main/README.md): entry docs · Canonical entry point for the official Shopee Affiliate API · `README.md`
- [Product API](https://github.com/bcat95/shopee-aff/blob/main/product-data-api.md): docs boundary · Non-official product data API reference and boundary · `product-data-api.md`

### Code Samples

Runnable client implementations

- [Code README](https://github.com/bcat95/shopee-aff/blob/main/Code/README.md): samples docs · Overview for runnable code samples · `Code/README.md`
- [Node sample](https://github.com/bcat95/shopee-aff/blob/main/Code/nodejs/index.js): client demo · Executable Node.js Shopee API client · `Code/nodejs/index.js`
- [Node tests](https://github.com/bcat95/shopee-aff/blob/main/Code/nodejs/index.test.js): validation · Automated checks for the Node sample · `Code/nodejs/index.test.js`
- [Node config](https://github.com/bcat95/shopee-aff/blob/main/Code/nodejs/package.json): runtime config · Node.js package and dependency definition · `Code/nodejs/package.json`
- [PHP sample](https://github.com/bcat95/shopee-aff/blob/main/Code/php/index.php): client demo · Executable PHP Shopee API client · `Code/php/index.php`

### Manual Testing

Postman artifacts for request exploration

- [Postman collection](https://github.com/bcat95/shopee-aff/blob/main/Postman/Shopee-Product-Data.postman_collection.json): request set · Saved requests for product data exploration · `Postman/Shopee-Product-Data.postman_collection.json`
- [Postman env](https://github.com/bcat95/shopee-aff/blob/main/Postman/Shopee-Product-Data.postman_environment.json): environment · Local environment values for Postman runs · `Postman/Shopee-Product-Data.postman_environment.json`

### Custom Link Tool

PHP utility for affiliate link workflows

- [Link tool](https://github.com/bcat95/shopee-aff/blob/main/bc-custom-link/index.php): php web tool · Browser-based PHP utility for custom affiliate links · `bc-custom-link/index.php`
- [Link builder](https://github.com/bcat95/shopee-aff/blob/main/bc-custom-link/link.php): link workflow · Server-side link generation and request handling · `bc-custom-link/link.php`
- [Connection](https://github.com/bcat95/shopee-aff/blob/main/bc-custom-link/conn.php): integration helper · Backend connection and API setup logic · `bc-custom-link/conn.php`
- [Helpers](https://github.com/bcat95/shopee-aff/blob/main/bc-custom-link/func.php): utility layer · Shared PHP helper functions for the custom link tool · `bc-custom-link/func.php`

### Shopee Platform

External API surfaces and business capabilities

- **Shopee API**: external platform · External Shopee Affiliate platform
- **REST/OpenAPI**: product lookup surface · Official REST endpoints for product data
- **GraphQL**: affiliate surface · Official GraphQL queries and mutations for affiliate workflows
- **Affiliate flows**: business capability · Offer discovery, link generation, and conversion reporting

## Connections

- README → Shopee API: documents · Explains the official platform and supported API surfaces
- Product API → Shopee API: references · Covers the non-official product data API boundary
- Code README → Node sample: guides · Introduces the runnable Node.js sample
- Code README → PHP sample: guides · Introduces the runnable PHP sample
- Node sample → Node config: uses · Depends on package and runtime configuration
- Node sample → Node tests: validated by · Has a companion test file
- Node sample → REST/OpenAPI: calls · Demonstrates REST/OpenAPI product requests
- Node sample → GraphQL: calls · Demonstrates GraphQL affiliate requests
- PHP sample → GraphQL: calls · Parallel PHP integration against Shopee GraphQL
- PHP sample → REST/OpenAPI: calls · Parallel PHP integration against Shopee REST
- Postman collection → REST/OpenAPI: exercises · Saved requests for manual API exploration
- Postman collection → GraphQL: exercises · Can reproduce GraphQL affiliate queries
- Postman env → Postman collection: configures · Provides environment variables for runs
- Link tool → Link builder: drives · UI submits link-generation actions
- Link builder → Connection: uses · Delegates backend connectivity and auth setup
- Link builder → Helpers: uses · Shares helper routines for link processing
- Connection → GraphQL: calls · Backend talks to Shopee affiliate APIs
- Affiliate flows → GraphQL: implemented by · Key affiliate workflows are exposed through GraphQL
- Affiliate flows → REST/OpenAPI: supported by · Product lookup flows use REST/OpenAPI
- Shopee API → REST/OpenAPI: includes · External platform exposes REST product endpoints
- Shopee API → GraphQL: includes · External platform exposes GraphQL affiliate operations