Source: data_layer/docs/ARCHITECTURE_VISUAL.md
Multi-Database Architecture - Visual Guide
System Overview
┌─────────────────────────────────────────────────────────────┐
│ JSONL Seed Files │
│ (Source of Truth) │
│ │
│ ├── seeds/ │
│ │ ├── ufc.json │
│ │ ├── f1.json │
│ │ └── ... │
│ └── seed.examples-kb/data/ │
│ ├── triage.jsonl │
│ └── contract_generation.jsonl │
└─────────────────────────────────────────────────────────────┘
↓
seed_supabase_multi_db.py
↓
┌─────────────────────────────────────────────────────────────┐
│ Supabase PostgreSQL (Primary DB) │
│ REQUIRED ✅ │
│ │
│ Tables: │
│ ├── sport_archetypes (5 master categories) │
│ ├── prospective_leagues (all leagues + sync tracking) │
│ └── few_shot_examples (AI examples) │
│ │
│ Features: │
│ ├── Fast queries (indexed) │
│ ├── Sync status tracking │
│ ├── Embedding storage (JSONB) │
│ └── ACID transactions │
└─────────────────────────────────────────────────────────────┘
↓ ↓
┌─────────────────┐ ┌─────────────────┐
│ Neo4j Graph │ │ Pinecone Vector │
│ OPTIONAL │ │ OPTIONAL │
│ ⭕ │ │ ⭕ │
└─────────────────┘ └─────────────────┘
↓ ↓
┌─────────────────┐ ┌─────────────────┐
│ Graph Relations │ │ Semantic Search │
│ │ │ │
│ Nodes: │ │ Indexes: │
│ • SportArchetype│ │ • altsports- │
│ • League │ │ leagues │
│ │ │ • altsports- │
│ Relationships: │ │ examples │
│ • BELONGS_TO_ │ │ │
│ ARCHETYPE │ │ Features: │
│ │ │ • Vector search │
│ Features: │ │ • Similarity │
│ • Pattern │ │ • Top-K results │
│ discovery │ │ │
│ • Archetype │ │ │
│ navigation │ │ │
└─────────────────┘ └─────────────────┘Sport Archetype System
┌─────────────────────────────────────────────────────────────┐
│ 5 Master Sport Archetypes │
└─────────────────────────────────────────────────────────────┘
↓ ↓ ↓ ↓ ↓
┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
│ Racing │ │ Combat │ │ Team │ │Precision│ │ Large │
│ │ │ │ │ Sport │ │ │ │ Field │
└────────┘ └────────┘ └────────┘ └────────┘ └────────┘
↓ ↓ ↓ ↓ ↓
┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
│ F1 │ │ UFC │ │ Soccer │ │ Golf │ │Marathon│
│ NASCAR │ │ Boxing │ │Basketball│ │Archery │ │Triathlon│
│ Horse │ │Muay Thai│ │ Hockey │ │ Darts │ │Cycling │
│ Racing │ │Wrestling│ │Volleyball│ │Shooting│ │ Ski │
└────────┘ └────────┘ └────────┘ └────────┘ └────────┘Data Flow
Seeding Flow
1. Read JSONL ──→ 2. Generate Embedding ──→ 3. Upsert Supabase
↓
OpenAI API
(text-embedding-3-small)
1536d
↓
↓
┌─────────────────────┴─────────────────────┐
↓ ↓
4. Sync to Neo4j 5. Sync to Pinecone
↓ ↓
CREATE (l:League) index.upsert(vector)
CREATE (a:SportArchetype) with metadata
MERGE (l)-[:BELONGS_TO]->(a) in namespace
↓ ↓
↓ ↓
6. Update Supabase sync status
neo4j_sync_status = 'synced'
pinecone_sync_status = 'synced'Query Flow
User Query: "Find high-speed racing leagues"
↓
1. Generate embedding
↓
OpenAI API
↓
↓
┌───────────────┴───────────────┐
↓ ↓
2. Vector Search 3. OR Direct Query
(Pinecone) (Supabase)
↓ ↓
Return league_tags Return leagues
↓ ↓
↓ ↓
4. Get full data from Supabase
WHERE league_tag IN (...)
↓
↓
5. (Optional) Get graph relationships
(Neo4j)
↓
MATCH (l)-[:BELONGS_TO_ARCHETYPE]->(a)
MATCH (sibling)-[:BELONGS_TO_ARCHETYPE]->(a)
↓
↓
6. Return results to userDatabase Sync Tracking
Supabase League Record:
┌─────────────────────────────────────────────┐
│ league_tag: "ufc" │
│ league_name: "Ultimate Fighting Championship│
│ sport_archetype: "combat" │
│ │
│ Neo4j Sync: │
│ ├── neo4j_node_id: "abc123" │
│ ├── neo4j_sync_status: "synced" │
│ └── neo4j_synced_at: "2025-10-10T..." │
│ │
│ Pinecone Sync: │
│ ├── pinecone_id: "ufc" │
│ ├── pinecone_namespace: "default" │
│ ├── pinecone_sync_status: "synced" │
│ └── pinecone_synced_at: "2025-10-10T..." │
│ │
│ Embedding: │
│ ├── embedding_vector: [0.123, -0.456, ...] │
│ ├── embedding_model: "text-embedding-3-small│
│ └── embedding_updated_at: "2025-10-10T..." │
└─────────────────────────────────────────────┘Graceful Degradation
Full System (All DBs Available):
┌──────────┐
│ Supabase │ ✅ Required
└──────────┘
↓
┌──────────┐
│ Neo4j │ ✅ Available → Graph features enabled
└──────────┘
↓
┌──────────┐
│ Pinecone │ ✅ Available → Semantic search enabled
└──────────┘
↓
┌──────────┐
│ OpenAI │ ✅ Available → Embeddings generated
└──────────┘
Degraded System (Supabase Only):
┌──────────┐
│ Supabase │ ✅ Required
└──────────┘
↓
┌──────────┐
│ Neo4j │ ⚠️ Not available → Graph features disabled
└──────────┘
↓
┌──────────┐
│ Pinecone │ ⚠️ Not available → Semantic search disabled
└──────────┘
↓
┌──────────┐
│ OpenAI │ ⚠️ Not available → No embeddings generated
└──────────┘
System still works! Just with reduced features.File Organization
database/
├── 📋 Documentation
│ ├── QUICKSTART_SUPABASE.md ⭐ Start here!
│ ├── SETUP_STATUS.md 📊 Status report
│ ├── SUPABASE_IMPLEMENTATION_SUMMARY.md
│ ├── COMPLETION_SUMMARY.md
│ ├── ARCHITECTURE_VISUAL.md 📊 This file
│ └── INDEX.md 🗺️ Navigation
│
├── 🔧 Scripts
│ ├── seed_supabase_multi_db.py ⭐ Unified seeding
│ ├── validate_supabase_multi_db.py ⭐ Validation
│ └── seed.examples.py 📝 Examples
│
├── 📦 Seeds
│ ├── seeds/ 🌱 League JSON files
│ └── seed.examples-kb/data/ 📚 JSONL examples
│
└── 📊 Schemas
├── schemas/models/neo4j/ 🕸️ Graph schema
└── (SQL in QUICKSTART) 🗄️ Supabase tablesCommand Flow
┌─────────────────────────────────────┐
│ 1. Validate Setup │
│ │
│ $ python scripts/ │
│ validate_supabase_multi_db.py │
│ │
│ Checks: │
│ ✅ Environment variables │
│ ✅ Database connections │
│ ✅ Seed files │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ 2. Seed Archetypes (Required) │
│ │
│ $ python scripts/ │
│ seed_supabase_multi_db.py │
│ --archetypes │
│ │
│ Creates: │
│ ✨ 5 sport archetype records │
│ ✨ Neo4j archetype nodes │
│ ✨ Pinecone archetype vectors │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ 3. Seed Leagues (Optional) │
│ │
│ $ python scripts/ │
│ seed_supabase_multi_db.py │
│ --leagues │
│ │
│ For each league JSON: │
│ ✨ Insert to Supabase │
│ ✨ Create Neo4j node │
│ ✨ Link to archetype │
│ ✨ Add to Pinecone │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ 4. Seed Examples (Optional) │
│ │
│ $ python scripts/ │
│ seed_supabase_multi_db.py │
│ --examples │
│ │
│ For each JSONL line: │
│ ✨ Insert to Supabase │
│ ✨ Add to Pinecone (by category) │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ 5. Query & Use │
│ │
│ Python: │
│ >>> from supabase import │
│ create_client │
│ >>> supabase.table(...).select() │
│ │
│ SQL (Supabase dashboard): │
│ SELECT * FROM prospective_leagues │
│ WHERE sport_archetype = 'combat' │
└─────────────────────────────────────┘Environment Setup
.env file:
┌─────────────────────────────────────┐
│ Required: │
│ SUPABASE_URL=postgresql://... │
│ SUPABASE_API_KEY=eyJhbGci... │
│ │
│ Optional (for embeddings): │
│ OPENAI_API_KEY=sk-... │
│ │
│ Optional (for graph): │
│ NEO4J_URI=bolt://localhost:7687 │
│ NEO4J_USERNAME=neo4j │
│ NEO4J_PASSWORD=... │
│ │
│ Optional (for vectors): │
│ PINECONE_API_KEY=... │
└─────────────────────────────────────┘Quick Start: See QUICKSTART_SUPABASE.md
Full Index: See INDEX.md
Status: ✅ Production Ready