GatorSquare Knowledge Graph Schema
The knowledge graph is the connective tissue between investigations. Every investigation stands alone as a visual piece — the graph reveals that they are chapters in the same book.
This schema is the PLATFORM CONTRACT. Every field name, every category, every structure must match EXACTLY. No synonyms. No variants. No creative reinterpretation.
Entity Categories (8 — LOCKED)
| Category | What It Represents | Examples |
|---|
| people | Named individuals who exercised agency | Nixon, Kissinger, Mossadegh, Soleimani |
| places | Geographic locations, countries, cities, regions, bases | Iran, Strait of Hormuz, Al Udeid, Baghdad |
| institutions | Organizations that persist beyond individuals | CIA, IRGC, OPEC, IMF, Hezbollah, CENTCOM |
| concepts | Abstract patterns, doctrines, theoretical frameworks | Forward Defense, Containment Doctrine, Asymmetric Warfare |
| events | Specific historical occurrences with dates | Iran Coup 1953, Operation Epic Fury 2026, Gulf War 1991 |
| mechanisms | Operational processes, policy tools, feedback loops, pipelines | Sanctions Regime, Arms Pipeline, Proxy Funding Channel |
| systems | Recurring mechanisms of power, trade, or control | Petrodollar System, IRGC Proxy Network, US Base Archipelago |
| commodities | Physical goods whose trade creates geopolitical structure | Oil, Uranium, Missiles, Drones |
These 8 categories are NON-NEGOTIABLE. No other values are accepted.
Common mistakes the AI makes:
country / countries / location → use placesperson / actor / figure → use peopleorganization / group → use institutionsevent (singular) → use eventseconomic → use commodities or mechanismshumanitarian → use conceptsinfrastructure → use mechanisms
Causal Relationship Types (12 — LOCKED)
| Relation | Meaning | Example |
|---|
| caused | A directly produced B | CIA → Iran Coup 1953 |
| triggered | A set B in motion (immediate catalyst) | Assassination → Proxy Retaliation |
| created | A brought B into existence | IRGC → Hezbollah |
| enabled | A made B possible without directly causing it | Cold War → CIA Covert Ops |
| funded | A provided money/resources for B | Iran → Houthi Missile Program |
| legitimized | A gave B political/legal cover | UN Resolution → Military Action |
| enforced | A compelled B through force/pressure | Sanctions → Economic Collapse |
| weakened | A reduced B's capacity (but didn't destroy) | Israel → Hezbollah (2024) |
| collapsed | A destroyed or ended B | Invasion → Ba'ath Party |
| opposed | A actively worked against B | Iran → US Regional Presence |
| resisted | A withstood B's effects | Proxy Network → Decapitation Strikes |
| warned_against | A cautioned about B's risks | Intelligence → Policy Makers |
| replaced | A took B's former role/position | New Leader → Assassinated Leader |
Edge direction: Always from cause to effect, from enabler to enabled. The arrow means "this made that happen/possible."
knowledge.json Schema (CANONICAL)
{
"project_id": "kebab-case-id",
"entities": [
{
"name": "Entity Name",
"category": "people|places|institutions|concepts|events|mechanisms|systems|commodities",
"description": "What it IS universally (context-independent, 1-2 sentences)",
"role": "What it DID in THIS investigation (investigation-specific)",
"panels": [2, 5, 8, 14, 22]
}
],
"causal_links": [
{
"from": "entity name",
"relation": "caused|triggered|created|enabled|funded|legitimized|enforced|weakened|collapsed|opposed|resisted|warned_against|replaced",
"to": "entity name",
"evidence_panel": 5
}
],
"causal_chains": [
{
"name": "Chain Name",
"description": "What structural mechanism this chain reveals",
"steps": ["step1", "step2", "step3", "step4"],
"panels": [3, 5, 8, 12]
}
],
"systems": [
{
"name": "System Name",
"description": "What this system does",
"entities": ["entity1", "entity2"]
}
],
"themes": [
{
"name": "Theme Name",
"description": "Structural pattern description",
"panels": [2, 8, 15]
}
],
"act_structure": [
{
"act": "EVOCATIVE ACT NAME",
"panels": [1, 2, 3, 4, 5],
"description": "What this act covers"
}
],
"emotion_arc": [
{"panel": 1, "emotion": "haunting", "note": "context"}
],
"cross_references": [
{"project_id": "other-project-id", "connection": "what links them", "type": "causal|thematic|structural"}
]
}
Field Rules
| Field | Type | Required | Notes |
|---|
project_id | string | YES | Kebab-case, matches folder name |
entities | array | YES | 100+ target. Every entity has name + category + description + role + panels |
causal_links | array | YES | 40+ target. Every link has from + relation + to + evidence_panel |
causal_chains | array | YES | 4+ chains, each with 4+ steps |
systems | array | YES | Extracted systems with member entities |
themes | array | YES | 5+ themes as objects (not strings) |
act_structure | array | YES | From plot.md — evocative names, not "Part 1" |
emotion_arc | array | YES | One entry per panel (25 entries for 25 panels) |
cross_references | array | YES | 3+ links to other investigations |
{
"project_id": "kebab-case-id",
"title": "Full Title",
"subtitle": "One-line hook",
"summary": "2-3 sentence overview",
"description": "Full paragraph for SEO/detail pages",
"author": "Author Name",
"author_role": "Role/Title",
"author_location": "City, Country",
"investigation_type": "systems|narrative|quantitative",
"investigation_date": "2026-03-22",
"topic_domain": "military history|economics|geopolitics|...",
"key_question": "The central question this investigation answers",
"thesis_statement": "One-sentence core finding",
"confidence_level": "high|medium|low",
"data_sources": ["source1", "source2"],
"geographic_focus": ["Country1", "Country2"],
"historical_period": "1990-2026",
"systems_mapped": ["System Name 1", "System Name 2"],
"key_figures": ["Person 1", "Person 2"],
"panel_count": 25,
"estimated_word_count": 6800,
"viewer_style": "magazine|dossier|cinematic|...",
"topic_categories": ["History", "Security", "Geopolitics", "Economics"],
"tags": ["tag1", "tag2", "...10-20 keywords"],
"cross_references": [
{"project_id": "other-id", "connection": "description", "type": "causal|thematic|structural"}
]
}
| Field | Type | Required | WRONG variants to avoid |
|---|
author | string | YES | NOT an object. Never {"name": "...", "role": "..."} |
author_role | string | YES | Separate field, not nested inside author |
author_location | string | YES | Separate field, not nested inside author |
topic_categories | string[] | YES | NOT categories. Always capitalized: "History" not "history" |
systems_mapped | string[] | YES | NOT systems_investigated. Plain strings, not objects |
key_question | string | YES | Do not omit |
thesis_statement | string | YES | Do not omit |
confidence_level | string | YES | Do not omit |
panel_count | integer | YES | Do not omit |
estimated_word_count | integer | YES | Do not omit |
{
"panel_id": 1,
"speaker": "narrator",
"text": "Full narrative text",
"image": "panels/style-name/panel-01.png",
"word_count": 130,
"metadata": {
"stage": "THE EVENT",
"mood": "haunting",
"dimension": "historical",
"title": "PANEL TITLE",
"prompt_text": "AI image generation prompt"
}
}
| Field | Type | Required | WRONG variants |
|---|
panel_id | integer | YES | NOT id, NOT "moment-01" string |
word_count | integer | YES | Do not omit |
metadata | object | YES | stage/mood/dimension/title MUST be nested under metadata, NOT top-level |
Convergence — The Point of the Graph
The graph's value is convergence detection. When two investigations share an entity (matched by name), that's a signal:
| Shared Entity | Investigations | What It Means |
|---|
| IRGC | Epic Fury, IRGC Proxies | Same institution, different perspectives |
| Strait of Hormuz | Hormuz, Epic Fury | Geography linking military ops to energy |
| Oil | Hormuz, US Military 35yr | Commodity driving every intervention |
Entities MERGE by name across all projects. Same name = same node in Neo4j. The description stays stable. The role is per-investigation.
people: #4ADE80 (green)
institutions: #60A5FA (blue)
events: #F87171 (red)
systems: #FB923C (orange)
concepts: #A78BFA (purple)
mechanisms: #2DD4BF (teal)
places: #9CA3AF (grey)
commodities: #FBBF24 (gold)
These colors are locked in the platform. Using wrong categories means wrong colors in the graph visualization.
Naming Conventions
- Entity names: Title case, human-readable. "IRGC", "Strait of Hormuz", "Operation Epic Fury"
- Keep names stable: once an entity name exists in one investigation, reuse the EXACT same name in every other investigation. The name is the merge key.
- One entity, one name: Don't create "CIA" and "Central Intelligence Agency" as separate entities. Pick one. Canonicalize.
- project_id: lowercase, hyphenated.
us-military-middle-east-1990-2026