# cv-cat/tiktokapis architecture

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

- Interactive diagram: https://gitdiagram.com/cv-cat/tiktokapis
- Repository: https://github.com/cv-cat/tiktokapis

## Overview

TikTok APIs is a Python client library for reading TikTok Web data and performing supported interactions, Creator publishing, live/IM messaging, and read-only Shop lookups. The principal workflow is: provide a browser Cookie and same-session state, construct a signed request through the API and request-building layers, then receive a TikTok response. The graph preserves the README’s separate product areas; unsampled endpoint implementations are represented at their documented source paths, with only documented or excerpt-supported wiring shown.

Main entry points: [`api/tiktok_web.py`](https://github.com/cv-cat/tiktokapis/blob/master/api/tiktok_web.py) (TikTok Web API), [`builder/signer.py`](https://github.com/cv-cat/tiktokapis/blob/master/builder/signer.py) (Signature dispatch), [`utils/http_client.py`](https://github.com/cv-cat/tiktokapis/blob/master/utils/http_client.py) (HTTP adapter), [`builder/auth.py`](https://github.com/cv-cat/tiktokapis/blob/master/builder/auth.py) (Browser auth state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API capabilities"]
  node_webapi["TikTok Web API<br/>[tiktok_web.py]"]
  node_compat["Compatibility API<br/>[tiktok.py]"]
  node_content["Content and users<br/>[tiktok_web.py]"]
  node_interaction["Comments and engagement<br/>[tiktok_web.py]"]
  node_creator["Creator publishing<br/>[tiktok_web.py]"]
  node_live["Live data and events<br/>[tiktok_web.py]"]
  node_im["Direct messages<br/>[tiktok_web.py]"]
  node_shop["Shop read APIs<br/>[tiktok_web.py]"]
  node_login["Login placeholders<br/>[tiktok_login.py]"]
  node_chat["Chat entry points<br/>[tiktok_chat.py]"]
end

subgraph group_request["Request construction"]
  node_auth["Browser auth state<br/>[auth.py]"]
  node_webbuilder["Headers and params<br/>[header.py]"]
  node_parambuilder["Query construction<br/>[params.py]"]
  node_signer["Signature dispatch<br/>[signer.py]"]
end

subgraph group_signing["Signing runtime"]
  node_pure["Python signatures<br/>[pure.py]"]
  node_signsdk["Web SDK bridge<br/>[sign.js]"]
  node_shopsdk["Shop BSID runtime<br/>[run.js]"]
  node_aws["AWS signing<br/>[aws_v4.py]"]
  node_ticket["Ticket guard<br/>[ticket_guard.py]"]
  node_protobuf["IM protocol"]
end

subgraph group_transport["Transport"]
  node_http["HTTP adapter<br/>[http_client.py]"]
end

node_user(("Client application"))
node_tiktok(("TikTok services"))
node_websocket(("TikTok WebSockets"))

node_user -->|"supplies session"| node_auth
node_user -->|"calls API"| node_webapi
node_webapi -->|"uses state"| node_auth
node_compat -->|"delegates"| node_webapi
node_webapi -->|"serves"| node_content
node_webapi -->|"serves"| node_interaction
node_webapi -->|"publishes"| node_creator
node_webapi -->|"serves"| node_live
node_webapi -->|"serves"| node_im
node_webapi -->|"reads"| node_shop
node_user -->|"calls placeholder"| node_login
node_user -->|"calls"| node_chat
node_webapi -->|"builds headers"| node_webbuilder
node_webapi -->|"builds queries"| node_parambuilder
node_webapi -->|"requests signatures"| node_signer
node_signer -->|"computes"| node_pure
node_signer -.->|"runs SDK"| node_signsdk
node_signer -.->|"runs BSID"| node_shopsdk
node_webapi -->|"signs Shop requests"| node_aws
node_webapi -->|"checks ticket guard"| node_ticket
node_im -->|"encodes messages"| node_protobuf
node_webapi -->|"sends HTTP"| node_http
node_http -->|"transfers requests"| node_tiktok
node_live -->|"connects"| node_websocket
node_im -->|"connects"| node_websocket

click node_auth "https://github.com/cv-cat/tiktokapis/blob/master/builder/auth.py"
click node_webapi "https://github.com/cv-cat/tiktokapis/blob/master/api/tiktok_web.py"
click node_compat "https://github.com/cv-cat/tiktokapis/blob/master/api/tiktok.py"
click node_content "https://github.com/cv-cat/tiktokapis/blob/master/api/tiktok_web.py"
click node_interaction "https://github.com/cv-cat/tiktokapis/blob/master/api/tiktok_web.py"
click node_creator "https://github.com/cv-cat/tiktokapis/blob/master/api/tiktok_web.py"
click node_live "https://github.com/cv-cat/tiktokapis/blob/master/api/tiktok_web.py"
click node_im "https://github.com/cv-cat/tiktokapis/blob/master/api/tiktok_web.py"
click node_shop "https://github.com/cv-cat/tiktokapis/blob/master/api/tiktok_web.py"
click node_login "https://github.com/cv-cat/tiktokapis/blob/master/api/tiktok_login.py"
click node_chat "https://github.com/cv-cat/tiktokapis/blob/master/api/tiktok_chat.py"
click node_webbuilder "https://github.com/cv-cat/tiktokapis/blob/master/builder/header.py"
click node_parambuilder "https://github.com/cv-cat/tiktokapis/blob/master/builder/params.py"
click node_signer "https://github.com/cv-cat/tiktokapis/blob/master/builder/signer.py"
click node_pure "https://github.com/cv-cat/tiktokapis/blob/master/signing/pure.py"
click node_signsdk "https://github.com/cv-cat/tiktokapis/blob/master/signing/env/sign.js"
click node_shopsdk "https://github.com/cv-cat/tiktokapis/blob/master/reverse/tiktok_shop_bsid/env/run.js"
click node_aws "https://github.com/cv-cat/tiktokapis/blob/master/signing/aws_v4.py"
click node_ticket "https://github.com/cv-cat/tiktokapis/blob/master/signing/ticket_guard.py"
click node_protobuf "https://github.com/cv-cat/tiktokapis/blob/master/static/Tiktok_Request_pb2.py"
click node_http "https://github.com/cv-cat/tiktokapis/blob/master/utils/http_client.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_webapi,node_compat,node_content,node_interaction,node_creator,node_live,node_im,node_shop,node_login,node_chat,node_user toneBlue
class node_auth,node_webbuilder,node_parambuilder,node_signer toneAmber
class node_pure,node_signsdk,node_shopsdk,node_aws,node_ticket,node_protobuf toneMint
class node_http toneRose
class node_tiktok,node_websocket toneIndigo
```

## Components

### API capabilities

- [TikTok Web API](https://github.com/cv-cat/tiktokapis/blob/master/api/tiktok_web.py): `api/tiktok_web.py`
- [Compatibility API](https://github.com/cv-cat/tiktokapis/blob/master/api/tiktok.py): `api/tiktok.py`
- [Content and users](https://github.com/cv-cat/tiktokapis/blob/master/api/tiktok_web.py): `api/tiktok_web.py`
- [Comments and engagement](https://github.com/cv-cat/tiktokapis/blob/master/api/tiktok_web.py): `api/tiktok_web.py`
- [Creator publishing](https://github.com/cv-cat/tiktokapis/blob/master/api/tiktok_web.py): `api/tiktok_web.py`
- [Live data and events](https://github.com/cv-cat/tiktokapis/blob/master/api/tiktok_web.py): `api/tiktok_web.py`
- [Direct messages](https://github.com/cv-cat/tiktokapis/blob/master/api/tiktok_web.py): `api/tiktok_web.py`
- [Shop read APIs](https://github.com/cv-cat/tiktokapis/blob/master/api/tiktok_web.py): `api/tiktok_web.py`
- [Login placeholders](https://github.com/cv-cat/tiktokapis/blob/master/api/tiktok_login.py): `api/tiktok_login.py`
- [Chat entry points](https://github.com/cv-cat/tiktokapis/blob/master/api/tiktok_chat.py): `api/tiktok_chat.py`

### Request construction

- [Browser auth state](https://github.com/cv-cat/tiktokapis/blob/master/builder/auth.py): `builder/auth.py`
- [Headers and params](https://github.com/cv-cat/tiktokapis/blob/master/builder/header.py): `builder/header.py`
- [Query construction](https://github.com/cv-cat/tiktokapis/blob/master/builder/params.py): `builder/params.py`
- [Signature dispatch](https://github.com/cv-cat/tiktokapis/blob/master/builder/signer.py): `builder/signer.py`

### Signing runtime

- [Python signatures](https://github.com/cv-cat/tiktokapis/blob/master/signing/pure.py): `signing/pure.py`
- [Web SDK bridge](https://github.com/cv-cat/tiktokapis/blob/master/signing/env/sign.js): `signing/env/sign.js`
- [Shop BSID runtime](https://github.com/cv-cat/tiktokapis/blob/master/reverse/tiktok_shop_bsid/env/run.js): `reverse/tiktok_shop_bsid/env/run.js`
- [AWS signing](https://github.com/cv-cat/tiktokapis/blob/master/signing/aws_v4.py): `signing/aws_v4.py`
- [Ticket guard](https://github.com/cv-cat/tiktokapis/blob/master/signing/ticket_guard.py): `signing/ticket_guard.py`
- [IM protocol](https://github.com/cv-cat/tiktokapis/blob/master/static/Tiktok_Request_pb2.py): `static/Tiktok_Request_pb2.py`

### Transport

- [HTTP adapter](https://github.com/cv-cat/tiktokapis/blob/master/utils/http_client.py): `utils/http_client.py`

### Other components

- **Client application**
- **TikTok services**
- **TikTok WebSockets**

## Connections

- Client application → Browser auth state: supplies session
- Client application → TikTok Web API: calls API
- TikTok Web API → Browser auth state: uses state
- Compatibility API → TikTok Web API: delegates
- TikTok Web API → Content and users: serves
- TikTok Web API → Comments and engagement: serves
- TikTok Web API → Creator publishing: publishes
- TikTok Web API → Live data and events: serves
- TikTok Web API → Direct messages: serves
- TikTok Web API → Shop read APIs: reads
- Client application → Login placeholders: calls placeholder
- Client application → Chat entry points: calls
- TikTok Web API → Headers and params: builds headers
- TikTok Web API → Query construction: builds queries
- TikTok Web API → Signature dispatch: requests signatures
- Signature dispatch → Python signatures: computes
- Signature dispatch → Web SDK bridge: runs SDK
- Signature dispatch → Shop BSID runtime: runs BSID
- TikTok Web API → AWS signing: signs Shop requests
- TikTok Web API → Ticket guard: checks ticket guard
- Direct messages → IM protocol: encodes messages
- TikTok Web API → HTTP adapter: sends HTTP
- HTTP adapter → TikTok services: transfers requests
- Live data and events → TikTok WebSockets: connects
- Direct messages → TikTok WebSockets: connects