quarkshologridledger/reference/PROJECT.md

Here is a complete, self-contained REFERENCE.md file that captures the entire system architecture. It bridges your plaintext TanStack Start frontend with a high-performance Go-based data loader streaming raw YAML telemetry into a Valkey cache (the open-source, high-performance successor to Redis).

You can save this file locally to use as your architectural blueprint.

REFERENCE.md

Markdown

# Architectural Reference: Quark's Holo-Grid Ledger

This document serves as the absolute technical reference for the intergalactic terminal sportsbook. The architecture uses a three-tier design to handle high-frequency data streams safely and efficiently:
1. **Data Layer**: Flat YAML configuration files mimicking raw sub-atomic telemetry.
2. **Ingestion Layer (Go)**: A high-performance Go routine that parses YAML files and pushes records continuously into a Valkey cache instance.
3. **Application Layer (TanStack Start)**: A type-safe, server-rendered frontend pulling directly from Valkey via server functions and background synchronization hooks.

---

## 1. System Topology

```mermaid
graph LR
    subgraph Data Layer
        A[(telemetry.yaml)]
    </nav>
    subgraph Ingestion Layer
        B[Go Ingestion Worker]
    end
    subgraph Cache Layer
        C[(Valkey Cache Instance)]
    end
    subgraph Presentation Layer
        D[TanStack Start SSR Server] --> E[Browser Terminal UI]
    end

    A --> B
    B -- HSET / LPUSH --> C
    C -- READ --> D

2. Data Layer: Telemetry YAML Layout

Place these static definition assets under the ./data-source/ directory root.

File: ./data-source/sectors.yaml

YAML

sectors:
  - id: "sector-001"
    name: "Sector 001 (Earth Array)"
    quadrant: "Alpha"
    initial_shield_capacity: 100
    kinetic_yield: 4.2
    status: "LIVE"
    markets:
      - id: "s1-over"
        name: "Kinetic Yield Over 8.5 TW"
        initial_price: 1.85
      - id: "s1-under"
        name: "Kinetic Yield Under 8.5 TW"
        initial_price: 1.95

  - id: "wolf-359"
    name: "Wolf 359 Outpost"
    quadrant: "Alpha"
    initial_shield_capacity: 34
    kinetic_yield: 12.8
    status: "LIVE"
    markets:
      - id: "w359-fail"
        name: "Total Shield Failure"
        initial_price: 1.40
      - id: "w359-hold"
        name: "Defenses Hold Perimeter"
        initial_price: 2.80

3. Ingestion Layer: Go Worker Utility

This Go engine handles parsing the local YAML file, calculating artificial odds fluctuations, and writing live JSON payloads directly into Valkey using standard Redis protocol definitions via the go-redis/v9 driver.

File: ./ingestion-engine/main.go

Go

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"log"
	"math/rand"
	"os"
	"time"

	"[github.com/redis/go-redis/v9](https://github.com/redis/go-redis/v9)"
	"gopkg.in/yaml.v3"
)

type Market struct {
	ID    string  `yaml:"id" json:"id"`
	Name  string  `yaml:"name" json:"name"`
	Price float64 `yaml:"initial_price" json:"price"`
	Trend string  `json:"trend"`
}

type Sector struct {
	ID             string   `yaml:"id" json:"id"`
	Name           string   `yaml:"name" json:"name"`
	Quadrant       string   `yaml:"quadrant" json:"quadrant"`
	ShieldCapacity int      `yaml:"initial_shield_capacity" json:"shieldCapacity"`
	KineticYield   float64  `yaml:"kinetic_yield" json:"kinetic_yield"`
	Status         string   `yaml:"status" json:"status"`
	Markets        []Market `yaml:"markets" json:"markets"`
}

type Config struct {
	Sectors []Sector `yaml:"sectors"`
}

var ctx = context.Background()

func main() {
	// 1. Connect to Valkey (Using standard Redis protocol port 6379)
	valkeyClient := redis.NewClient(&redis.Options{
		Addr:     "localhost:6379",
		Password: "", // Default empty
		DB:       0,  // Default DB
	})

	// Test connection
	if err := valkeyClient.Ping(ctx).Err(); err != nil {
		log.Fatalf("Critical: Could not resolve Valkey connection: %v", err)
	}
	fmt.Println("> Subspace Comms Link to Valkey established.")

	// 2. Read and parse the YAML file
	yamlFile, err := os.ReadFile("../data-source/sectors.yaml")
	if err != nil {
		log.Fatalf("Error reading target file definitions: %v", err)
	}

	var config Config
	if err := yaml.Unmarshal(yamlFile, &config); err != nil {
		log.Fatalf("Error parsing configuration details: %v", err)
	}

	// 3. Fire the Ingestion Loop Simulation
	ticker := time.NewTicker(2000 * time.Millisecond)
	defer ticker.Stop()

	fmt.Println("> Telemetry engine loop initiated. Streaming telemetry logs...")

	for range ticker.C {
		for i := range config.Sectors {
			sector := &config.Sectors[i]

			// Fluctuate shield capacities artificially
			shieldChange := rand.Intn(5) - 2 // -2 to +2
			sector.ShieldCapacity += shieldChange
			if sector.ShieldCapacity > 100 {
				sector.ShieldCapacity = 100
			} else if sector.ShieldCapacity < 0 {
				sector.ShieldCapacity = 0
			}

			// Modulate marker coefficients
			for j := range sector.Markets {
				market := &sector.Markets[j]
				priceShift := (rand.Float64() * 0.2) - 0.1 // -0.10 to +0.10
				oldPrice := market.Price
				market.Price = oldPrice + priceShift

				if market.Price < 1.05 {
					market.Price = 1.05
				}

				if market.Price > oldPrice {
					market.Trend = "up"
				} else if market.Price < oldPrice {
					market.Trend = "down"
				} else {
					market.Trend = "stable"
				}
			}

			// Marshall state to absolute JSON for application caching efficiency
			jsonPayload, err := json.Marshal(sector)
			if err != nil {
				log.Printf("Error marshalling schema object: %v", err)
				continue
			}

			// Push atomic updates directly into Valkey hash set
			key := fmt.Sprintf("sector:telemetry:%s", sector.ID)
			err = valkeyClient.Set(ctx, key, jsonPayload, 0).Err()
			if err != nil {
				log.Printf("Valkey stream pipeline transmission error: %v", err)
			}
		}
		log.Println(">> Atomic telemetry matrix block sent to Valkey pipeline cluster.")
	}
}

4. Application Layer: Reading from Valkey in TanStack Start

Your frontend reads directly from the cache pool inside server execution limits. This guarantees sub-millisecond data delivery times to the rendering layer.

First, make sure you have standard client integration parameters ready (npm i ioredis).

File: ./src/server/db/valkeyConnector.ts

TypeScript

import Redis from 'ioredis'

// Connect to local Valkey instance over port 6379
export const valkey = new Redis({
  host: '127.0.0.1',
  port: 6379,
})

export async function fetchLiveSectorFromCache(sectorId: string) {
  const data = await valkey.get(`sector:telemetry:${sectorId}`)
  if (!data) return null
  return JSON.parse(data)
}

File: ./src/routes/quadrants/$sectorId.tsx

TypeScript

import { createFileRoute } from '@tanstack/react-router'
import { useQuery } from '@tanstack/react-query'
import { fetchLiveSectorFromCache } from '../../server/db/valkeyConnector'
import { createServerFn } from '@tanstack/react-start'

// Server RPC definition boundary
const getCachedSectorData = createServerFn({ method: 'GET' })
  .input(String)
  .handler(async ({ input: sectorId }) => {
    return await fetchLiveSectorFromCache(sectorId)
  })

export const Route = createFileRoute('/quadrants/$sectorId')({
  loader: async ({ params }) => {
    const initialSnapshot = await getCachedSectorData({ input: params.sectorId })
    return { initialSnapshot }
  },
  component: TerminalGridPane,
})

function TerminalGridPane() {
  const { initialSnapshot } = Route.useLoaderData()
  const { sectorId } = Route.useParams()

  // High-frequency client polling strategy linking right back to Valkey keyspaces
  const { data: sector } = useQuery({
    queryKey: ['live-telemetry', sectorId],
    queryFn: () => getCachedSectorData({ input: sectorId }),
    initialData: initialSnapshot,
    refetchInterval: 2000, 
  })

  if (!sector) return <pre className="text-rose-500">&gt; ERROR: MATRIX SYNC COMPROMISED</pre>

  return (
    <div className="border border-emerald-500/30 p-4 bg-black font-mono">
      <h3 className="text-emerald-400 font-bold mb-2">&gt; COGNITIVE STREAM: {sector.name}</h3>
      <div className="space-y-1 text-xs">
        <p>QUADRANT TELEMETRY: {sector.quadrant}</p>
        <p>SHIELD EFFICIENCY: <span className="text-amber-500">{sector.shieldCapacity}%</span></p>
      </div>
      
      {/* Dynamic Betting Selections Render */}
      <div className="mt-4 grid grid-cols-1 gap-2">
        {sector.markets.map((m: any) => (
          <button key={m.id} className="p-2 border border-slate-800 text-left hover:border-emerald-500 flex justify-between">
            <span>{m.name}</span>
            <span className={m.trend === 'up' ? 'text-emerald-400' : m.trend === 'down' ? 'text-rose-400' : 'text-slate-400'}>
              [{m.price.toFixed(2)}]
            </span>
          </button>
        ))}
      </div>
    </div>
  )
}

To bring factions into your data, you just need to explicitly name the two competing forces inside your Sectors. In a sportsbook, these are your Home Team and Away Team (or Competitor A and Competitor B).

By adding a factions object to your data model, your Go engine can calculate specific tactical advantages, and your TanStack Start frontend can render a true "Versus" scoreboard layout.

Here is how you inject factions across your entire architecture.

1. Update the Data Layer (data-source/sectors.yaml)

Add a factions object to each sector inside your YAML file. Give each faction a clear name and track their individual shield capacities separately instead of having just one global shield score.

YAML

sectors:
  - id: "sector-001"
    name: "Sector 001 (Earth Array)"
    quadrant: "Alpha"
    kinetic_yield: 4.2
    status: "LIVE"
    factions:
      home:
        name: "Starfleet Command"
        shield_capacity: 100
      away:
        name: "The Borg Collective"
        shield_capacity: 100
    markets:
      - id: "s1-home-win"
        name: "Starfleet Victory"
        initial_price: 2.10
      - id: "s1-away-win"
        name: "Borg Assimilation"
        initial_price: 1.65

2. Update the Go Ingestion Engine (main.go)

Now, update your Go structs to parse these factions, and modify the engine loop so the factions actively damage each other's shields.

Go

type Faction struct {
	Name           string `yaml:"name" json:"name"`
	ShieldCapacity int    `yaml:"shield_capacity" json:"shieldCapacity"`
}

type FactionsSchema struct {
	Home Faction `yaml:"home" json:"home"`
	Away Faction `yaml:"away" json:"away"`
}

type Sector struct {
	ID           string         `yaml:"id" json:"id"`
	Name         string         `yaml:"name" json:"name"`
	Quadrant     string         `yaml:"quadrant" json:"quadrant"`
	KineticYield float64        `yaml:"kinetic_yield" json:"kinetic_yield"`
	Status       string         `yaml:"status" json:"status"`
	Factions     FactionsSchema `yaml:"factions" json:"factions"`
	Markets      []Market       `yaml:"markets" json:"markets"`
}

// Inside the background loop, simulate combat between the factions:
for i := range config.Sectors {
    sector := &config.Sectors[i]
    
    // Randomly choose which faction takes a hit this tick
    if rand.Float64() > 0.5 {
        sector.Factions.Home.ShieldCapacity -= rand.Intn(8) // Borg fires on Starfleet
    } else {
        sector.Factions.Away.ShieldCapacity -= rand.Intn(5) // Starfleet fires on Borg
    }
    
    // Clamp values between 0 and 100
    if sector.Factions.Home.ShieldCapacity < 0 { sector.Factions.Home.ShieldCapacity = 0 }
    if sector.Factions.Away.ShieldCapacity < 0 { sector.Factions.Away.ShieldCapacity = 0 }
    
    // Dynamically shift odds based on who has higher shields
    for j := range sector.Markets {
        market := &sector.Markets[j]
        // If Home shields drop below Away shields, increase Home odds multiplier (underdog status)
        if sector.Factions.Home.ShieldCapacity < sector.Factions.Away.ShieldCapacity {
            if market.ID == "s1-home-win" { market.Price += 0.05 }
        }
    }
}

3. Render the Confrontation in the UI ($sectorId.tsx)

Now that Valkey is serving the detailed faction data, you can build a plaintext split-panel scoreboard at the top of your main grid layout.

TypeScript

function SectorConsoleView() {
  const { sectorId } = Route.useParams()
  const { data: sector } = useQuery({
    queryKey: ['live-telemetry', sectorId],
    queryFn: () => getCachedSectorData({ input: sectorId }),
    refetchInterval: 2000, 
  })

  if (!sector) return <pre>&gt; ACCESSING SYSTEM NET...</pre>

  return (
    <div className="space-y-4">
      {/* Dynamic Versus Arena Header */}
      <div className="border border-slate-800 bg-slate-950 p-4 font-mono text-center">
        <div className="text-[10px] text-slate-500 mb-2">ENGAGEMENT MATRIX // {sector.name}</div>
        
        <div className="grid grid-cols-7 items-center text-sm font-bold">
          {/* Home Faction */}
          <div className="col-span-3 text-right">
            <span className="text-amber-400 block">{sector.factions.home.name}</span>
            <span className="text-xs text-slate-400">SHD: {sector.factions.home.shieldCapacity}%</span>
          </div>
          
          {/* VS Divider */}
          <div className="col-span-1 text-slate-600 tracking-widest animate-pulse text-xs">VS</div>
          
          {/* Away Faction */}
          <div className="col-span-3 text-left">
            <span className="text-rose-400 block">{sector.factions.away.name}</span>
            <span className="text-xs text-slate-400">SHD: {sector.factions.away.shieldCapacity}%</span>
          </div>
        </div>

        {/* Global Match Clock / Energy Tracker */}
        <div className="mt-3 border-t border-slate-900 pt-2 text-xs text-slate-500 flex justify-between px-4">
          <span>TOTAL ENERGY RELEASED:</span>
          <span className="text-emerald-400 font-bold">{sector.kinetic_yield.toFixed(1)} TW</span>
        </div>
      </div>

      {/* Markets Selection Grid sits underneath this header view */}
    </div>
  )
}

Here is your consolidated, terminal-ready command dictionary mapping our Star Trek Telemetry to standard Sportsbook Architecture:

Space-Grid Term	Real-World Sportsbook Translation	Practical Example
Quadrant	Sport Category / League	Alpha Quadrant (Matches your top-level category menu, like filtering for Premier League or NBA).
Sector	Individual Match / Fixture	Sector 001 or Wolf 359 (The active "game page" where an event is currently happening).
Factions	Teams / Contenders	Starfleet Command (Home) vs. The Borg Collective (Away) (The competitors squaring off inside the arena).
Shield Capacity	Live Defensive Metric / Health	Starfleet Shields: 74% (Acts like an active match timeline indicator, showing which side is taking damage or losing control).
Kinetic Yield	Live In-Play Match Score	14.2 Terawatts released (The cumulative scoreboard counter that grows as action happens, like total points scored).
Market	Betting Line / Wager Type	Faction Victory or Total Kinetic Yield Over/Under (The explicit proposal lines a user risks their Latinum on).
Latinum	Account Balance Base Currency	Gold-Pressed Latinum (The account balance backing your betslip tokens).
Subspace Interruption	Odds Change Suspended Lockout	Market Suspended (The background Valkey cache triggers an automatic input lockout when a sudden scoring event happens).

To generate a continuous, realistic stream of sports matches (Sectors) and betting options (Markets), you shouldn't hardcode individual events. Instead, you need a stable, static Taxonomy Base Data file.

Think of this base taxonomy file as a template library. Your Go ingestion engine will read this library, pick two opposing factions, assign them a sector arena, and generate the live match data dynamically.

Here is the structured YAML blueprint for your taxonomy database and how the generation engine maps it out.

1. The Core Taxonomy Configuration (data-source/taxonomy.yaml)

This file holds your static master rules. It defines what factions exist, which quadrants they belong to, their natural rivalries, and standard betting templates.

YAML

# data-source/taxonomy.yaml

quadrants:
  - id: "alpha"
    name: "Alpha Quadrant"
    factions:
      - id: "starfleet"
        name: "Starfleet Command"
        type: "defensive"
      - id: "borg"
        name: "The Borg Collective"
        type: "aggressive"
      - id: "cardassians"
        name: "Cardassian Union"
        type: "tactical"

  - id: "beta"
    name: "Beta Quadrant"
    factions:
      - id: "klingons"
        name: "Klingon Empire"
        type: "aggressive"
      - id: "romulans"
        name: "Romulan Star Empire"
        type: "tactical"

# Standard templates used by the generator to instantiate structural betting lines
market_templates:
  - id: "match-outcomes"
    name: "Combat Resolution"
    selections:
      - type: "home-win"
        suffix: "Decisive Victory"
      - type: "away-win"
        suffix: "Decisive Victory"
  
  - id: "kinetic-over-under"
    name: "Total Kinetic Yield"
    selections:
      - type: "over"
        name: "Over 8.5 Terawatts"
        base_price: 1.85
      - type: "under"
        name: "Under 8.5 Terawatts"
        base_price: 1.85

# A list of location names the engine can pick to host matches
sector_pool:
  - id: "wolf-359"
    name: "Wolf 359 Outpost"
    quadrant: "alpha"
  - id: "sector-001"
    name: "Sector 001 (Earth Core)"
    quadrant: "alpha"
  - id: "narendra-3"
    name: "Narendra III Outpost"
    quadrant: "beta"

2. The Generation Blueprint: From Rules to Live Data

When your Go ingestion engine spins up, it loops through this taxonomy file to generate actual live events using an instantiation pattern:

Plaintext

  [ TAXONOMY DEFINITION ]
            │
            ▼ (Go Generator Engine)
  1. Pick Location: "Wolf 359" (Alpha)
  2. Pick Home Faction: "Starfleet Command"
  3. Pick Away Faction: "The Borg Collective"
  4. Hydrate Market Templates: Substitute Faction names into strings
            │
            ▼
  [ LIVE VALKEY DATA STRUCTURE ]

3. The Go Generation Logic (Conceptual Snippet)

This is how your Go ingestion worker takes the abstract templates from taxonomy.yaml and handles generating real live event instances:

Go

// Psuedocode for the Go template instantiation loop
func GenerateLiveEvent(location SectorPoolItem, home Faction, away Faction, templates []MarketTemplate) Sector {
    var generatedMarkets []Market

    for _, tmpl := range templates {
        if tmpl.ID == "match-outcomes" {
            generatedMarkets = append(generatedMarkets, Market{
                ID:    location.ID + "-moneyline-home",
                Name:  home.Name + " " + tmpl.Selections[0].Suffix, // "Starfleet Command Decisive Victory"
                Price: 2.00, // Balanced starting base odds
            })
            generatedMarkets = append(generatedMarkets, Market{
                ID:    location.ID + "-moneyline-away",
                Name:  away.Name + " " + tmpl.Selections[1].Suffix, // "The Borg Collective Decisive Victory"
                Price: 1.80, // Borg slight favorite based on aggressive profile
            })
        }
    }

    return Sector{
        ID:       location.ID,
        Name:     location.Name,
        Quadrant: location.Quadrant,
        Status:   "LIVE",
        Factions: FactionsSchema{
            Home: FactionState{Name: home.Name, ShieldCapacity: 100},
            Away: FactionState{Name: away.Name, ShieldCapacity: 100},
        },
        Markets: generatedMarkets,
    }
}

By organizing your database logic this way, you can add new teams (factions) or new stadiums (sectors) directly to your taxonomy.yaml file without altering a single line of your Go simulation logic or your TanStack Start React components. Everything down the wire becomes purely data-driven!