# netkaruma/search1688api architecture

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

- Interactive diagram: https://gitdiagram.com/netkaruma/search1688api
- Repository: https://github.com/netkaruma/search1688api

## Overview

This library exposes synchronous and asynchronous 1688 product-search sessions. Users submit an image or text query; the session initializes cookies and signing state, performs the relevant 1688 requests, and returns parsed product dictionaries. The documented workflow and sampled code support the major stages below; some shared public-method wiring is in omitted source excerpts, so uncertain internal call links are left out.

Main entry points: [`search1688api/sync_session.py`](https://github.com/netkaruma/search1688api/blob/main/search1688api/sync_session.py) (Sync session), [`search1688api/async_session.py`](https://github.com/netkaruma/search1688api/blob/main/search1688api/async_session.py) (Async session), [`search1688api/base.py`](https://github.com/netkaruma/search1688api/blob/main/search1688api/base.py) (Shared session logic), [`search1688api/utils.py`](https://github.com/netkaruma/search1688api/blob/main/search1688api/utils.py) (HTML fallback parsing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Session interfaces"]
  node_sync["Sync session<br/>[sync_session.py]"]
  node_async["Async session<br/>[async_session.py]"]
end

subgraph group_shared["Shared search logic"]
  node_base["Shared session logic<br/>[base.py]"]
  node_sign["Request signing<br/>[base.py]"]
  node_parse["API response parsing<br/>[base.py]"]
  node_cookie_init["Cookie and token setup<br/>[sync_session.py]"]
  node_text_search["Text product search<br/>[sync_session.py]"]
end

subgraph group_image["Image search"]
  node_image_read["Image encoding<br/>[utils.py]"]
  node_image_request["Image upload request<br/>[sync_session.py]"]
  node_image_cookie["Search-page cookies<br/>[sync_session.py]"]
  node_image_search["Image product search<br/>[sync_session.py]"]
  node_fallback["HTML fallback parsing<br/>[utils.py]"]
end

subgraph group_remote["1688 services"]
  node_platform{{"1688 APIs and pages"}}
end

node_user(("Python caller"))

node_user -->|"submits query"| node_sync
node_user -->|"submits query"| node_async
node_sync -->|"uses shared logic"| node_base
node_async -->|"uses shared logic"| node_base
node_base -->|"computes signatures"| node_sign
node_base -->|"parses responses"| node_parse
node_sync -->|"encodes image"| node_image_read
node_async -->|"encodes image"| node_image_read
node_sync -->|"uploads image"| node_image_request
node_async -->|"uploads image"| node_image_request
node_sync -->|"initializes session"| node_cookie_init
node_async -->|"initializes session"| node_cookie_init
node_sync -->|"collects search cookies"| node_image_cookie
node_async -->|"collects search cookies"| node_image_cookie
node_sync -->|"requests image results"| node_image_search
node_async -->|"requests image results"| node_image_search
node_sync -->|"requests text results"| node_text_search
node_async -->|"requests text results"| node_text_search
node_image_request -->|"sends image data"| node_platform
node_cookie_init -->|"requests session cookies"| node_platform
node_image_cookie -->|"requests search pages"| node_platform
node_image_search -->|"requests image products"| node_platform
node_text_search -->|"requests text products"| node_platform
node_image_search -->|"parses fallback HTML"| node_fallback
node_fallback -->|"fetches fallback page"| node_platform
node_user -->|"receives product list"| node_sync
node_user -->|"receives product list"| node_async

click node_sync "https://github.com/netkaruma/search1688api/blob/main/search1688api/sync_session.py"
click node_async "https://github.com/netkaruma/search1688api/blob/main/search1688api/async_session.py"
click node_base "https://github.com/netkaruma/search1688api/blob/main/search1688api/base.py"
click node_sign "https://github.com/netkaruma/search1688api/blob/main/search1688api/base.py"
click node_parse "https://github.com/netkaruma/search1688api/blob/main/search1688api/base.py"
click node_image_read "https://github.com/netkaruma/search1688api/blob/main/search1688api/utils.py"
click node_image_request "https://github.com/netkaruma/search1688api/blob/main/search1688api/sync_session.py"
click node_cookie_init "https://github.com/netkaruma/search1688api/blob/main/search1688api/sync_session.py"
click node_image_cookie "https://github.com/netkaruma/search1688api/blob/main/search1688api/sync_session.py"
click node_image_search "https://github.com/netkaruma/search1688api/blob/main/search1688api/sync_session.py"
click node_text_search "https://github.com/netkaruma/search1688api/blob/main/search1688api/sync_session.py"
click node_fallback "https://github.com/netkaruma/search1688api/blob/main/search1688api/utils.py"

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_sync,node_async toneBlue
class node_base,node_sign,node_parse,node_cookie_init,node_text_search toneAmber
class node_image_read,node_image_request,node_image_cookie,node_image_search,node_fallback toneMint
class node_platform toneRose
class node_user toneIndigo
```

## Components

### Session interfaces

- [Sync session](https://github.com/netkaruma/search1688api/blob/main/search1688api/sync_session.py): `search1688api/sync_session.py`
- [Async session](https://github.com/netkaruma/search1688api/blob/main/search1688api/async_session.py): `search1688api/async_session.py`

### Shared search logic

- [Shared session logic](https://github.com/netkaruma/search1688api/blob/main/search1688api/base.py): `search1688api/base.py`
- [Request signing](https://github.com/netkaruma/search1688api/blob/main/search1688api/base.py): `search1688api/base.py`
- [API response parsing](https://github.com/netkaruma/search1688api/blob/main/search1688api/base.py): `search1688api/base.py`
- [Cookie and token setup](https://github.com/netkaruma/search1688api/blob/main/search1688api/sync_session.py): `search1688api/sync_session.py`
- [Text product search](https://github.com/netkaruma/search1688api/blob/main/search1688api/sync_session.py): `search1688api/sync_session.py`

### Image search

- [Image encoding](https://github.com/netkaruma/search1688api/blob/main/search1688api/utils.py): `search1688api/utils.py`
- [Image upload request](https://github.com/netkaruma/search1688api/blob/main/search1688api/sync_session.py): `search1688api/sync_session.py`
- [Search-page cookies](https://github.com/netkaruma/search1688api/blob/main/search1688api/sync_session.py): `search1688api/sync_session.py`
- [Image product search](https://github.com/netkaruma/search1688api/blob/main/search1688api/sync_session.py): `search1688api/sync_session.py`
- [HTML fallback parsing](https://github.com/netkaruma/search1688api/blob/main/search1688api/utils.py): `search1688api/utils.py`

### 1688 services

- **1688 APIs and pages**

### Other components

- **Python caller**

## Connections

- Python caller → Sync session: submits query
- Python caller → Async session: submits query
- Sync session → Shared session logic: uses shared logic
- Async session → Shared session logic: uses shared logic
- Shared session logic → Request signing: computes signatures
- Shared session logic → API response parsing: parses responses
- Sync session → Image encoding: encodes image
- Async session → Image encoding: encodes image
- Sync session → Image upload request: uploads image
- Async session → Image upload request: uploads image
- Sync session → Cookie and token setup: initializes session
- Async session → Cookie and token setup: initializes session
- Sync session → Search-page cookies: collects search cookies
- Async session → Search-page cookies: collects search cookies
- Sync session → Image product search: requests image results
- Async session → Image product search: requests image results
- Sync session → Text product search: requests text results
- Async session → Text product search: requests text results
- Image upload request → 1688 APIs and pages: sends image data
- Cookie and token setup → 1688 APIs and pages: requests session cookies
- Search-page cookies → 1688 APIs and pages: requests search pages
- Image product search → 1688 APIs and pages: requests image products
- Text product search → 1688 APIs and pages: requests text products
- Image product search → HTML fallback parsing: parses fallback HTML
- HTML fallback parsing → 1688 APIs and pages: fetches fallback page
- Python caller → Sync session: receives product list
- Python caller → Async session: receives product list