Use this file as persistent context for LLMs, teammates, or future you. It explains the business domain, the hackathon goal, how datasets relate, and every column in the CSVs (verified against data_science/data/ headers and data_science/data/data_dictionary.csv).

Where to start

• Notebooks and CSV analysis (no Docker required): data_science/README.md
• Postgres + API + UI (Docker): web/README.md

Smadex is a mobile advertising platform, specifically a DSP (Demand-Side Platform). A DSP buys ad inventory on behalf of advertisers (brands that want installs, purchases, signups, etc.). When you see an ad inside a mobile app, a chain of systems decided in near real time whether to show it and which creative to show.

Public messaging often cites extreme scale (for example, millions of bid opportunities per second and sub-100ms decision windows). You do not need live auction logs for this hackathon; the provided CSVs are a fully synthetic teaching dataset.

When an impression becomes available, eligible buyers evaluate a bid request (often includes coarse geo, device/OS, app category, etc.). Buyers respond with bids; a winner is chosen; the winning creative is served. This repository does not contain bid-level auction logs. It contains delivery and outcome statistics after the fact (spend, impressions, clicks, conversions, revenue), plus creative and campaign metadata.

Fatigue means performance degrades over time for a creative that used to work: CTR/CVR/efficiency slip even if targeting is unchanged. Marketers want early warnings and actions (refresh creative, rotate variants, reallocate budget).

Build a product-style demo that helps a marketer answer:

1. Which ads are working right now? — Performance explorer (slice metrics by time, geo, OS, format, etc.).
2. Which ads are dying (fatigue)? — Fatigue detection (trends vs a baseline, not only a static leaderboard).
3. What should I do next? — Recommendations / explainability (actions on creatives, not “what to bid on an auction slot” unless you bring external auction data).

Bonus differentiator: combine asset_file PNGs with performance to explain why patterns exist (vision model, human review UI, clustering, etc.).

Framing: this is not a perfect Kaggle-style leaderboard problem. Strong projects blend analysis + simple models + explainability + UX.

From data_science/data/README.md (canonical counts):

Uniformity quirk: every advertiser has 5 campaigns and every campaign has 6 creatives by design. Portfolio-size comparisons are meaningless; compare performance and creative traits instead.

advertisers.csv
  └── advertiser_id ──< campaigns.csv
                          └── campaign_id ──< creatives.csv
                                                └── creative_id ──< creative_daily_country_os_stats.csv
                                                (also join daily rows by campaign_id for sanity)

Practical joins

• campaigns.advertiser_id -> advertisers.advertiser_id
• creatives.campaign_id -> campaigns.campaign_id
• creative_daily_country_os_stats.creative_id -> creatives.creative_id
• creative_daily_country_os_stats.campaign_id -> campaigns.campaign_id (redundant but useful)

Pre-aggregated convenience tables

• creative_summary.csv = one row per creative: lifetime totals, decay features, synthetic labels (creative_status, fatigue_day, perf_score), plus creative metadata columns mirrored from creatives.csv.
• campaign_summary.csv = one row per campaign: lifetime totals + campaign metadata.

Authoritative column gloss: data_science/data/data_dictionary.csv (machine-readable). The sections below match actual CSV headers in this repo.

Rich metadata + engineered visual features (synthetic) for each creative. Includes path to a synthetic PNG.

Identity and delivery

Concept / copy

Visual scores (roughly 0-1 floats unless noted)

Binary flags (0/1)

Grain: one row per (date, creative_id, country, os) (also carries campaign_id).

Important analytical caveat: impressions_last_7d is a rolling field defined by the dataset authors. Do not blindly sum it across rows the same way you sum impressions; for rollups you usually aggregate impressions, spend_usd, etc., and compute your own rolling windows if needed.

Grain: one row per creative_id. Contains:

• Lifetime totals and overall rates (overall_*).
• First-week vs last-week decay features (first_7d_*, last_7d_*, *_decay_pct).
• Synthetic supervision-ish fields: creative_status, fatigue_day, perf_score.
• Creative metadata duplicated for modeling convenience (same themes as creatives.csv).

