# l-portet/tiktok-warmup-bot architecture

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

- Interactive diagram: https://gitdiagram.com/l-portet/tiktok-warmup-bot
- Repository: https://github.com/l-portet/tiktok-warmup-bot

## Overview

##### Project Type and Purpose
- Type: Open-source Node.js command-line automation tool.
- Purpose: Warm up a TikTok account by automating “swipe,” “like,” “open comments,” etc., via iOS Voice Control using pre-generated MP3 voice-action files.

##### File Structure
- Root files:
– index.js (main application logic)
– package.json / package-lock.json (dependencies & scripts)
- Asset folder:
– voice-actions/ (contains MP3 files for each voice command)
- Config & scripts:
– README.md for usage instructions
– LICENSE.md for license terms

##### Key Components
a. Configuration & CLI Layer
– index.js reads command-line flags (`--duration`, `--sequence`)
– Exposes ENV or in-code constants (VOICE_ACTIONS config)
b. Scheduler & Action-Selection Module
– Default “swipe next” loop
– Randomized intervals for other actions (likePost, openComments, etc.)
c. Asset Manager
– voice-actions folder holding MP3 files
– Mapping between action names and MP3 file paths
d. Audio Playback Engine
– Uses OS command (e.g., `ffplay`, `afplay`, or Node audio module) to play MP3
e. OS Voice Control Interface
– iOS Voice Control listens for played audio
– Translates audio to touch events in the TikTok app
f. TikTok Application (External System)
– Receives touch events and updates UI accordingly
g. External Dependencies
– ElevenLabs (used at generation time for voice clips)
– Node.js runtime

##### Relationships & Data Flow
1) User invokes `npm start -- --duration=30 --sequence=…`
2) index.js parses flags → sets duration & sequence
3) Scheduler selects next action based on intervals or explicit sequence
4) Asset Manager retrieves corresponding MP3 from voice-actions/
5) Audio Playback Engine plays MP3 through speakers
6) iOS Voice Control hears the command → injects the corresponding UI event into TikTok
7) TikTok UI transitions (swipe, like, open comments, etc.)
8) Scheduler resets intervals & repeats until duration elapses

##### Architectural Patterns & Principles
- Modular Separation:
– CLI/Config, Scheduler, Asset Management, Playback are distinct modules
- Event-Driven Loop:
– Each voice action is an “event” scheduled at random intervals
- Extensibility Points:
– New actions: drop a new MP3 into voice-actions/ and add mapping in index.js
– Configuration flags: easily add new flags for frequency control

##### Putting It All Together
- Top-left: User & CLI invocation
- Middle tier (left to right):
[Configuration & CLI Parser] → [Scheduler & Logic] → [Asset Manager] → [Audio Playback Engine]
- Bottom tier:
[iOS Voice Control] → [TikTok App on Device]

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Local Machine Modules
    subgraph LM["Local Machine"]
        direction TB
        U["User CLI Invocation"]:::codeModule
        Config["Configuration & CLI Parser"]:::codeModule
        Scheduler["Scheduler & Action-Selection Module"]:::codeModule
        Asset["Asset Manager"]:::asset
        Playback["Audio Playback Engine"]:::codeModule
        ExternalDeps["External Dependencies\n(Node.js runtime & ElevenLabs)"]:::codeModule
        Docs["Documentation & Scripts"]:::codeModule
    end

    %% External Device & App
    subgraph ED["External Device & App"]
        direction TB
        IOS["iOS Voice Control"]:::external
        TikTok["TikTok App on Device"]:::external
    end

    %% Data Flow
    U -->|"invoke CLI"| Config
    Config -->|"parse flags"| Scheduler
    Scheduler -->|"select action"| Asset
    Asset -->|"retrieve MP3"| Playback
    Playback -->|"play MP3"| IOS
    IOS -->|"inject touch event"| TikTok

    %% Auxiliary Flows
    Config -.->|uses| ExternalDeps
    Config -.->|reads| Docs

    %% Click Events
    click Config "https://github.com/l-portet/tiktok-warmup-bot/blob/master/index.js"
    click Config "https://github.com/l-portet/tiktok-warmup-bot/blob/master/package.json"
    click Scheduler "https://github.com/l-portet/tiktok-warmup-bot/blob/master/index.js"
    click Asset "https://github.com/l-portet/tiktok-warmup-bot/tree/master/voice-actions/"
    click Playback "https://github.com/l-portet/tiktok-warmup-bot/blob/master/index.js"
    click ExternalDeps "https://github.com/l-portet/tiktok-warmup-bot/blob/master/package.json"
    click ExternalDeps "https://github.com/l-portet/tiktok-warmup-bot/blob/master/package-lock.json"
    click Docs "https://github.com/l-portet/tiktok-warmup-bot/blob/master/README.md"
    click Docs "https://github.com/l-portet/tiktok-warmup-bot/blob/master/LICENSE.md"

    %% Styles
    classDef codeModule fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef asset fill:#98FB98,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px
    style LM stroke-dasharray: 5 5
    style ED stroke-dasharray: 5 5
```
