ghost 5.129.1 → 5.129.2

package/core/built/admin/index.html

@@ -6,7 +6,7 @@
     <title>Ghost</title>
 
     
-<meta name="ghost-admin/config/environment" content="%7B%22modulePrefix%22%3A%22ghost-admin%22%2C%22environment%22%3A%22production%22%2C%22cdnUrl%22%3A%22%22%2C%22editorUrl%22%3A%22%22%2C%22rootURL%22%3A%22%22%2C%22locationType%22%3A%22trailing-hash%22%2C%22EmberENV%22%3A%7B%22FEATURES%22%3A%7B%7D%2C%22EXTEND_PROTOTYPES%22%3A%7B%22Date%22%3Afalse%2C%22Array%22%3Atrue%2C%22String%22%3Atrue%2C%22Function%22%3Afalse%7D%2C%22_APPLICATION_TEMPLATE_WRAPPER%22%3Afalse%2C%22_JQUERY_INTEGRATION%22%3Atrue%2C%22_TEMPLATE_ONLY_GLIMMER_COMPONENTS%22%3Atrue%7D%2C%22APP%22%3A%7B%22version%22%3A%225.129%22%2C%22name%22%3A%22ghost-admin%22%7D%2C%22ember-simple-auth%22%3A%7B%7D%2C%22%40sentry%2Fember%22%3A%7B%22disablePerformance%22%3Atrue%2C%22sentry%22%3A%7B%7D%7D%2C%22ember-cli-mirage%22%3A%7B%22usingProxy%22%3Afalse%2C%22useDefaultPassthroughs%22%3Atrue%7D%2C%22exportApplicationGlobal%22%3Afalse%2C%22ember-load%22%3A%7B%22loadingIndicatorClass%22%3A%22ember-load-indicator%22%7D%2C%22editorFilename%22%3A%22koenig-lexical.umd.js%22%2C%22editorHash%22%3A%2237bd1e3e4d%22%2C%22adminXSettingsFilename%22%3A%22admin-x-settings.js%22%2C%22adminXSettingsHash%22%3A%22d9d1575574%22%2C%22adminXActivitypubFilename%22%3A%22admin-x-activitypub.js%22%2C%22adminXActivitypubHash%22%3A%22420f33378b%22%2C%22postsFilename%22%3A%22posts.js%22%2C%22postsHash%22%3A%223c29fa5ebb%22%2C%22statsFilename%22%3A%22stats.js%22%2C%22statsHash%22%3A%224949fe6470%22%2C%22adminXActivitypubCustomUrl%22%3A%22https%3A%2F%2Fcdn.jsdelivr.net%2Fghost%2Fadmin-x-activitypub%400%2Fdist%2Fadmin-x-activitypub.js%22%7D" />
+<meta name="ghost-admin/config/environment" content="%7B%22modulePrefix%22%3A%22ghost-admin%22%2C%22environment%22%3A%22production%22%2C%22cdnUrl%22%3A%22%22%2C%22editorUrl%22%3A%22%22%2C%22rootURL%22%3A%22%22%2C%22locationType%22%3A%22trailing-hash%22%2C%22EmberENV%22%3A%7B%22FEATURES%22%3A%7B%7D%2C%22EXTEND_PROTOTYPES%22%3A%7B%22Date%22%3Afalse%2C%22Array%22%3Atrue%2C%22String%22%3Atrue%2C%22Function%22%3Afalse%7D%2C%22_APPLICATION_TEMPLATE_WRAPPER%22%3Afalse%2C%22_JQUERY_INTEGRATION%22%3Atrue%2C%22_TEMPLATE_ONLY_GLIMMER_COMPONENTS%22%3Atrue%7D%2C%22APP%22%3A%7B%22version%22%3A%225.129%22%2C%22name%22%3A%22ghost-admin%22%7D%2C%22ember-simple-auth%22%3A%7B%7D%2C%22%40sentry%2Fember%22%3A%7B%22disablePerformance%22%3Atrue%2C%22sentry%22%3A%7B%7D%7D%2C%22ember-cli-mirage%22%3A%7B%22usingProxy%22%3Afalse%2C%22useDefaultPassthroughs%22%3Atrue%7D%2C%22exportApplicationGlobal%22%3Afalse%2C%22ember-load%22%3A%7B%22loadingIndicatorClass%22%3A%22ember-load-indicator%22%7D%2C%22editorFilename%22%3A%22koenig-lexical.umd.js%22%2C%22editorHash%22%3A%2237bd1e3e4d%22%2C%22adminXSettingsFilename%22%3A%22admin-x-settings.js%22%2C%22adminXSettingsHash%22%3A%22657b852ebf%22%2C%22adminXActivitypubFilename%22%3A%22admin-x-activitypub.js%22%2C%22adminXActivitypubHash%22%3A%2240f7252084%22%2C%22postsFilename%22%3A%22posts.js%22%2C%22postsHash%22%3A%22be74778cd8%22%2C%22statsFilename%22%3A%22stats.js%22%2C%22statsHash%22%3A%222dcb5663ba%22%2C%22adminXActivitypubCustomUrl%22%3A%22https%3A%2F%2Fcdn.jsdelivr.net%2Fghost%2Fadmin-x-activitypub%400%2Fdist%2Fadmin-x-activitypub.js%22%7D" />
 
     <meta name="viewport" content="user-scalable=no, width=device-width, initial-scale=1, maximum-scale=1, minimal-ui, viewport-fit=cover" />
     <meta name="pinterest" content="nopin" />
