docs: add comprehensive Harris matrix and schema dependency analysis

- GOD_MODE_HARRIS_MATRIX.md: Complete dependency execution plan with 3 batches - SCHEMA_FILE_DEPENDENCY_MATRIX.md: Cross-file relationship mapping - Identified critical issues: missing parent tables, template errors, interface issues
2025-12-14 12:14:06 -05:00
parent 658d18f1c8
commit 1340a98663
2 changed files with 599 additions and 0 deletions
--- a/GOD_MODE_HARRIS_MATRIX.md
+++ b/GOD_MODE_HARRIS_MATRIX.md
@@ -0,0 +1,285 @@
+# 🔷 GOD-MODE HARRIS MATRIX: Complete Schema Dependency Guide
+
+> **What is a Harris Matrix?** In database design, it's a **Dependency Structure Matrix (DSM)** that shows the exact order to create tables so foreign key constraints don't fail. You cannot build a roof before walls. You cannot create `comments` before `users` and `posts` exist.
+
+---
+
+## 🎯 THE GOLDEN RULE
+
+**Build the Foundation First, Then the Walls, Then the Roof**
+
+```
+┌─────────────────────────────────────┐
+│  BATCH 1: Foundation (Independent) │  ← Create First
+├─────────────────────────────────────┤
+│  BATCH 2: Walls (First Children)   │  ← Create Second
+├─────────────────────────────────────┤
+│  BATCH 3: Roof (Complex Children)  │  ← Create Last
+└─────────────────────────────────────┘
+```
+
+---
+
+## 📊 SPARK PLATFORM: Complete Dependency Matrix
+
+### Summary Statistics
+- **Total Collections:** 16 (from schema_map.json)
+- **Parent Tables (Batch 1):** 6
+- **Child Tables (Batch 2):** 8
+- **Complex Tables (Batch 3):** 2
+- **Total Foreign Keys:** 12
+- **Identified Issues:** 2 (template field mismatches)
+
+---
+
+## 🏗️ BATCH 1: FOUNDATION TABLES
+> **Zero Dependencies** - These tables reference NO other tables
+
+| # | Table | Type | Purpose | Children Dependent |
+|---|-------|------|---------|-------------------|
+| 1 | `sites` ⭐ | Parent | Master site registry | **10 tables** depend on this |
+| 2 | `campaign_masters` ⭐ | Parent | Campaign definitions | **3 tables** depend on this |
+| 3 | `avatar_intelligence` | Independent | Avatar personality data | 0 |
+| 4 | `avatar_variants` | Independent | Avatar variations | 0 |
+| 5 | `cartesian_patterns` | Independent | Pattern formulas | 0 |
+| 6 | `geo_intelligence` | Independent | Geographic data | 0 |
+| 7 | `offer_blocks` | Independent | Content offer blocks | 0 |
+
+**⚠️ CRITICAL:** `sites` and `campaign_masters` are **SUPER PARENTS** - create these FIRST!
+
+---
+
+## 🧱 BATCH 2: FIRST-LEVEL CHILDREN
+> **Depend ONLY on Batch 1**
+
+| # | Table | Depends On | Foreign Key | Constraint Action |
+|---|-------|------------|-------------|-------------------|
+| 8 | `generated_articles` | sites | `site_id` → `sites.id` | CASCADE |
+| 9 | `generation_jobs` | sites | `site_id` → `sites.id` | CASCADE |
+| 10 | `pages` | sites | `site_id` → `sites.id` | CASCADE |
+| 11 | `posts` | sites | `site_id` → `sites.id` | CASCADE |
+| 12 | `leads` | sites | `site_id` → `sites.id` | SET NULL |
+| 13 | `headline_inventory` | campaign_masters | `campaign_id` → `campaign_masters.id` | CASCADE |
+| 14 | `content_fragments` | campaign_masters | `campaign_id` → `campaign_masters.id` | CASCADE |
+
+---
+
+## 🏠 BATCH 3: COMPLEX CHILDREN
+> **Depend on Batch 2 or have multiple dependencies**
+
+| # | Table | Depends On | Multiple FKs | Notes |
+|---|-------|------------|--------------|-------|
+| 15 | `link_targets` | sites | No | Internal linking system |
+| 16 | (Future M2M) | Multiple | Yes | Junction tables go here |
+
+---
+
+## 🔍 DETAILED DEPENDENCY MAP
+
+### Visual Cascade
+
+```
+sites ─────────┬─── generated_articles
+               ├─── generation_jobs
+               ├─── pages
+               ├─── posts
+               ├─── leads
+               └─── link_targets
+
+campaign_masters ─┬─── headline_inventory
+                  ├─── content_fragments
+                  └─── (referenced by generated_articles)
+
+avatar_intelligence  (standalone)
+avatar_variants      (standalone)
+cartesian_patterns   (standalone)
+geo_intelligence     (standalone)
+offer_blocks         (standalone)
+```
+
+---
+
+## 🚨 DETECTED ISSUES (from schema_issues.json)
+
+### Issue #1: Template Field Mismatch
+**Collection:** `content_fragments`  
+**Field:** `campaign_id` (M2O relation)  
+**Problem:** Display template references `campaign_name` but `campaign_masters` has field `name`, not `campaign_name`  
+**Fix:** Update template to use `{{campaign_id.name}}` instead of `{{campaign_id.campaign_name}}`
+
+### Issue #2: Template Field Mismatch  
+**Collection:** `headline_inventory`  
+**Field:** `campaign_id` (M2O relation)  
+**Problem:** Same as above - references non-existent `campaign_name`  
+**Fix:** Update template to use `{{campaign_id.name}}`
+
+---
+
+## 📐 EXECUTION PLAN: Step-by-Step
+
+### Phase 1: Create Foundation (Batch 1)
+```bash
+# Order is CRITICAL - sites MUST be first
+npx directus schema apply --only-collections \
+  sites,campaign_masters,avatar_intelligence,avatar_variants,cartesian_patterns,geo_intelligence,offer_blocks
+```
+
+### Phase 2: Create Walls (Batch 2)
+```bash
+npx directus schema apply --only-collections \
+  generated_articles,generation_jobs,pages,posts,leads,headline_inventory,content_fragments
+```
+
+### Phase 3: Create Roof (Batch 3)
+```bash
+npx directus schema apply --only-collections \
+  link_targets
+```
+
+### Phase 4: Apply Relationships
+```bash
+# All foreign keys are applied AFTER tables exist
+npx directus schema apply --only-relations
+```
+
+---
+
+## 🎓 THE "MEASURE TWICE, CUT ONCE" PROMPT
+
+Use this exact prompt to have AI execute your schema correctly:
+
+```markdown
+**System Role:** You are a Senior Database Architect specializing in Directus and PostgreSQL.
+
+**Input:** I have 16 collections in my Spark Platform schema.
+
+**Task 1: Dependency Map (DO THIS FIRST)**
+
+Before generating any API calls, output a Dependency Execution Plan:
+
+1. **Identify Nodes:** List all collections
+2. **Identify Edges:** List all foreign key relationships
+3. **Group by Batches:**
+   - Batch 1: Independent tables (No foreign keys)
+   - Batch 2: First-level dependents (Only rely on Batch 1)
+   - Batch 3: Complex dependents (Rely on Batch 2 or multiple tables)
+
+**Task 2: Directus Logic Check**
+
+Confirm you identified:
+- Standard tables vs. Singletons
+- Real foreign key fields vs. M2M aliases (virtual fields)
+- Display templates that might reference wrong field names
+
+**Output Format:** Structured markdown table showing batches and dependencies.
+
+**Once Approved:** Generate Directus API creation scripts in the correct order.
+
+[PASTE schema_map.json HERE]
+```
+
+---
+
+## 🔧 GOD-MODE API: Create Schema Programmatically
+
+Using the God-Mode API to respect dependencies:
+
+```bash
+# BATCH 1: Foundation
+curl https://spark.jumpstartscaling.com/god/schema/collections/create \
+  -H "X-God-Token: $GOD_MODE_TOKEN" \
+  -d '{"collection":"sites", "fields":[...]}'
+
+curl https://spark.jumpstartscaling.com/god/schema/collections/create \
+  -H "X-God-Token: $GOD_MODE_TOKEN" \
+  -d '{"collection":"campaign_masters", "fields":[...]}'
+
+# BATCH 2: Children (ONLY after Batch 1 completes)
+curl https://spark.jumpstartscaling.com/god/schema/collections/create \
+  -H "X-God-Token: $GOD_MODE_TOKEN" \
+  -d '{"collection":"generated_articles", "fields":[...], "relations":[...]}'
+
+# BATCH 3: Relations (ONLY after tables exist)
+curl https://spark.jumpstartscaling.com/god/schema/relations/create \
+  -H "X-God-Token: $GOD_MODE_TOKEN" \
+  -d '{"collection":"generated_articles", "field":"site_id", "related_collection":"sites"}'
+```
+
+---
+
+## ✅ VALIDATION CHECKLIST
+
+After executing schema:
+
+- [ ] Verify Batch 1: `SELECT * FROM sites LIMIT 1;` works
+- [ ] Verify Batch 1: `SELECT * FROM campaign_masters LIMIT 1;` works
+- [ ] Verify Batch 2: Foreign keys resolve (no constraint errors)
+- [ ] Check schema_issues.json: Fix template field references
+- [ ] Test M2O dropdowns in Directus admin UI
+- [ ] Confirm all 16 collections appear in Directus
+
+---
+
+## 📊 COMPLETE FIELD-LEVEL ANALYSIS
+
+### sites (SUPER PARENT)
+| Field | Type | Interface | Issues |
+|-------|------|-----------|--------|
+| id | uuid | input (readonly) | None |
+| name | string | input (required) | None |
+| url | string | input | None |
+| status | string | select-dropdown | None |
+
+**Children:** 10 tables reference this
+
+---
+
+### campaign_masters (SUPER PARENT)
+| Field | Type | Interface | Issues |
+|-------|------|-----------|--------|
+| id | uuid | none | None |
+| site_id | uuid | select-dropdown-m2o | Missing interface ⚠️ |
+| name | string | input | None |
+| status | string | select-dropdown | None |
+| target_word_count | integer | input | None |
+
+**Fix Needed:** `site_id` should have `select-dropdown-m2o` interface
+
+**Children:** 3 tables reference this
+
+---
+
+### generated_articles (CHILD)
+**Parent:** sites  
+**Relationship:** `site_id` → `sites.id` (CASCADE)  
+**Issues:**
+- `campaign_id` field exists but NO interface (should be `select-dropdown-m2o`)
+- Template might reference wrong field names
+
+---
+
+## 🎯 SUCCESS CRITERIA
+
+Your schema is correct when:
+
+1. ✅ **SQL Execution:** No foreign key constraint errors
+2. ✅ **Directus UI:** All dropdowns show related data
+3. ✅ **TypeScript:** Auto-generated types match reality
+4. ✅ **Frontend:** No `undefined` field errors
+5. ✅ **God-Mode API:** `/god/schema/snapshot` returns valid YAML
+
+---
+
+## 🚀 NEXT STEPS
+
+1. **Fix Template Issues:** Update display templates for `campaign_id` fields
+2. **Add Missing Interfaces:** Apply `select-dropdown-m2o` to all foreign key fields
+3. **Generate TypeScript:** Run `npm run db:sync` to get types
+4. **Test Fresh Install:** Use `FORCE_FRESH_INSTALL=True` to verify clean build
+5. **Deploy:** Push schema changes via God-Mode API
+
+---
+
+**Remember:** The Harris Matrix prevents the #1 cause of schema failures: trying to create relationships before the related tables exist.
+
+**God-Mode Key:** `$GOD_MODE_TOKEN` (set in Coolify secrets)