Trend Radar

Problem

A regional marketing team needed to know which sounds, formats, and topics were rising on TikTok early enough to act on them, and it needed to trust the answer. A dashboard that lets a language model decide what counts as a trend will eventually present a confident guess as a finding. Trend Radar is built so that cannot happen.

Approach

Measurement decides, LLMs describe. Deterministic signals decide every verdict: caption n-gram clustering, creator spread, adoption curves, and freshness. A model can name a mechanic or demote a measured riser, but it can never admit an entity the measurements rejected, and it never writes URLs, IDs, counts, or provenance.

Four more rules follow from that one. Never invent: an unknown value renders as a blank marker, never a guess or a zero, and every figure carries its provenance. No silent discarding: lifecycle stages are tags rather than gates, and a safety verdict demotes or annotates a result rather than deleting it. Self-calibration over magic constants: thresholds come from each lane's own trailing spend history. Degrade honestly: every data store has a labeled fallback, so a failed pull serves the last good state with a stale badge instead of a blank surface.

Architecture

Collectors run on the official TikTok API for Business and commercial data vendors across 8 discovery lanes, with cursor-paged retrieval, retry with exponential backoff, and per-day idempotency. A two-stage screen follows: a Claude-based brand-fit gate returns structured go or no-go verdicts against voice and brand guardrails, then a computer vision and reasoning layer scores GCC cultural applicability, in Arabic and English.

Cost governance sits in PostgreSQL: per-run spend meters, a cross-process daily budget ledger, and balance-gated runs. Combined data and inference spend holds to a fixed single-digit-dollar daily budget. The system ships as a Dockerized collector with 5 scheduled cron lanes, 16 versioned SQL migrations, and 315 automated tests in an npm workspaces monorepo.

This repository

The public repository is a sanitized engineering extract. The client is referred to only as "the brand", and its identity, prompts, product catalog, competitor lane, dashboard UI, and all collected data are removed. The detection engine, collectors, cost governance, and database schema are present with their tests.

My role

I architected and built the system on my own, and scoped it directly with the marketing, creative, and innovation stakeholders who used it, iterating in short feedback cycles.