@@ -28,7 +28,7 @@
     </style>
 
     <link integrity="" rel="stylesheet" href="assets/vendor-0ede59da8efb5e28fa929557f7ff7154.css">
-    <link integrity="" rel="stylesheet" href="assets/ghost-415f8e3c36dbe0e09f87608628da382d.css" title="light">
+    <link integrity="" rel="stylesheet" href="assets/ghost-3d0ad0c58f433d5735532bf25d4fd423.css" title="light">
 
     
 </head>
@@ -48,8 +48,8 @@
     <div id="ember-basic-dropdown-wormhole"></div>
 
     <script src="assets/vendor-c89102f24c3d9502e9db741509767580.js"></script>
-<script src="assets/chunk.383.09219fde42568dd42ed5.js"></script>
-<script src="assets/chunk.524.5330e1e5569947d7b7f2.js"></script>
-    <script src="assets/ghost-1bce1a4ebfdfc6f6f333a827f40f69a6.js"></script>
+<script src="assets/chunk.728.214803966b81ffdb1acd.js"></script>
+<script src="assets/chunk.524.c8313bccd308920abf9c.js"></script>
+    <script src="assets/ghost-db9fcb8c1f65776f3ee11c39f19a660b.js"></script>
 </body>
 </html>

package/core/frontend/helpers/ghost_head.js

@@ -2,7 +2,7 @@
 // Usage: `{{ghost_head}}`
 //
 // Outputs scripts and other assets at the top of a Ghost theme
-const {labs, metaData, settingsCache, config, blogIcon, urlUtils, getFrontendKey} = require('../services/proxy');
+const {labs, metaData, settingsCache, config, blogIcon, urlUtils, getFrontendKey, settingsHelpers} = require('../services/proxy');
 const {escapeExpression, SafeString} = require('../services/handlebars');
 const {generateCustomFontCss, isValidCustomFont, isValidCustomHeadingFont} = require('@tryghost/custom-fonts');
 // BAD REQUIRE
