Content Performance Analytics

Free — GPL coresize Lplanned, not built

Generated from docs/plan/core/content-performance-analytics/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

A blog-post analytics engine that tracks page views, referral sources, and basic engagement metrics. Core provides the tracking interface and honest view-count/traffic-source dashboard; paid plans own advanced features (heatmaps, audience segmentation, predictive analytics).

The problem

Merchants can’t see which blog posts drive traffic or engagement, and they’re guessing what content strategy to invest in. Without visibility into performance, they waste resources on low-performing content and miss opportunities to amplify what works.

What it does

• Track page views per blog post (increment on valid request, deduplicated by session/IP)
• Record referral source (HTTP referer header, parsed to domain)
• Track basic engagement time (first-paint-to-exit or time-on-page)
• Aggregate daily/weekly/monthly page-view trends per post
• Expose view counts and referral breakdown in admin dashboard
• Provide view data via REST API (JSON export for third-party tools)
• Display top 10 posts by views, top referral sources in admin
• Support filtering by date range
• Ensure tracking respects privacy (no PII, no IP logging, session-token only)
• Log anonymously to audit trail (do not link to specific users)

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Heatmaps — requires client-side recording of mouse/scroll events; expensive in storage and privacy liability. Reason: advanced UX instrumentation is a paid feature.
• Audience segmentation (behavioral cohorts, repeat-visitor identity) — requires user identity; core only tracks anonymous sessions. Reason: identity infrastructure is paid (storefront-customer-accounts).
• Predictive analytics (forecasting which posts will trend) — requires ML pipeline. Reason: paid feature with vendor lock-in.
• A/B testing integration — requires experiment tracking; core does not own split-test infrastructure. Reason: paid feature.
• Third-party analytics imports (Google Analytics, Mixpanel) — core does not own credential management. Reason: each vendor needs credential seam; data is paid.
• Custom event tracking (button clicks, form submissions) — only page-view and referral are core. Reason: paid feature for event expansion.

Data model

New tables: PageViewEvent {id, postId, timestamp, referrerDomain, sessionToken, userAgent, countryCode}; PostViewAggregate {postId, date, viewCount, topReferrers: [{domain, count}]}. No migration required.

API

• GET /api/posts/:postId/views
• GET /api/posts/:postId/referrers
• GET /api/posts/analytics/top
• POST /api/analytics/pageview

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Dashboard card showing ‘Top Posts by Views’ (pie chart or table); post detail page shows ‘Page Views’ sparkline and referral breakdown; export CSV of all posts with views; filter by date range, sort by views/trend; real-time view counter (optional).

The seam — why this is core

Core owns: honest page-view tracking interface, view-count aggregation, referral-source parsing, admin dashboard with read-only metrics. Paid owns: advanced analytics (heatmaps, ML, segmentation), third-party integrations, custom event tracking, data warehouse export.

Core owns view tracking and traffic-source attribution as essential interfaces. Paid owns advanced analytics infrastructure (heatmaps, machine-learning predictions) and support for high-volume sites.

Dependencies

• Blog/post infrastructure (posts must exist and be queryable)
• Session/request context on storefront (sessionToken, referrer, userAgent)
• Settings system (enable/disable analytics per merchant)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• A blog post with 100 views from direct traffic shows viewCount=100 and topReferrers includes ‘direct’ with 100 count
• Referrer source is correctly parsed from HTTP Referer header (e.g., ‘https://google.com/search’ → domain ‘google.com’)
• Session-token deduplication works: same sessionToken posting 5 times in 1 second counts as 1 view
• API export returns CSV with postId, title, viewCount, last7Days, last30Days
• Daily aggregation roll-up happens at 00:00 UTC, capturing all views from previous day
• Page-view events do not store IP address or any PII
• Referrer parsing handles null/missing referer gracefully (counts as ‘direct’, no error)
• Admin dashboard updates within 5 minutes of view event
• View tracking does not break if storefront cache is enabled (uses cache-busting or POST)
• Audit log does NOT record individual page views; only daily rollups and config changes are logged

Risks

Spam views: bot traffic inflates view counts; mitigation: rate-limiting on POST or IP-based dedup. Storage bloat: if not aggregated daily, table grows unbounded; mitigation: mandatory daily roll-up and archival. Privacy breach: storing IP/userID violates privacy; mitigation: schema validation. Race condition: two servers aggregate same day simultaneously; mitigation: transaction + unique constraint.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.