feat: consolidate schema and fix frontend type errors
This commit is contained in:
cawcenter
274
SCHEMA_REFERENCE.md
Normal file
274
SCHEMA_REFERENCE.md
Normal file
@@ -0,0 +1,274 @@
|
||||
# Spark Platform - Database Schema Reference
|
||||
|
||||
This document serves as the **Single Source of Truth** for the Spark Platform database schema. It consolidates all core systems, engines, and analytics modules.
|
||||
|
||||
## 1. Core System
|
||||
|
||||
### `sites`
|
||||
Managed WordPress instances.
|
||||
- **id** (UUID): Primary Key
|
||||
- **name** (String): Site Name
|
||||
- **url** (String): Full URL (e.g., https://example.com)
|
||||
- **wp_username** (String): Admin username
|
||||
- **wp_app_password** (String): Application Password
|
||||
- **domain_age_years** (Integer): Age of domain for velocity calculation
|
||||
- **status** (String): `active` | `paused` | `archived`
|
||||
- **created_at** (Timestamp)
|
||||
- **updated_at** (Timestamp)
|
||||
|
||||
### `globals`
|
||||
Site-wide settings and branding.
|
||||
- **id** (UUID): Primary Key
|
||||
- **site** (M2O -> sites): Owner site
|
||||
- **site_name** (String)
|
||||
- **site_tagline** (String)
|
||||
- **logo** (Image)
|
||||
- **favicon** (Image)
|
||||
- **primary_color** (String)
|
||||
- **secondary_color** (String)
|
||||
- **footer_text** (Text)
|
||||
- **social_links** (JSON)
|
||||
- **scripts_head** (Text)
|
||||
- **scripts_body** (Text)
|
||||
|
||||
### `navigation`
|
||||
Site menus.
|
||||
- **id** (UUID)
|
||||
- **site** (M2O -> sites)
|
||||
- **label** (String)
|
||||
- **url** (String)
|
||||
- **target** (String): `_self` | `_blank`
|
||||
- **parent** (M2O -> navigation): For nested menus
|
||||
- **sort** (Integer)
|
||||
|
||||
---
|
||||
|
||||
## 2. Content Factory (SEO Engine)
|
||||
|
||||
### `campaign_masters`
|
||||
Controls content generation campaigns.
|
||||
- **id** (UUID)
|
||||
- **site_id** (M2O -> sites)
|
||||
- **name** (String)
|
||||
- **headline_spintax_root** (Text): Root spintax for titles
|
||||
- **niche_variables** (JSON): Key/Value pairs for replacement
|
||||
- **location_mode** (String): `none` | `state` | `county` | `city`
|
||||
- **location_target** (String)
|
||||
- **batch_count** (Integer)
|
||||
- **target_word_count** (Integer): Default 1500
|
||||
- **velocity_mode** (String): `RAMP_UP` | `CONSISTENT`
|
||||
- **backdate_start** (Date)
|
||||
- **backdate_end** (Date)
|
||||
- **status** (String): `active` | `paused` | `completed`
|
||||
|
||||
### `generated_articles`
|
||||
The central content unit (replaces/aliases `posts` for SEO).
|
||||
- **id** (UUID)
|
||||
- **site_id** (M2O -> sites)
|
||||
- **campaign_id** (M2O -> campaign_masters)
|
||||
- **title** (String)
|
||||
- **slug** (String)
|
||||
- **html_content** (Text): Full rendered HTML
|
||||
- **schema_json** (JSON): FAQ, Article, Product schema
|
||||
- **meta_desc** (Text)
|
||||
- **meta_title** (String)
|
||||
- **featured_image** (Image)
|
||||
- **generation_hash** (String): For duplicate checks
|
||||
- **is_published** (Boolean)
|
||||
- **status** (String): `queued` | `processing` | `qc` | `approved` | `published`
|
||||
- **sitemap_status** (String): `ghost` | `queued` | `indexed`
|
||||
- **date_created** (Timestamp)
|
||||
- **date_published** (Timestamp)
|
||||
|
||||
### `headline_inventory`
|
||||
Pre-generated titles awaiting content.
|
||||
- **id** (UUID)
|
||||
- **campaign** (M2O -> campaign_masters)
|
||||
- **final_title_text** (String)
|
||||
- **status** (String): `available` | `used`
|
||||
- **used_on_article** (M2O -> generated_articles)
|
||||
|
||||
### `content_fragments`
|
||||
Reusable content blocks (intros, outros, CTAs).
|
||||
- **id** (UUID)
|
||||
- **campaign** (M2O -> campaign_masters)
|
||||
- **fragment_type** (String)
|
||||
- **content_body** (Text)
|
||||
- **word_count** (Integer)
|
||||
|
||||
### `production_queue`
|
||||
Manages generation schedule and velocity.
|
||||
- **id** (UUID)
|
||||
- **site** (M2O -> sites)
|
||||
- **campaign** (M2O -> campaign_masters)
|
||||
- **status** (String): `test_batch` | `pending` | `active` | `completed`
|
||||
- **total_requested** (Integer)
|
||||
- **completed_count** (Integer)
|
||||
- **velocity_mode** (String)
|
||||
- **schedule_data** (JSON): Array of planned dates
|
||||
|
||||
---
|
||||
|
||||
## 3. Cartesian Engine (Advanced Logic)
|
||||
|
||||
### `generation_jobs`
|
||||
Batch jobs for Cartesian product generation.
|
||||
- **id** (UUID)
|
||||
- **site_id** (M2O -> sites)
|
||||
- **target_quantity** (Integer)
|
||||
- **status** (String): `Pending` | `Processing` | `Complete`
|
||||
- **filters** (JSON)
|
||||
- **current_offset** (Integer)
|
||||
|
||||
### `cartesian_patterns`
|
||||
Logic patterns for data combinations.
|
||||
- **id** (UUID)
|
||||
- **pattern_key** (String): Unique key
|
||||
- **pattern_type** (String)
|
||||
- **formula** (String): Logic formula
|
||||
- **data** (JSON)
|
||||
|
||||
### `spintax_dictionaries`
|
||||
Global spintax terms.
|
||||
- **id** (UUID)
|
||||
- **category** (String): e.g., "power_words"
|
||||
- **data** (JSON): Array of strings
|
||||
|
||||
---
|
||||
|
||||
## 4. Intelligence Library
|
||||
|
||||
### `avatar_intelligence`
|
||||
User personas for targeted content.
|
||||
- **id** (UUID)
|
||||
- **avatar_key** (String)
|
||||
- **base_name** (String)
|
||||
- **wealth_cluster** (String)
|
||||
- **business_niches** (JSON)
|
||||
- **data** (JSON): Pain points, desires, etc.
|
||||
|
||||
### `avatar_variants`
|
||||
Variations of personas.
|
||||
- **id** (UUID)
|
||||
- **avatar_key** (String)
|
||||
- **variant_type** (String)
|
||||
- **data** (JSON)
|
||||
|
||||
### `geo_intelligence`
|
||||
Location data clusters.
|
||||
- **id** (UUID)
|
||||
- **cluster_key** (String)
|
||||
- **data** (JSON): Demographics, local keywords
|
||||
|
||||
### `offer_blocks`
|
||||
Universal and personalized offer content.
|
||||
- **id** (UUID)
|
||||
- **block_type** (String)
|
||||
- **avatar_key** (String)
|
||||
- **data** (JSON)
|
||||
|
||||
### `quality_flags`
|
||||
Content quality control issues.
|
||||
- **id** (UUID)
|
||||
- **site** (M2O -> sites)
|
||||
- **batch_id** (String)
|
||||
- **article_a** (String)
|
||||
- **article_b** (String)
|
||||
- **collision_text** (Text)
|
||||
- **similarity_score** (Float)
|
||||
- **status** (String): `pending` | `resolved` | `ignored`
|
||||
|
||||
---
|
||||
|
||||
## 5. Analytics & Tracking
|
||||
|
||||
### `events`
|
||||
Custom user interactions.
|
||||
- **id** (UUID)
|
||||
- **site** (M2O -> sites)
|
||||
- **event_name** (String)
|
||||
- **event_category** (String)
|
||||
- **event_label** (String)
|
||||
- **event_value** (Integer)
|
||||
- **page_path** (String)
|
||||
- **session_id** (String)
|
||||
- **visitor_id** (String)
|
||||
- **metadata** (JSON)
|
||||
- **timestamp** (Timestamp)
|
||||
|
||||
### `pageviews`
|
||||
Traffic logging.
|
||||
- **id** (UUID)
|
||||
- **site** (M2O -> sites)
|
||||
- **page_path** (String)
|
||||
- **page_title** (String)
|
||||
- **referrer** (String)
|
||||
- **user_agent** (String)
|
||||
- **ip_address** (String)
|
||||
- **device_type** (String)
|
||||
- **browser** (String)
|
||||
- **os** (String)
|
||||
- **utm_source** (String)
|
||||
- **utm_medium** (String)
|
||||
- **utm_campaign** (String)
|
||||
- **is_bot** (Boolean)
|
||||
- **bot_name** (String)
|
||||
- **timestamp** (Timestamp)
|
||||
|
||||
### `conversions`
|
||||
Goal completions.
|
||||
- **id** (UUID)
|
||||
- **site** (M2O -> sites)
|
||||
- **lead** (M2O -> leads)
|
||||
- **conversion_type** (String)
|
||||
- **value** (Float)
|
||||
- **currency** (String)
|
||||
- **source** (String)
|
||||
- **sent_to_google** (Boolean)
|
||||
- **sent_to_facebook** (Boolean)
|
||||
|
||||
### `site_analytics`
|
||||
Analytics configuration per site.
|
||||
- **id** (UUID)
|
||||
- **site** (M2O -> sites)
|
||||
- **google_ads_id** (String)
|
||||
- **google_ads_conversion_label** (String)
|
||||
- **fb_pixel_id** (String)
|
||||
- **fb_access_token** (String)
|
||||
|
||||
---
|
||||
|
||||
## 6. Infrastructure
|
||||
|
||||
### `hub_pages`
|
||||
Programmatic internal linking hubs.
|
||||
- **id** (UUID)
|
||||
- **site** (M2O -> sites)
|
||||
- **title** (String)
|
||||
- **slug** (String)
|
||||
- **parent_hub** (M2O -> hub_pages)
|
||||
- **level** (Integer)
|
||||
- **articles_count** (Integer)
|
||||
- **schema_json** (JSON)
|
||||
|
||||
### `link_targets`
|
||||
Internal linking destinations.
|
||||
- **id** (UUID)
|
||||
- **site** (M2O -> sites)
|
||||
- **target_url** (String)
|
||||
- **anchor_text** (String)
|
||||
- **anchor_variations** (JSON)
|
||||
- **priority** (Integer)
|
||||
- **is_active** (Boolean)
|
||||
- **is_hub** (Boolean)
|
||||
|
||||
### `work_log`
|
||||
System audit trail.
|
||||
- **id** (UUID)
|
||||
- **site** (M2O -> sites)
|
||||
- **action** (String)
|
||||
- **entity_type** (String)
|
||||
- **entity_id** (String)
|
||||
- **details** (JSON)
|
||||
- **user** (String)
|
||||
- **timestamp** (Timestamp)
|
||||
Reference in New Issue
Block a user