@@ -362,9 +362,8 @@ module.exports = async function ghost_head(options) { // eslint-disable-line cam
             if (!_.isEmpty(tagCodeInjection)) {
                 head.push(tagCodeInjection);
             }
-            const isTbTrackingEnabled = labs.isSet('trafficAnalytics');
-            const hasTbConfig = config.get('tinybird') && config.get('tinybird:tracker');
-            if (isTbTrackingEnabled && hasTbConfig) {
+            // Use settingsHelpers to check if web analytics is enabled (includes all necessary checks)
+            if (settingsHelpers.isWebAnalyticsEnabled()) {
                 head.push(getTinybirdTrackerScript(dataRoot));
                 // Set a flag in response locals to indicate tracking script is being served
                 if (dataRoot._locals) {

package/core/frontend/meta/get-meta.js

@@ -21,7 +21,7 @@ const getOgImage = require('./og-image');
 const getPaginatedUrl = require('./paginated-url');
 const getPublishedDate = require('./published-date');
 const getRssUrl = require('./rss-url');
-const getSchema = require('./schema');
+const {getSchema} = require('./schema');
 const getStructuredData = require('./structured-data');
 const getTitle = require('./title');
 const getTwitterImage = require('./twitter-image');

package/core/frontend/meta/schema.js

@@ -48,31 +48,33 @@ function trimSchema(schema) {
     return schemaObject;
 }
 
-function trimSameAs(data, context) {
+// note that website isn't included here
+const SOCIAL_PLATFORMS = ['facebook', 'twitter', 'threads', 'bluesky', 'mastodon', 'tiktok', 'youtube', 'instagram', 'linkedin'];
+
+/**
+ * Build the `sameAs` array for schema.org Person objects.
+ *
+ * @param {Object} author   either `data.author` or `data.<post|page>.primary_author`.
+ *                          Expected to contain `website` plus any supported social usernames.
+ * @returns {string[]}      URLs for the author website and each populated social profile.
+ */
+function trimSameAs(author) {
+    if (!author || Object.keys(author).length === 0) {
+        return [];
+    }
+    
     const sameAs = [];
 
-    if (context === 'post' || context === 'page') {
-        if (data[context].primary_author.website) {
-            sameAs.push(escapeExpression(data[context].primary_author.website));
-        }
-        if (data[context].primary_author.facebook) {
-            sameAs.push(socialUrls.facebook(data[context].primary_author.facebook));
-        }
-        if (data[context].primary_author.twitter) {
-            sameAs.push(socialUrls.twitter(data[context].primary_author.twitter));
-        }
-    } else if (context === 'author') {
-        if (data.author.website) {
-            sameAs.push(escapeExpression(data.author.website));
-        }
-        if (data.author.facebook) {
-            sameAs.push(socialUrls.facebook(data.author.facebook));
-        }
-        if (data.author.twitter) {
-            sameAs.push(socialUrls.twitter(data.author.twitter));
-        }
+    if (author.website) {
+        sameAs.push(escapeExpression(author.website));
     }
 
+    SOCIAL_PLATFORMS.forEach((platform) => {
+        if (author[platform] && typeof socialUrls[platform] === 'function') {
+            sameAs.push(escapeExpression(socialUrls[platform](author[platform])));
+        }
+    });
+
     return sameAs;
 }
 
@@ -94,7 +96,7 @@ function getPostSchema(metaData, data) {
             name: escapeExpression(data[context].primary_author.name),
             image: schemaImageObject(metaData.authorImage),
             url: metaData.authorUrl,
-            sameAs: trimSameAs(data, context),
+            sameAs: trimSameAs(data[context].primary_author),
             description: data[context].primary_author.metaDescription ?
                 escapeExpression(data[context].primary_author.metaDescription) :
                 null
@@ -150,7 +152,7 @@ function getAuthorSchema(metaData, data) {
     const schema = {
         '@context': 'https://schema.org',
         '@type': 'Person',
-        sameAs: trimSameAs(data, 'author'),
+        sameAs: trimSameAs(data.author),
         name: escapeExpression(data.author.name),
         url: metaData.authorUrl,
         image: schemaImageObject(metaData.authorImage) || schemaImageObject(metaData.coverImage),
@@ -179,4 +181,4 @@ function getSchema(metaData, data) {
     return null;
 }
 
-module.exports = getSchema;
+module.exports = {getSchema, SOCIAL_PLATFORMS};

package/core/frontend/services/proxy.js

@@ -1,6 +1,7 @@
 // This file contains everything that the helpers and frontend apps require from the core of Ghost
 const settingsCache = require('../../shared/settings-cache');
 const config = require('../../shared/config');
+const settingsHelpers = require('../../server/services/settings-helpers');
 
 // Require from the handlebars framework
 const {SafeString} = require('./handlebars');
@@ -47,6 +48,11 @@ module.exports = {
     // TODO: Only expose "get"
     settingsCache: settingsCache,
 
+    // Settings helpers for calculated settings
+    settingsHelpers: {
+        isWebAnalyticsEnabled: settingsHelpers.isWebAnalyticsEnabled.bind(settingsHelpers)
+    },
+
     // TODO: Expose less of the API to make this safe
     api: require('../../server/api').endpoints,
 

package/core/server/data/tinybird/ARCHITECTURE.md

@@ -0,0 +1,420 @@
+# Ghost Traffic Analytics Data Model Explainer
+
+This document explains the comprehensive data architecture behind Ghost's traffic analytics features, 
+covering both the MySQL database schema and Tinybird event streams, their relationships, and how they work together 
+to provide real-time analytics.
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [MySQL Schema (Ghost Database)](#mysql-schema-ghost-database)
+3. [Tinybird Event Schema](#tinybird-event-schema)
+4. [Data Flow & Relationships](#data-flow--relationships)
+5. [API Endpoints](#api-endpoints)
+6. [Mock Data Considerations](#mock-data-considerations)
+
+## Overview
+ Ghost's traffic analytics system has two data sources: MySQL and Tinybird
+
+# Ghost Analytics Architecture
+
+```mermaid
+graph TD
+    A[Ghost Admin<br/>Frontend] --> B[Ghost<br/>Main Server]
+    A --> C[Tinybird<br/>Analytics DB]
+    B --> D[MySQL<br/>Database]
+    B --> C
+```
+
+- **MySQL Database**: Stores content, members, newsletters, and member attribution events
+- **Tinybird**: Real-time analytics database that processes page views and visitor sessions
+- **Cross-system Integration**: UUID-based relationships between Ghost entities and Tinybird events
+
+The system tracks:
+- **Web Traffic**: Page views, sessions, referrers, device info (via Tinybird)
+- **Member Growth**: Signups, conversions, attribution to content (via MySQL)
+- **Newsletter Performance**: Sends, opens, clicks, revenue attribution (via MySQL + Tinybird)
+- **Content Performance**: Views, member conversions, revenue impact (hybrid)
+
+## MySQL Schema (Ghost Database)
+
+### Core Content Tables
+
+#### `posts`
+Primary content table storing all posts and pages.
+
+**Key fields for analytics:**
+- `id` (string, 24 chars) - Primary key, used in attribution events
+- `uuid` (string, 36 chars) - UUID for Tinybird correlation
+- `title` - Content title
+- `slug` - URL slug
+- `type` - 'post' or 'page'
+- `status` - 'published', 'draft', 'scheduled', 'sent'
+- `published_at` - Publication timestamp
+- `newsletter_id` - Associated newsletter (if sent via email)
+
+#### `posts_meta`
+Extended metadata for posts.
+
+**Relevant fields:**
+- `post_id` - Foreign key to posts.id
+- `meta_title`, `meta_description` - SEO metadata
+- `email_subject` - Newsletter subject line
+- `email_only` - Whether post is email-exclusive
+
+### Member & Subscription Tables
+
+#### `members`
+Core member accounts.
+
+**Key fields:**
+- `id` (string, 24 chars) - Primary key
+- `uuid` (string, 36 chars) - UUID for Tinybird correlation  
+- `email` - Member email address
+- `status` - 'free', 'paid', 'comped'
+- `created_at` - Signup timestamp
+
+#### `newsletters`
+Newsletters are series of emails. Sites can have multiple different newsletters, each with its own name & branding. Sites may have a "Daily newsletter" and a "Weekly roundup" newsletter, for example.
+
+**Key fields:**
+- `id` (string, 24 chars) - Primary key
+- `name` - Newsletter name
+- `status` - 'active', 'archived'
+
+#### `products` (tiers)
+Subscription tiers/products that members can sign up for with Stripe
+
+**Key fields:**
+- `id` (string, 24 chars) - Primary key
+- `name` - Tier name
+- `type` - 'free', 'paid'
+- `monthly_price`, `yearly_price` - Pricing
+
+### Attribution & Event Tables
+
+#### `members_created_events`
+Tracks member signups and their attribution.
+
+**Key fields:**
+- `id` - Primary key
+- `member_id` - Foreign key to members.id
+- `created_at` - Signup timestamp
+- `attribution_id` - ID of attributed resource (post.id, etc.)
+- `attribution_type` - 'post', 'page', 'url', 'tag', 'author'
+- `attribution_url` - Full URL that drove signup
+- `referrer_source` - Domain that referred the member
+- `referrer_medium` - Marketing medium
+- `referrer_url` - Full referrer URL
+- `source` - 'member', 'import', 'system', 'api', 'admin'
+
+#### `members_subscription_created_events`
+Tracks paid subscription starts and their attribution.
+
+**Key fields:**
+- `id` - Primary key
+- `member_id` - Foreign key to members.id
+- `subscription_id` - Associated subscription
+- `created_at` - Conversion timestamp
+- `attribution_id` - ID of attributed resource
+- `attribution_type` - 'post', 'page', 'url', 'tag', 'author'
+- `attribution_url` - URL that drove conversion
+- `referrer_source` - Domain that drove conversion
+- `referrer_medium` - Marketing medium
+- `referrer_url` - Full referrer URL
+
+#### `members_paid_subscription_events`
+Tracks MRR changes from subscription events.
+
+**Key fields:**
+- `member_id` - Foreign key to members.id
+- `subscription_id` - Associated subscription
+- `mrr_delta` - Monthly recurring revenue change
+- `created_at` - Event timestamp
+
+### Email & Newsletter Tables
+
+#### `emails`
+When a post is sent as an email, a row is added to this table
+
+**Key fields:**
+- `id` - Primary key
+- `post_id` - Associated post (unique)
+- `newsletter_id` - Associated newsletter
+- `status` - 'pending', 'submitted', 'failed'
+- `email_count` - Total recipients
+- `delivered_count` - Successfully delivered
+- `opened_count` - Total opens
+- `failed_count` - Failed deliveries
+- `submitted_at` - Send timestamp
+
+#### `email_recipients`
+A row for every member who received a particular email. Tracks which members received each email, and when it was delivered, opened, failed, etc.
+
+**Key fields:**
+- `email_id` - Foreign key to emails.id
+- `member_id` - Foreign key to members.id
+- `member_email` - Recipient email
+- `delivered_at` - Delivery timestamp
+- `opened_at` - Open timestamp
+- `failed_at` - Failure timestamp
+
+#### `redirects`
+All links in an email are replaced with tracking links to Ghost so we can track clicks in emails
+
+**Key fields:**
+- `id` - Primary key
+- `from` - Short redirect URL
+- `to` - Destination URL
+- `post_id` - Associated post (if applicable)
+
+#### `members_click_events`
+Email click tracking - each time a member clicks a link in an email
+
+**Key fields:**
+- `member_id` - Foreign key to members.id
+- `redirect_id` - Foreign key to redirects.id
+- `created_at` - Click timestamp
+
+### Newsletter Subscription Tables
+
+#### `members_newsletters`
+Many-to-many relationship for newsletter subscriptions. Sites can have multiple newsletters, members can be subscribed to 0 or more newsletters
+
+**Key fields:**
+- `member_id` - Foreign key to members.id
+- `newsletter_id` - Foreign key to newsletters.id
+
+#### `members_subscribe_events`
+Newsletter subscription/unsubscription events. Members can choose to subscribe/unsubscribe to any of a site's newsletters at any time
+
+**Key fields:**
+- `member_id` - Foreign key to members.id
+- `newsletter_id` - Foreign key to newsletters.id
+- `subscribed` - true/false for subscribe/unsubscribe
+- `created_at` - Event timestamp
+- `source` - Event source
+
+## Tinybird Event Schema
+
+### Analytics Events Datasource
+
+#### `analytics_events`
+
+Raw page view events streamed from the frontend. You can find the schema in `datasources` folder.
+Fields with specific data in the schema:
+
+```sql
+`action` LowCardinality(String)  -- Usually 'page_hit'
+`site_uuid` LowCardinality(String) -- Extracted from payload
+```
+
+**Payload Structure:**
+```json
+{
+  "site_uuid": "string",
+  "member_uuid": "string|undefined",  // member.uuid in MySQL
+  "member_status": "free|paid|comped|undefined", // member.status in MySQL
+  "post_uuid": "string|undefined", // post.uuid in MySQL
+  "post_type": "post|page|empty", //post.type in MySQL
+  "user-agent": "string",
+  "locale": "string",
+  "location": "string", // Country code
+  "referrer": "string", // used for member attribution
+  "pathname": "string",
+  "href": "string", // Full URL
+}
+```
+
+### Materialized View: _mv_hits
+
+#### `_mv_hits`
+
+Schema for hits can be also found in `datasources` folder.
+Explanation of some of the important fields.
+
+```sql
+`location` String      -- Country code
+`source` String        -- Referrer domain
+`pathname` String      -- URL path
+`href` String          -- Full URL
+`device` String        -- Device type
+`os` String           -- Operating system
+`browser` String      -- Browser name
+```
+
+### Tinybird Endpoints (Pipes)
+
+Endpoints which can be found in `endpoints` folder.
+
+- `api_active_visitors` - Real-time visitor counts
+- `api_kpis` - Site-wide KPI metrics
+- `api_post_visitor_counts` - Visitor counts by post UUID
+- `api_top_browsers` - Top browsers by visits
+- `api_top_devices` - Top devices by visits
+- `api_top_locations` - Top countries by visits
+- `api_top_os` - Top operating systems by visits
+- `api_top_pages` - Top pages by visits
+- `api_top_sources` - Top referrer sources by visits
+
+## Data Flow & Relationships
+
+### 1. Page View Tracking
+
+```
+Frontend → Tinybird analytics_events → _mv_hits materialized view
+```
+
+**Key Relationships:**
+- `payload.site_uuid` identifies the Ghost site
+- `payload.post_uuid` correlates to `posts.uuid` in MySQL
+- `payload.member_uuid` correlates to `members.uuid` in MySQL
+
+### 2. Member Attribution Flow
+
+```
+Member Signup → members_created_events (with attribution_*)
+Member Conversion → members_subscription_created_events (with attribution_*)
+```
+
+**Attribution Logic:**
+- `attribution_id` contains `posts.id` when attributed to specific content
+- `attribution_type` categorizes the attribution source
+- `attribution_url` stores the full URL that drove the action
+- `referrer_source` tracks the referring domain
+
+### 3. Newsletter Performance Flow
+
+```
+Post Creation → Email Send (emails table) → Individual Recipients (email_recipients)
+Click Tracking → redirects → members_click_events
+```
+
+### 4. Cross-System Data Correlation
+
+**Post Performance Analysis:**
+1. Get page views from Tinybird using `posts.uuid`
+2. Get member attribution from MySQL using `posts.id`
+3. Get email performance from MySQL using `posts.id`
+4. Combine for comprehensive post analytics
+
+**Member Journey Tracking:**
+1. Tinybird tracks anonymous page views
+2. MySQL tracks member signup with attribution
+3. MySQL tracks paid conversion with attribution
+
+## API Endpoints
+
+All endpoints require authentication (`mw.authAdminApi`) and are gated behind `labs.isSet('trafficAnalytics')`.
+
+### Core Stats Endpoints
+
+```javascript
+// Member growth
+GET /stats/member_count
+GET /stats/mrr
+GET /stats/subscriptions
+
+// Content performance  
+GET /stats/top-posts          // Attribution-based rankings
+GET /stats/top-posts-views    // View-based rankings (Tinybird)
+GET /stats/top-content        // Combined content performance
+
+// Post-specific analytics
+GET /stats/posts/:id/stats    // Individual post performance
+GET /stats/posts/:id/growth   // Member attribution for post
+GET /stats/posts/:id/top-referrers // Referrer breakdown for post
+
+// Newsletter analytics
+GET /stats/newsletter-stats        // Full newsletter performance
+GET /stats/newsletter-basic-stats  // Basic stats (faster)
+GET /stats/newsletter-click-stats  // Click-through data
+GET /stats/subscriber-count        // Subscriber growth
+
+// Traffic sources
+GET /stats/referrers           // Historical referrer data
+GET /stats/top-sources-growth  // Source performance over time
+
+// Batch endpoints
+POST /stats/posts-visitor-counts   // Bulk visitor counts (Tinybird)
+POST /stats/posts-member-counts    // Bulk member attribution (MySQL)
+```
+
+### Request/Response Patterns
+
+Most endpoints support:
+- `date_from` / `date_to` - Date range filtering
+- `limit` - Result count limiting  
+- `order` - Sort field and direction
+- `newsletter_id` - Newsletter-specific filtering
+- `timezone` 
+
+Response format:
+```json
+{
+  "data": [...],
+  "meta": {
+    "totals": {...}
+  }
+}
+```
+
+## Mock Data Considerations
+
+### Data Volume & Relationships
+
+For realistic testing, mock data should maintain proper ratios:
+
+**Content:**
+- ~100-500 posts across 6-month period
+- ~10-20 pages (about, contact, etc.)
+- 1-3 newsletters
+
+**Members:**
+- ~1000-5000 total members
+- ~70% free, ~25% paid, ~5% comped
+- ~50-100 new signups per month
+- ~10-20% conversion rate from free to paid
+
+**Page Views (Tinybird):**
+- ~10-50 views per post (varies widely)
+- ~100-500 daily total page views
+- ~60% direct/type-in, ~25% search, ~10% social, ~5% other referrers
+
+**Email Performance:**
+- ~50-80% delivery rate
+- ~20-40% open rate
+- ~2-5% click rate
+- Newsletter sends 1-4x per month
+
+### Key Constraints
+
+**UUID Relationships:**
+- `posts.uuid` must match Tinybird `post_uuid` values
+- `members.uuid` must match Tinybird `member_uuid` values
+- UUIDs should be valid v4 format
+
+**Attribution Data:**
+- `attribution_id` must reference valid `posts.id`
+- `attribution_url` should be realistic Ghost URLs
+- `referrer_source` should be realistic domains
+
+**Temporal Consistency:**
+- Member created events before subscription events
+- Posts published before attribution events
+- Email sends after post publication
+- Page views distributed realistically over time
+
+### Performance Considerations
+
+**Indexes:**
+- Date-based queries need temporal indexing
+- Attribution queries need member_id + attribution_id indexes
+- Cross-table joins need proper foreign key indexes
+
+**Query Patterns:**
+- Most analytics queries filter by date ranges
+- Post-specific queries join on post IDs/UUIDs
+- Member attribution queries are complex with multiple CTEs
+
+This data model enables comprehensive traffic analytics while maintaining performance through strategic use of both MySQL and Tinybird for their respective strengths.

package/core/server/data/tinybird/README.md

@@ -0,0 +1,84 @@
+## Tinybird Analytics
+
+This is the web analytics implementation using [Tinybird Forward](https://www.tinybird.co/docs/forward).
+
+### Requirements
+
+In order to use Tinybird locally, make sure to install the Tinybird CLI.
+**Only for the first time, run:** `yarn tb:install` from the root folder.
+
+### Using Tinybird locally
+
+To run Tinybird locally, run `yarn tb` from root. 
+
+This script will pull and start the `tinybird-local` Docker container, then run `tb dev` to deploy the Tinybird project to the `tinybird-local` container on file changes. The `tb dev` command also launches a Tinybird shell environment where you can run other `tb` CLI commands against the local container.  Read more about the [`tb dev` command here](https://www.tinybird.co/docs/forward/dev-reference/commands/tb-dev).
+
+### Connecting Tinybird to Ghost config file
+
+In order to use Tinybird local service with Ghost, the config local needs to be updated with Tinybird details.
+Config can contain information about remote and local environments.
+
+Make sure to get the proper tokens, which you can obtain by running  `tb token ls`, or if you are within Tinybird
+local shell environment, you can just run `token ls`.
+
+Make sure you use the proper tokens. If you need read, write permissions, use a token that allows both.
+
+Simply disable local to use the cloud version by switching `local: false`. 
+This is switchable both via tracker script (ideally not used with the cloud data except with a unique id) and stats page.
+
+You can enable or disable local in config script below. Update your `/ghost/core/config.local.json` or `/ghost/core/config.local.jsonc`
+with the following information.
+
+### Config
+Sample config:
+```json
+{
+   "someOtherConfigurationForEmail": {
+        "transport": "SMTP",
+        "options": {
+            "port": 12345
+        }
+    },
+    "tinybird": {
+        "tracker": {
+            "endpoint": "https://e.ghost.org/tb/web_analytics",
+            "token": "xxxxx",
+            "datasource": "analytics_events",
+            "local": {
+                "enabled": true,
+                "token": "xxxxx",
+                "endpoint": "http://localhost:7181/v0/events",
+                "datasource": "analytics_events"
+            }
+        },
+        "stats": {
+            "endpoint": "https://api.tinybird.co",
+            "token": "xxxxx",
+            "local": {
+                "enabled": true,
+                "token": "xxxxx",
+                "endpoint": "http://localhost:7181",
+                "datasource": "analytics_events"
+            }
+        }
+    }
+}
+```
+
+### Testing
+
+Tests are executed using `test run` when running `tb dev`.
+
+
+### Testing data
+
+In fixtures folder, you can find local test data. When tinybird local is running, you can append data, or remove data
+from fixture files here. As you modify the files, the datasources will be auto updated.
+
+Keep in mind that as you update fixtures, it will rebuild data, but materialized views will have appended data. Old
+data will not be cleared from them. One way to approach this to make sure data is consistent is to truncate all data
+sources before adding test data to it.
+
+### Architecture
+
+[See full documentation regarding analytics architecture in following document](ARCHITECTURE.md)