AdClarity
Deterministic TTAM analytics with an optional LLM deep dive
From messy ad exports to auditable performance decisions. AdClarity is a production analytics workflow that transforms TikTok Ads Manager exports into...
Role & Stack: Design and implementation — full-stack. Built with Next.js 15 App Router, TypeScript, React 19, Tailwind CSS v4, Recharts, Papa Parse, SheetJS, ExcelJS, the OpenAI SDK, and Google Generative AI.
Overview: The application uses a client-side upload and server-side analysis pipeline. It normalizes TikTok Ads Manager CSV and XLSX exports, reconstructs efficiency metrics strictly from aggregated totals, and evaluates performance through a rule-based diagnostic tree: CPM → CTR → CPC → CVR → CPI/CPA → ROAS. Instead of averaging unreliable row-level rates, AdClarity derives every KPI from summed raw values. The result is an attribution-aware and auditable analysis surface designed for client success and performance marketing workflows.
The Problem: TikTok Ads Manager exports can contain inconsistent headers, creative-level rows, ambiguous naming conventions, multiple event sources, and precomputed rates that should not be averaged. Turning these exports into trustworthy recommendations typically requires extensive spreadsheet cleanup and manual interpretation.
The Solution: AdClarity creates a structured workflow for ingesting, validating, analyzing, diagnosing, and exporting campaign performance. It preserves metric integrity, prevents attribution double-counting, and translates account data into a scored recommendation roadmap.
Architecture — Ingest & Normalize: CSV and XLSX files pass through automatic header detection and an editable column-mapping layer. Secondary TTAM fields — including app, website, and SKAN purchases and registrations — are detected through header predicates. The normalization pipeline then folds source events into typed fields, prevents common classification errors, and infers operating system from the mapped column, configurable naming conventions, or campaign-name text.
Architecture — Attribution Source of Truth: An EventAttributionConfig determines which event sources contribute to canonical installs, purchases, registrations, and derived CPAs. The default includes platform/app and website data while leaving SKAN disabled to reduce double-counting risk.
Architecture — Naming DSL: A client-editable naming system supports custom delimiters and ordered token roles such as geography, operating system, targeting, and funnel stage. These rules are applied before regular-expression fallbacks.
Architecture — Pivot & Diagnose: The application creates segment-level pivots with spend share and differences from account benchmarks. A deterministic diagnostic engine then produces urgency-tiered recommendations, ranging from immediate actions to opportunities worth continuing.
Architecture — Optional LLM Analysis: A compact, structured version of the deterministic analysis can be passed to OpenAI, Gemini, or both. A comparison layer expands the findings without replacing the underlying rule-based analysis. API keys remain session-scoped in the browser.
Technical Highlights: Metric integrity: all metrics are calculated from aggregated totals — for example, CPI is total spend divided by the selected canonical install count, and purchase and registration CPAs remain separated according to the active attribution configuration. Funnel as UI state: funnel-stage overrides are applied client-side, allowing users to reclassify campaigns without uploading or processing the source file again. Auditable recommendations: the deterministic rule engine is the primary decision layer, and each recommendation can be traced to structured metrics and account benchmarks. Excel export: ExcelJS generates a workbook containing live formulas, campaign-renaming controls, and dictionary sheets for downstream analysis and client delivery.
Deployment: The application is deployed on Vercel. The analysis and LLM deep-dive endpoints use the Node.js runtime.
Outcome: A production CSM workflow that turns a messy, creative-level TTAM export into an auditable and attribution-aware diagnostic surface. The rule engine remains the source of truth, while LLMs serve as an optional second pass over the same structured analysis.
The deterministic rule engine runs without any API key. Optional OpenAI and Gemini deep dives use session-scoped keys entered in the browser and are never persisted.