# Creator analytics learning-loop dashboard pattern

Session learning from AutoShorts Dashboard Sprint 5: simplify analytics for a normal content creator and connect performance to creative changes.

## Trigger

Use this when a creator/publishing dashboard has analytics, imported platform CSVs, package/video review pages, and the user asks for clearer daily decisions rather than more provider APIs or charts.

## Product principle

The default analytics view should answer five questions in this order:

1. What must I do today?
2. Which videos are ready or published?
3. Which video got how many views?
4. What did I change?
5. Did it get better, and what should I try next?

Do **not** make the creator navigate reporting-console tabs before seeing video results. Hide raw import/snapshot/provider terms from the primary UI; keep them in an Import/Manage Data area or developer docs.

## Analytics IA

Collapse complex analytics navigation into at most three areas:

- **Results** — default. KPI cards plus the Video Results table.
- **Improvements** — cards that connect creative changes to before/after metrics.
- **Import data** — CSV upload, import history, warnings, raw detail, rollback.

Avoid seven-tab layouts such as `overview | import | videos | trends | topics | insights | import history` for daily creator use.

## Results table

Make views prominent and visible without a drawer.

Primary columns:

- Thumbnail / Video title
- Views
- Delta views with plain labels: `+40 since last import`, `new`, `rising`, `slowing`
- CTR
- Retention proxy
- Subscribers
- Linked package/topic
- What changed
- Next action

Secondary metrics belong in the detail drawer: watch time, impressions, average duration, subscribers per 1000 views, raw import values, import snapshots.

## Detail drawer

On row click, open a right-side drawer/modal titled `Video Performance` with:

1. Video summary: thumbnail, title, external YouTube ID, linked package, topic, publish date.
2. Key metrics: views, views delta, CTR, retention proxy, subscribers delta, watch time, impressions.
3. Development over time: a simple import snapshot list and a small views-over-imports line.
4. What changed: title/caption/schedule/topic/hook notes, or `No change logged yet` with `Add change note`.
5. Recommendation: simple rule-based advice such as packaging/title improvement or follow-up recommendation.

## Backend model pattern

Add a simple `CreativeChange` model before building elaborate experiments:

- `id`
- `video_asset_id` nullable
- `external_post_id` nullable
- `post_draft_id` nullable
- `topic_id` nullable
- `change_type`: title, caption, description, hashtags, schedule, topic, thumbnail, hook, opening, cta, other
- `before_text` nullable
- `after_text` nullable
- `change_note`
- `hypothesis` nullable
- `changed_at`
- `created_by`, default creator
- `source`: manual, metadata_version, import

Also add a minimal `ActivityEvent` table for real history instead of placeholders:

- `entity_type`, `entity_id`, `event_type`, `label`, `payload_json`, `created_at`, `created_by`

Create events on metadata save, creative change, marked ready, approved, scheduled, upload queued/failed, and analytics linked.

## Automatic change capture

When review metadata save changes important fields, automatically create `CreativeChange` rows:

- YouTube title → `title`
- YouTube description → `description`
- TikTok caption → `caption`
- tags/hashtags → `hashtags`
- schedule → `schedule`
- topic/series if present → `topic`/`other`

Add an optional `Change note` input near `Save changes` with placeholder copy such as: `Shortened title and made warning clearer.`

## Improvements endpoint logic

MVP logic is deliberately honest and simple:

1. For each CreativeChange, find the latest analytics snapshot before `changed_at`.
2. Find the first or latest snapshot after `changed_at`.
3. Calculate delta and percentage when possible.
4. If before/after data is missing, still show the change but label it `needs_more_snapshots`.

Never imply statistical certainty from weak data. Say what changed and what the next import can validate.

## Suggested endpoints

- `GET /api/analytics/simple`
- `GET /api/analytics/video-results`
- `GET /api/analytics/video-results/{external_post_id}`
- `GET /api/analytics/improvements`
- `GET /api/analytics/unlinked-posts`
- `POST /api/analytics/changes`
- `GET /api/analytics/changes`

Make these frontend-friendly: include display labels, linked/unlinked booleans, latest_change, next_action, and thumbnail URLs so the UI does not reimplement analytics business logic.

## Mapping UX

When analytics rows are unlinked, show a top box in Results:

`N analytics videos are not linked to prepared packages. Linking them lets you see which package and metadata produced each result.`

Provide an unlinked drawer with analytics title, views, publish date, likely package matches, and actions to link. Persist YouTube/video IDs from source metadata in VideoAsset or PostDraft metadata when importing prepared packages; use those for auto-match before title similarity.

## Dashboard simplification

For daily cockpit pages, avoid showing the whole analytics system. Top dashboard should show:

1. Next video to review.
2. Performance since last import.
3. Unlinked analytics / unresolved actions.

Then show last 3 prepared packages, next topic, scheduled items, and a short `How this works` card:

1. Prepared videos arrive in the Inbox.
2. You review video, captions and descriptions.
3. You approve or schedule private uploads.
4. You import YouTube analytics CSVs.
5. The dashboard shows which videos and changes improved performance.

## Verification

- Backend tests: CreativeChange on metadata save; video-results endpoint views + linked/unlinked; improvements before/after or needs_more_snapshots; unlinked posts; ActivityEvent on save/schedule/approve.
- Frontend build.
- API smokes for all simple analytics endpoints.
- Browser QA: `/analytics` defaults to Results; visible views; linked/unlinked; Improvements card; Review change history/activity; Dashboard 5-step explainer.
- Copy scan: no primary UI text like `snapshot`, `ExternalPost`, `provider mapping`, `prepared for next sprint`.
- Report what genuinely works versus skeletons.

## Pitfalls

- More analytics tabs usually make the product less understandable. Default to fewer areas and move raw details under Import data.
- A drawer is for detail; views and linked status must be visible in the table itself.
- If no changes exist yet, create a real QA change note through the same endpoint/path the UI uses before claiming Improvements works.
- Do not prioritize new platform APIs when the user's complaint is UX clarity or learning-loop comprehension.