# okdargy/fxtiktok architecture

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

- Interactive diagram: https://gitdiagram.com/okdargy/fxtiktok
- Repository: https://github.com/okdargy/fxtiktok

## Overview

fxTikTok is a TikTok-to-embed service: a request for a TikTok link is routed by the Worker, TikTok data is fetched and parsed, then page templates produce metadata for Discord and other embed consumers. Generated media and ActivityPub-style responses are served by a separate offload application. The README also documents direct media, slideshow pagination, captions, high-quality playback, profile/live embeds, and Prometheus metrics. Edges reflect the excerpts and source-index references; unsampled behavior is not inferred.

Main entry points: [`src/index.ts`](https://github.com/okdargy/fxtiktok/blob/hono-rewrite/src/index.ts) (Worker routes), [`src/services/tiktok.ts`](https://github.com/okdargy/fxtiktok/blob/hono-rewrite/src/services/tiktok.ts) (TikTok scraping), [`src/generate.ts`](https://github.com/okdargy/fxtiktok/blob/hono-rewrite/src/generate.ts) (Media routes), [`src/templates/index.ts`](https://github.com/okdargy/fxtiktok/blob/hono-rewrite/src/templates/index.ts) (Template exports)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_request["Request routing"]
  node_worker["Worker routes<br/>[index.ts]"]
  node_generation["Media routes<br/>[generate.ts]"]
  node_offload["Offload server<br/>[offload.ts]"]
end

subgraph group_data["TikTok data"]
  node_scraper["TikTok scraping<br/>[tiktok.ts]"]
  node_schemas["TikTok data types"]
  node_api_types["API types<br/>[API.ts]"]
end

subgraph group_embed["Embed and media output"]
  node_activity["Activity builder"]
  node_alternate["Alternate metadata"]
  node_video_page["Video embed<br/>[VideoResponse.tsx]"]
  node_profile_page["Profile embed"]
  node_live_page["Live embed<br/>[LiveResponse.tsx]"]
  node_other_pages["Status pages"]
  node_template_router["Template exports<br/>[index.ts]"]
  node_meta["Metadata helper<br/>[metaHelper.tsx]"]
  node_format["Formatting<br/>[format.ts]"]
  node_activity_ids["Activity IDs<br/>[activityId.ts]"]
end

subgraph group_ops["Operations"]
  node_metrics["Request metrics<br/>[metrics.ts]"]
end

node_consumer(("Embed consumer"))
node_tiktok["TikTok"]
node_redis[("Redis cache")]
node_prometheus["Prometheus"]

node_consumer -->|"requests embeds"| node_worker
node_worker -->|"fetches TikTok data"| node_scraper
node_scraper -->|"fetches pages"| node_tiktok
node_scraper -->|"reads and writes cache"| node_redis
node_worker -->|"renders responses"| node_template_router
node_worker -->|"renders profile"| node_profile_page
node_template_router -->|"exports template"| node_video_page
node_template_router -->|"exports template"| node_live_page
node_template_router -->|"exports templates"| node_other_pages
node_video_page -->|"builds metadata"| node_meta
node_profile_page -->|"builds metadata"| node_meta
node_live_page -->|"builds metadata"| node_meta
node_video_page -->|"uses page count"| node_activity
node_profile_page -->|"formats counts"| node_format
node_live_page -->|"formats live stats"| node_format
node_meta -->|"builds activity ID"| node_activity_ids
node_worker -.->|"mounts media routes"| node_generation
node_generation -->|"fetches video data"| node_scraper
node_generation -->|"builds activity response"| node_activity
node_generation -->|"builds alternate response"| node_alternate
node_activity -->|"fetches video data"| node_scraper
node_offload -->|"serves media routes"| node_generation
node_offload -->|"serves activity output"| node_activity
node_worker -->|"wraps routes"| node_metrics
node_consumer -->|"scrapes metrics"| node_metrics
node_metrics -->|"exposes metrics"| node_prometheus
node_scraper -->|"parses typed data"| node_schemas
node_schemas -.->|"includes API schema"| node_api_types

click node_worker "https://github.com/okdargy/fxtiktok/blob/hono-rewrite/src/index.ts"
click node_generation "https://github.com/okdargy/fxtiktok/blob/hono-rewrite/src/generate.ts"
click node_offload "https://github.com/okdargy/fxtiktok/blob/hono-rewrite/src/offload.ts"
click node_scraper "https://github.com/okdargy/fxtiktok/blob/hono-rewrite/src/services/tiktok.ts"
click node_schemas "https://github.com/okdargy/fxtiktok/tree/hono-rewrite/src/types"
click node_api_types "https://github.com/okdargy/fxtiktok/blob/hono-rewrite/src/types/API.ts"
click node_activity "https://github.com/okdargy/fxtiktok/blob/hono-rewrite/src/util/generateActivity.tsx"
click node_alternate "https://github.com/okdargy/fxtiktok/blob/hono-rewrite/src/util/generateAlternate.tsx"
click node_video_page "https://github.com/okdargy/fxtiktok/blob/hono-rewrite/src/templates/pages/VideoResponse.tsx"
click node_profile_page "https://github.com/okdargy/fxtiktok/blob/hono-rewrite/src/templates/pages/ProfileResponse.tsx"
click node_live_page "https://github.com/okdargy/fxtiktok/blob/hono-rewrite/src/templates/pages/LiveResponse.tsx"
click node_other_pages "https://github.com/okdargy/fxtiktok/tree/hono-rewrite/src/templates/pages"
click node_template_router "https://github.com/okdargy/fxtiktok/blob/hono-rewrite/src/templates/index.ts"
click node_meta "https://github.com/okdargy/fxtiktok/blob/hono-rewrite/src/util/metaHelper.tsx"
click node_format "https://github.com/okdargy/fxtiktok/blob/hono-rewrite/src/util/format.ts"
click node_activity_ids "https://github.com/okdargy/fxtiktok/blob/hono-rewrite/src/util/activityId.ts"
click node_metrics "https://github.com/okdargy/fxtiktok/blob/hono-rewrite/src/metrics.ts"

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_worker,node_generation,node_offload toneBlue
class node_scraper,node_schemas,node_api_types,node_redis toneAmber
class node_activity,node_alternate,node_video_page,node_profile_page,node_live_page,node_other_pages,node_template_router,node_meta,node_format,node_activity_ids toneMint
class node_metrics toneRose
class node_consumer,node_tiktok,node_prometheus toneIndigo
```

## Components

### Request routing

- [Worker routes](https://github.com/okdargy/fxtiktok/blob/hono-rewrite/src/index.ts): `src/index.ts`
- [Media routes](https://github.com/okdargy/fxtiktok/blob/hono-rewrite/src/generate.ts): `src/generate.ts`
- [Offload server](https://github.com/okdargy/fxtiktok/blob/hono-rewrite/src/offload.ts): `src/offload.ts`

### TikTok data

- [TikTok scraping](https://github.com/okdargy/fxtiktok/blob/hono-rewrite/src/services/tiktok.ts): `src/services/tiktok.ts`
- [TikTok data types](https://github.com/okdargy/fxtiktok/tree/hono-rewrite/src/types): `src/types`
- [API types](https://github.com/okdargy/fxtiktok/blob/hono-rewrite/src/types/API.ts): `src/types/API.ts`

### Embed and media output

- [Activity builder](https://github.com/okdargy/fxtiktok/blob/hono-rewrite/src/util/generateActivity.tsx): `src/util/generateActivity.tsx`
- [Alternate metadata](https://github.com/okdargy/fxtiktok/blob/hono-rewrite/src/util/generateAlternate.tsx): `src/util/generateAlternate.tsx`
- [Video embed](https://github.com/okdargy/fxtiktok/blob/hono-rewrite/src/templates/pages/VideoResponse.tsx): `src/templates/pages/VideoResponse.tsx`
- [Profile embed](https://github.com/okdargy/fxtiktok/blob/hono-rewrite/src/templates/pages/ProfileResponse.tsx): `src/templates/pages/ProfileResponse.tsx`
- [Live embed](https://github.com/okdargy/fxtiktok/blob/hono-rewrite/src/templates/pages/LiveResponse.tsx): `src/templates/pages/LiveResponse.tsx`
- [Status pages](https://github.com/okdargy/fxtiktok/tree/hono-rewrite/src/templates/pages): `src/templates/pages`
- [Template exports](https://github.com/okdargy/fxtiktok/blob/hono-rewrite/src/templates/index.ts): `src/templates/index.ts`
- [Metadata helper](https://github.com/okdargy/fxtiktok/blob/hono-rewrite/src/util/metaHelper.tsx): `src/util/metaHelper.tsx`
- [Formatting](https://github.com/okdargy/fxtiktok/blob/hono-rewrite/src/util/format.ts): `src/util/format.ts`
- [Activity IDs](https://github.com/okdargy/fxtiktok/blob/hono-rewrite/src/util/activityId.ts): `src/util/activityId.ts`

### Operations

- [Request metrics](https://github.com/okdargy/fxtiktok/blob/hono-rewrite/src/metrics.ts): `src/metrics.ts`

### Other components

- **Embed consumer**
- **TikTok**
- **Redis cache**
- **Prometheus**

## Connections

- Embed consumer → Worker routes: requests embeds (evidence: `README.md`)
- Worker routes → TikTok scraping: fetches TikTok data (evidence: `src/index.ts`)
- TikTok scraping → TikTok: fetches pages (evidence: `src/services/tiktok.ts`)
- TikTok scraping → Redis cache: reads and writes cache (evidence: `src/services/tiktok.ts`)
- Worker routes → Template exports: renders responses (evidence: `src/index.ts`)
- Worker routes → Profile embed: renders profile (evidence: `src/index.ts`)
- Template exports → Video embed: exports template (evidence: `src/templates/index.ts`)
- Template exports → Live embed: exports template (evidence: `src/templates/index.ts`)
- Template exports → Status pages: exports templates (evidence: `src/templates/index.ts`)
- Video embed → Metadata helper: builds metadata (evidence: `src/templates/pages/VideoResponse.tsx`)
- Profile embed → Metadata helper: builds metadata (evidence: `src/templates/pages/ProfileResponse.tsx`)
- Live embed → Metadata helper: builds metadata (evidence: `src/templates/pages/LiveResponse.tsx`)
- Video embed → Activity builder: uses page count (evidence: `src/templates/pages/VideoResponse.tsx`)
- Profile embed → Formatting: formats counts (evidence: `src/templates/pages/ProfileResponse.tsx`)
- Live embed → Formatting: formats live stats (evidence: `src/templates/pages/LiveResponse.tsx`)
- Metadata helper → Activity IDs: builds activity ID (evidence: `src/util/metaHelper.tsx`)
- Worker routes → Media routes: mounts media routes (evidence: `src/index.ts`)
- Media routes → TikTok scraping: fetches video data (evidence: `src/generate.ts`)
- Media routes → Activity builder: builds activity response (evidence: `src/generate.ts`)
- Media routes → Alternate metadata: builds alternate response (evidence: `src/generate.ts`)
- Activity builder → TikTok scraping: fetches video data (evidence: `src/util/generateActivity.tsx`)
- Offload server → Media routes: serves media routes (evidence: `src/offload.ts`)
- Offload server → Activity builder: serves activity output (evidence: `src/offload.ts`)
- Worker routes → Request metrics: wraps routes (evidence: `src/index.ts`)
- Embed consumer → Request metrics: scrapes metrics (evidence: `README.md`)
- Request metrics → Prometheus: exposes metrics (evidence: `README.md`)
- TikTok scraping → TikTok data types: parses typed data (evidence: `src/services/tiktok.ts`)
- TikTok data types → API types: includes API schema
