# davincible/gotiktoklive architecture

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

- Interactive diagram: https://gitdiagram.com/davincible/gotiktoklive
- Repository: https://github.com/davincible/gotiktoklive

## Overview

##### Core components
- TikTok API Wrapper: The central entry point provided by the TikTok struct. This exposes the various functions (TrackUser, TrackRoom, GetUserInfo, GetRoomInfo, NewFeed, etc.) that initiate and manage connections.
- Live Stream Handler: This component (represented by the Live type, as referenced in methods and tests) handles the websocket connection to TikTok’s internal service; it is responsible for receiving events in real time.
- Event Dispatch/Listeners: Several event types (e.g., ChatEvent, UserEvent, GiftEvent, LikeEvent, etc.) are defined and processed. Include an Event Dispatcher component that routes events from the websocket to the end-user (application) consumer.
- Proto/Definitions: There is a “proto” directory which holds the TikTok protocol definitions (tiktok.pb.go and tiktok.proto). Represent this as the message schema layer that translates TikTok’s data formats.
- Downloader Integration: The code includes functions to download livestreams (e.g., live.DownloadStream), which relies on an external FFMpeg binary. This external dependency should be represented.
- Utility Components: Files like utils.go, types.go, requests.go, and const.go likely provide helper functions and types. These can be represented in a “Utilities” module.

##### Relationships and interactions
- The TikTok API Wrapper acts as a client interface that orchestrates interactions. It receives user or room tracking requests and instantiates a Live Stream Handler.
- The Live Stream Handler establishes a websocket connection (and optionally an HTTP connection) to TikTok’s internal WebCast service and routes incoming messages through event channels.
- When live events (such as Chat, User, Gift, etc.) are received, they are parsed (using structures defined in the proto directory and utility code) and then dispatched via the event flow to the consumer’s event handlers.
- The downloader functionality interacts externally with FFMpeg – this can be shown as an outbound dependency from the Live Stream Handler.
- The testing component simulates these interactions to ensure correct behavior of capturing events and handling network communications.

##### Architectural patterns
- Modular Design: The separation among API wrappers, event handlers, utilities, and proto definitions suggests a modular architecture.
- Event-Driven Design: The system is naturally reactive, with events flowing out from the Live Stream Handler to the consumer.
- Dependency Injection / Configuration: Methods for setting debugging, error, info, and warn handlers indicate configurable logging and error processing.
- Use of Go routines and channels emphasizes a concurrent design for handling realtime streaming data.

##### Technologies, frameworks, and external integrations
- Go (the programming language) and its native concurrency model (goroutines and channels).
- WebSocket communication for real-time interactions.
- FFMpeg (as an external command-line dependency) used for the stream download feature.
- Protocol Buffers via the proto directory for data schema definitions.
- The Makefile and go.mod/go.sum for build and dependency management.

##### Specific elements
- Clear labels for every component: TikTok API Wrapper, Live Stream Handler, Event Dispatcher, Proto Definitions, Utilities, and Testing module.
- From TikTok API Wrapper to Live Stream Handler.
- From Live Stream Handler to External TikTok Webcast Service (depicting the WebSocket connection).
- From Live Stream Handler to the Event Dispatcher.
- From Event Dispatcher to client-supplied event-handling functions.
- From Live Stream Handler to the Downloader (with FFMpeg dependency).
- Dependencies between the Utility Components and the API/Handler components.

## Diagram (Mermaid)

```mermaid
graph TD
    %% API Layer
    subgraph "API Layer"
        TiktokAPI["TikTok API Wrapper"]:::api
    end

    %% Connection & Event Layer
    subgraph "Connection & Event Layer"
        LiveHandler["Live Stream Handler"]:::handler
        WSConnection["WSS Connection"]:::handler2
        EventDispatcher["Event Dispatcher"]:::dispatcher
    end

    %% Message Schema Layer
    subgraph "Message Schema Layer"
        Proto1["Proto: tiktok.proto"]:::proto
        Proto2["Proto: tiktok.pb.go"]:::proto
    end

    %% Utilities Layer
    subgraph "Utilities"
        UtilConst["const.go"]:::utility
        UtilTypes["types.go"]:::utility
        UtilRequests["requests.go"]:::utility
        UtilUtils["utils.go"]:::utility
    end

    %% External Integrations Layer
    subgraph "External Integrations"
        ExternalWebcast["TikTok Webcast Service"]:::external
        Downloader["Downloader (FFMpeg)"]:::external
    end

    %% Client & Testing Layer
    subgraph "Client & Testing"
        Consumer["Client Event Handlers"]:::consumer
        Testing["Testing Suite"]:::testing
    end

    %% Interactions
    TiktokAPI -->|"initiates"| LiveHandler
    LiveHandler -->|"opens websocket"| WSConnection
    WSConnection -->|"connects to"| ExternalWebcast
    LiveHandler -->|"dispatches events"| EventDispatcher
    EventDispatcher -->|"triggers"| Consumer
    LiveHandler -->|"invokes"| Downloader

    %% Utility support
    UtilConst --- TiktokAPI
    UtilTypes --- TiktokAPI
    UtilRequests --- LiveHandler
    UtilUtils --- LiveHandler

    %% Schema usage
    LiveHandler -.->|"parses"| Proto1
    LiveHandler -.->|"parses"| Proto2

    %% Testing interactions (dashed lines)
    Testing --- TiktokAPI
    Testing --- LiveHandler
    Testing --- EventDispatcher
    Testing --- WSConnection
    Testing --- Downloader

    %% Click Events
    click TiktokAPI "https://github.com/davincible/gotiktoklive/blob/master/tiktok.go"
    click LiveHandler "https://github.com/davincible/gotiktoklive/blob/master/live.go"
    click WSConnection "https://github.com/davincible/gotiktoklive/blob/master/wss.go"
    click EventDispatcher "https://github.com/davincible/gotiktoklive/blob/master/feed.go"
    click Proto1 "https://github.com/davincible/gotiktoklive/blob/master/proto/tiktok.proto"
    click Proto2 "https://github.com/davincible/gotiktoklive/blob/master/proto/tiktok.pb.go"
    click UtilConst "https://github.com/davincible/gotiktoklive/blob/master/const.go"
    click UtilTypes "https://github.com/davincible/gotiktoklive/blob/master/types.go"
    click UtilRequests "https://github.com/davincible/gotiktoklive/blob/master/requests.go"
    click UtilUtils "https://github.com/davincible/gotiktoklive/blob/master/utils.go"
    click Testing "https://github.com/davincible/gotiktoklive/tree/master/tests"

    %% Styles
    classDef api fill:#f9c,stroke:#333,stroke-width:2px;
    classDef handler fill:#ccf,stroke:#333,stroke-width:2px;
    classDef handler2 fill:#cfc,stroke:#333,stroke-width:2px;
    classDef dispatcher fill:#fcf,stroke:#333,stroke-width:2px;
    classDef proto fill:#ffc,stroke:#333,stroke-width:2px;
    classDef utility fill:#cff,stroke:#333,stroke-width:2px;
    classDef external fill:#c9f,stroke:#333,stroke-width:2px;
    classDef consumer fill:#f99,stroke:#333,stroke-width:2px;
    classDef testing fill:#ddd,stroke:#333,stroke-width:2px;
```