IDs and labels

Lifetime totals

Fatigue / momentum features

Creative metadata columns (same families as creatives.csv)

Includes: width, height, language, creative_launch_date, theme, hook_type, cta_text, headline, subhead, dominant_color, emotional_tone, duration_sec, text_density, copy_length_chars, readability/brand/clutter/novelty/motion scores, counts, has_* flags, asset_file.

Volume helpers

Grain: one row per campaign_id. Campaign metadata plus rolled-up performance.

Row-wise mapping of (file_name, column_name, data_type, description). Treat it as the schema glossary for tools and LLMs.

From data_science/data/README.md and dataset design:

1. fatigue_day only exists for creative_status == fatigued. Other statuses leave it blank by construction.
2. Uniform portfolio sizes make “who is biggest” questions meaningless; compare KPIs and creative features.
3. Synthetic data: patterns are realistic for learning, but this is not a production benchmark.
4. Hidden generator variables are not shipped; do not expect to invert the full generative process from public files alone.

Shorter guides with the same domain story in context:

• data_science/README.md — data science tree, each CSV explained, joins.
• web/README.md — Docker, Postgres tables vs CSVs, empty vs non-empty DB seeding behavior.

Layout:

• data_science/ — CSVs under data_science/data/ (and assets/), plus notebooks under data_science/notebooks/. Use this tree for analysis and experiments without running the web stack.
• web/ — Production-style stack: web/backend/ (FastAPI: /api/performance/*, …), web/frontend/ (React + Vite UI), web/docker-compose.yml, and web/db/schema.sql (PostgreSQL DDL: one public table per seeded CSV in data_science/data/, excluding data_dictionary.csv).

Web API data source

The API always uses PostgreSQL via DATABASE_URL. It does not read CSV files at request time. CSVs in data_science/data/ are the bulk seed source when the fact table is empty (see below).

Run locally (API + UI against Postgres)

# Terminal A — Postgres must already exist and be seeded (see bootstrap below)
cd web/backend && pip install -r requirements.txt && uvicorn main:app --reload --port 8000

# Terminal B
cd web/frontend && npm install && npm run dev

Seed Postgres from CSV (local, without full Docker stack)

From the repo root, with a venv that has web/backend dependencies installed:

export DATABASE_URL=postgresql+psycopg2://USER:PASS@localhost:5432/smadex
export IMPORT_DATA_DIR=/absolute/path/to/HACK_UPC_SMADEX/data_science/data
python web/backend/scripts/bootstrap_pg_from_csv.py

If IMPORT_DATA_DIR is unset, the script defaults to data_science/data/ relative to the repository root. It applies web/db/schema.sql, then loads all CSV-backed tables when the fact table is empty, or backfills empty summary/dictionary tables when the fact table already has rows.

Run with Docker (Postgres + API + UI)

cd web && docker compose up --build
# UI:  http://localhost:8080  (nginx proxies /api to backend)
# API: http://localhost:8000
# Postgres: localhost:5432  user/password/db: smadex / smadex / smadex

Compose mounts ../data_science/data read-only at /import on the backend. On each backend start, scripts.ensure_db_seeded runs: if any seed table is missing it applies web/db/schema.sql; if creative_daily_country_os_stats has at least one row, the full truncate+reload is skipped and empty tables (e.g. new campaign_summary) are backfilled from CSV; if the fact table is empty, all seven seeded tables are truncated and the corresponding CSVs are loaded from /import (data_dictionary.csv is not loaded into Postgres).

Reset the database (force a full re-seed on next start): cd web && docker compose down -v then up again (removes the named volume smadex_pgdata).

When your team changes the product, append short dated notes here:

• Which KPI definitions you standardized (CTR denominators, CPA smoothing rules).
• Any new derived tables you materialize (daily creative totals, per-country baselines).
• Model cards (inputs, labels, leakage checks) if you add ML.

Keeping this README current is cheaper than re-explaining the domain in every chat.