# TikTok Programmatic Data Collection

This project provides an automated data pipeline to collect key performance metrics from TikTok using Apify. It includes both a CLI tool for data collection and a React dashboard for visualization.

## Components

- **CLI Tool** (`src/`) - TypeScript Node.js backend for scraping TikTok data
- **UI Dashboard** (`ui/`) - React/Vite frontend for visualization and analytics

## Setup

### CLI Tool

1. **Clone the repository.**
2. **Install dependencies:**
    ```bash
    npm install
    ```
3. **Configure environment variables:**
    Create a `.env` file in the root directory:
    ```env
    APIFY_API_TOKEN=your_apify_token_here
    ```

### UI Dashboard

1. **Navigate to the UI directory:**
    ```bash
    cd ui
    ```
2. **Install dependencies:**
    ```bash
    npm install
    ```
3. **Configure environment variables:**
    Create a `.env.local` file in the `ui/` directory:
    ```env
    VITE_APIFY_API_TOKEN=your_apify_token_here
    ```
4. **Start the development server:**
    ```bash
    npm run dev
    ```

## CLI Usage

The CLI operates in two primary modes: `creator` and `trend`.

### 1. Creator-Level Metrics
Analyzes a creator's performance based on the rolling 7-day median of their recent videos.

**Command:**
```bash
npm start -- --mode creator --target <username>
```

**Example:**
```bash
npm start -- --mode creator --target tiktok
```

**Output:**
- Median Views, Likes, Comments, and Shares
- Average Engagement Rate

### 2. Daily Trend Tracking
Tracks the daily volume and engagement data for a specific sound/song.

**Command:**
```bash
npm start -- --mode trend --target <sound_url_or_id>
```

**Example:**
```bash
npm start -- --mode trend --target https://www.tiktok.com/music/Eenie-Meenie-7454284589998820354
```

**Output:**
- Aggregated metrics (total views, likes, etc.) for the scraped batch
- Daily breakdown of creations and engagement

## UI Dashboard

The React dashboard provides visual analytics for both creator and trend data.

**Commands:**
```bash
cd ui
npm run dev      # Start development server
npm run build    # Build for production
npm run preview  # Preview production build
npm run lint     # Run ESLint
```

**Features:**
- Creator Analysis page for performance metrics
- Trend Analysis page for sound/music tracking
- IndexedDB caching for search history

## Key Metrics

**Creator Analysis (7-day rolling medians):**
- Views, Likes, Comments, Shares
- Engagement Rate: (Likes + Comments + Shares) / Views * 100

**Trend Analysis (daily aggregations per sound):**
- Daily creations, views, likes, comments, shares

## Architecture

### CLI Backend (`src/`)
- `index.ts` - Entry point, parses CLI args
- `scrapers.ts` - Apify client wrapper using `clockworks/tiktok-scraper` actor
- `analytics.ts` - Median/aggregation calculations
- `types.ts` - TypeScript interfaces

### React UI (`ui/src/`)
- `layouts/Dashboard.tsx` - Main layout with sidebar navigation
- `pages/CreatorAnalysis.tsx` - Creator performance analysis
- `pages/TrendAnalysis.tsx` - Sound/trend tracking
- `api/apify.ts` - Browser-side Apify client
- `api/analytics.ts` - Analytics calculations
- `api/db.ts` - IndexedDB caching using Dexie

## Development

- `npm run spike`: Runs a test script (`src/spike.ts`) to verify Apify connectivity