AdPulse — the spec

An internal analytics dashboard that pulls Amazon Ads data and surfaces sales and ad performance across three time horizons — last week, last month, last year — in one place. Built for Billy Lau's internal team, it replaces manual spreadsheet reviews with automated trend signals and AI-generated action items so the team can run their weekly and monthly performance process entirely inside the tool.

---

Decisions locked

---

The core loop

1. Team member opens AdPulse; the dashboard loads with the latest synced Amazon Ads data.
2. Side-by-side comparison cards display key metrics (spend, ROAS, ACOS, revenue, impressions, clicks) for last week, last month, and last year.
3. Automated trend detection flags each metric red or green against its prior period and against the team's set targets.
4. Any metric that misses a target fires an alert, visible as a badge in the header and in a dedicated Alerts panel.
5. The user clicks a metric card to see the AI-generated improvement ideas specific to that metric's movement.
6. The user applies a custom date range or filter (by campaign type, product, or portfolio) to investigate further, then closes the loop by acting on or dismissing the recommendations.

---

v1 scope

Side-by-side period comparison cards — Displays spend, revenue, ROAS, ACOS, clicks, and impressions in three columns (WoW, MoM, YoY) on the main dashboard screen. Each card shows absolute value, delta, and percentage change.

Automated trend detection with red/green signals — Calculates directional movement for every metric against the prior equivalent period and applies a red (declining or off-target) or green (improving or on-target) indicator directly on each card.

Metric alerts when targets missed — Team members set a target threshold per metric in Settings; when live data breaches the threshold, an alert is created, surfaced in the header badge and the Alerts panel screen.

AI-generated improvement ideas per metric — On click of any metric card, a side panel opens with 3–5 AI-generated recommendations contextualised to that metric's trend, period, and magnitude of change (e.g., bid adjustment suggestions when ACOS spikes).

Custom date range picker and filters — A persistent toolbar above the cards lets the user select any custom date range and filter by campaign type, portfolio, or product, re-rendering all cards and signals in real time.

---

Deliberately later

• Campaign-level drill-down — Requires stable aggregate layer first; adding granularity before the team's process is set will create noise.
• CSV / PDF export — Useful once the dashboard is the source of truth; premature export risks the team reverting to spreadsheet workflows before adoption is complete.
• Saved dashboard views and presets — Power feature that earns its complexity after the team has agreed on which views matter; v2 with clear user demand.

---

Data model sketch

• users — id, name, email, role, team\_id
• data_sources — id, type (amazon\_ads\_api | csv\_upload), credentials\_ref, last\_synced\_at
• raw_metrics — id, source\_id, date, campaign\_id, spend, revenue, impressions, clicks, orders
• metric_snapshots — id, period\_type (week|month|year), period\_start, period\_end, metric\_key, value, delta, pct\_change
• targets — id, metric\_key, threshold\_value, direction (above|below), created\_by
• alerts — id, target\_id, triggered\_at, metric\_snapshot\_id, dismissed\_at, dismissed\_by
• ai_recommendations — id, metric\_snapshot\_id, generated\_at, content, status (active|dismissed)
• filters — id, user\_id, date\_range\_start, date\_range\_end, campaign\_type, portfolio\_id

---

Screens

• Dashboard (main) — Period comparison cards, trend signals, and filter toolbar; the team's daily entry point.
• Alerts panel — Chronological list of all active and recent threshold breaches with dismiss and note actions.
• Metric detail / AI panel — Slide-over triggered from any card; shows historical sparkline and AI improvement ideas for that metric.
• Settings — Target thresholds per metric, data source connections (Amazon Ads API key, CSV upload), and user management.
• Upload / sync status — Log of all data imports and API syncs with timestamps and error states.

---

How to use this document

• Bring it into Mind Palace, where the guided platform and its AI coach pick up from exactly this document and build the product with you step by step.
• Hand it to a developer as the complete v1 brief — scope, data model, and screens are defined and ready.
• Keep it as the single source of truth for every feature and prioritisation decision while the build is in progress.