LBS Foundry Documentation

Documentation for LBS Foundry — a sports content and data management platform built on event sourcing and CQRS. Start with Introduction for a platform overview.

This index is generated from each document's YAML frontmatter (type / title / description) by tools/docs/docs-index.mjs. Do not edit by hand — run pnpm docs:index after adding or moving a doc. See the documentation conventions.

Start here

• ClickHouse schema review — Foundry storage experiment note (archived) — Reviewed: 2026-04-21 • Schemas: ClickHouseSchemas.cs
• Introduction to the Sports Content and Data Management Platform concept — This document provides an overview of the Sports Content and Data Management Platform, designed to power real-time sports data feeds across multiple use cases...
• Centralized Authorization System reference — This document describes the centralized role-based authorization system implemented for commands and queries in the LBS Foundry platform.

Getting started

• Getting Started with LBS Foundry index — Welcome to the LBS Foundry development team! This guide will get you up and running with the codebase in no time.
• Quick Start: Testing Authentication with the SDK guide — This guide will help you test the new JWT authentication system end-to-end using the Foundry SDK.
• Backend Local Setup (Windows) guide — This guide walks you through setting up the LBS.Foundry backend locally on Windows. It assumes you have already completed the steps in prerequisites.md...
• Prerequisites & Environment Setup guide — This guide walks you through installing every tool you need before you can build and run LBS Foundry. Once everything here is installed, follow...

Architecture

• LBS Foundry Architecture Overview index — This guide provides a comprehensive overview of the LBS Foundry architecture, design patterns, and core principles.
• Domain-Driven Design: Aggregates, Events, and Commands concept — This guide explains how to implement domain-driven design (DDD) concepts using our event sourcing framework.
• Batch Command Execution Design design — This document outlines design options for executing multiple commands in a single API request, with support for transactional execution grouped by aggregate...
• Data Harvesters Overview concept — The Data Harvesters are responsible for ingesting real-time data from external sources into the system. These sources can include sports data feeds, social...
• Foundry Database Schema Diagram reference — The following contracts are registered in their own Marten modules for the main event store database, not the Foundry read model store:
• Event Sourcing Architecture concept — This document describes the event sourcing implementation in LBS Foundry, including patterns, practices, and technical details.
• Foundry — Architecture, Rationale & Glossary reference — Architecture, rationale, and glossary for the Foundry platform: what it is, what it delivers (a canonical record of the sport plus the full distribution of simulated game outcomes), and the canonical terminology.
• Foundry — Architecture Use Case Walk concept — A use-case walk of the Foundry architecture. Each walk traces a realistic
• Generic Query Pattern design — The generic query pattern provides abstract base classes for implementing common query operations (GetAll, GetById) while allowing derived classes to:
• Identity Linking — Problem & Solution Summary design — LBS.Foundry ingests sports data from multiple providers (FoxSports, SuperCoach, StatsPerform, NRL Web, and — in the NFL 2026-2027 initiative — NflVerse, ESPN)....
• Mermaid Diagram Update Prompt reference — Use this prompt at the end of any session where you've added or modified contracts, events, or contract builders. Paste it into Claude Code (or any AI...
• Multi-Host Concurrency Design design — The current TimerService implementation only controls concurrency within a single host process:
• Query-Command System Alignment Design design — This document outlines a design for aligning the query system architecture with the command system patterns to achieve consistency and reduce complexity.
• Real-Time Notification System - Technical Design design — Related ADR: real-time-notification-system.md
• LBS.EntityResolution — Provider-to-canonical-ID resolution reference — Resolves a provider's rows to Foundry canonical_ids — one canonical identity per real-world entity across every provider, so downstream Foundry Core joins...

Developer guide

• Developer Guide index — Day-to-day development reference for LBS Foundry. For platform overview see intro; for architecture see architecture/README.
• Adding Event History to Detail Pages guide — This guide shows how to add event history viewing capabilities to any aggregate detail page in Foundry.
• CI/CD Pipeline guide — This document describes the LBS Foundry continuous integration and deployment pipeline, implemented in .github/workflows/Build-Container-Apps.yml.
• Coding Standards guide — This guide outlines the coding standards and conventions for the LBS Foundry project. Following these standards ensures consistency, maintainability, and...
• Common Development Tasks guide — This guide covers the most common tasks you'll perform while developing LBS Foundry. Each task includes step-by-step instructions and examples.
• Debugging and Troubleshooting Guide guide — This guide covers common issues you might encounter while developing LBS Foundry and how to resolve them.
• Deployment Pipeline Setup Guide guide — This guide provides step-by-step instructions for setting up the deployment pipeline for LBS Foundry applications, including GitHub secrets configuration and...
• LBS Foundry Development Workflow guide — This guide outlines the internal development workflow and best practices for the LBS Foundry team.
• Event History Viewer (Backend) guide — This document describes the event history viewing feature in Foundry, which allows viewing the complete event stream for any aggregate.
• Event Versioning and Maintaining Backwards Compatibility guide — This guide explains how to version, rename, or retire an event in an event-sourced system without breaking replay, projections, local environments, or...
• Frequently Asked Questions (FAQ) guide — Common questions and answers for LBS Foundry developers.
• Generic Queries guide — Reusable base query records (GetAllQuery / GetByIdQuery) and their handlers for read models implementing IContract.
• Module System guide — The LBS module system provides a declarative way to enable/disable features and timers based on enabled modules. It integrates seamlessly with the Timer...
• Real-Time Notification System - Developer Guide guide — The LBS Foundry notification system provides real-time WebSocket-based notifications for database entity changes. It eliminates the need for polling and...
• GetByIdQuery Ownership Validation - Design Options design — This document outlines potential approaches for implementing ownership validation in GetByIdQuery. This is Phase 2 functionality that was deferred...
• Real-World Event Replay Testing guide — This guide explains how to create tests that replay production/staging events through builders to verify correct behavior and debug issues.
• Timer Infrastructure guide — LBS Foundry provides a declarative timer infrastructure for scheduling recurring tasks. Instead of writing manual SystemBackgroundService implementations with...

SDK

• SDK Generation & Publishing Process guide — This document explains how and when the TypeScript and Python SDKs are generated and published.
• SDK Generation Strategy & Versioning guide (archived) — RFC weighing whether to commit auto-generated SDK files, with a recommendation and versioning strategy.
• SDK Generation guide — The LBS Foundry platform provides auto-generated client SDKs in multiple languages, ensuring type safety and API consistency across all client applications.
• GitHub Token Setup for pnpm on Windows guide — This guide explains how to configure a GitHub Personal Access Token (PAT) for pnpm on Windows to access private packages from GitHub Packages.
• SDK Local Development Guide guide — This guide explains how to use the Foundry SDK locally during development, including linking the SDK to your applications and testing authentication.

Architecture decisions (ADRs)

• Architecture Decision Records (ADRs) index — This directory contains Architecture Decision Records (ADRs) that document important architectural decisions made for the LBS Foundry platform.
• ADR-007: Auto-Generated Multi-Language SDK for LBS Foundry API adr — Phase 1-3: TypeScript SDK generator and client (Completed)
• ADR-008: OpenAPI 3.0 Specification Generation adr — Future enhancement to complement custom SDK generation (ADR-007) with industry-standard API documentation.
• ADR-009: Sports Content Query Service — Validation & Foundational Architecture adr — Pending review and sign-off by Engineering and Product. Closes the Validation
• ADR: Real-Time Data Change Notification System adr — Architecture decision for the real-time data change notification system; Phases 1-2 implemented.

API

Ballr

• Optimise Lineup by Roster reference — Query Handler: GetOptimiseLineupByRosterQueryHandler
• Get Optimise Lineup Input by Team ID reference — Query Handler: GetOptimiseLineupInputByTeamIdQueryHandler
• TradeAssist by Roster reference — Query Handler: GetTradeAssistByRosterQueryHandler
• Get TradeAssist Input by Team ID reference — Query Handler: GetTradeAssistInputByTeamIdQueryHandler
• Query Caching Examples reference — This directory contains examples of how to implement cacheable queries using the ICacheableQuery interface.
• GetPlayerSuperCoachPointsPredictions API reference — The GetPlayerSuperCoachPointsPredictions API returns SuperCoach points predictions for the players in a single match. This is a secure readmodel query that requires the Member role.
• Get SuperCoach Team Rankings reference — File: src/Apps/Ballr.WebApi/Integration/SuperCoachTeam/Queries/GetSupercoachTeamRankingsQueryHandler.cs
• GetTeamRatingInputByTeamId API reference — The GetTeamRatingInputByTeamId API retrieves the team rating input payload for a SuperCoach team. This builds the structured input required by the SuperCoach...
• Link / Unlink SuperCoach Team Commands reference — Commands: LinkSupercoachTeamCommand, UnlinkSupercoachTeamCommand
• Search SuperCoach Teams reference — File: src/Apps/Ballr.WebApi/Integration/SuperCoachTeam/Queries/SearchSupercoachTeamsQueryHandler.cs
• LBS-1051: TradeAssist (historical note) note (archived) — Component: Ballr SuperCoach

Importers

• ClearRugbyLeaguePlayerProjectionsImporter guide — Clears player projections for NRL SuperCoach participant stats. Supports clearing all participants for a given season and round, or a specific subset of...
• Event Integrators Guide guide — Event integrators allow you to react to domain events in the event store, enabling integration with external systems, cross-aggregate workflows, and...
• Admin Feed Imports guide — How the admin Feed Imports UI browses harvested provider data and triggers imports through the generic per-entity importers and the import infrastructure.
• Import Infrastructure Usage Guide guide — This document explains how to use the LBS Foundry import infrastructure for creating and executing transactional imports.
• SquadImporter guide — Imports squad rosters (team-by-season player, coach, and staff lists) from the foundry.squads ClickHouse table into the SquadAggregate, reconciling each squad declaratively against the feed.
• Stats Perform NRL Match State Reference guide — Single source of truth for the Stats Perform Rugby League game state model and its mapping to the Foundry domain.
• StatsPerformNrlScoreboardImporter guide — Manually triggers a full reprocess of an NRL match scoreboard from StatsPerform. Fetches live match data from the StatsPerform API, resolves player and team ID...

Integrations

• Clerk Authentication Integration guide — This document describes the pure event-sourced User authentication system integrated with Clerk for the LBS Foundry platform.
• Clerk Webhook Implementation Plan plan — Implement a secure webhook handler to synchronize user data between Clerk and our system, creating user aggregates and preferences when users are created...
• Cloudflare PFX Certificate Generation Guide guide — Complete guide for generating PFX certificates from Cloudflare Origin Certificates for use with Azure Container Apps custom domains.
• Discord Integration Configuration guide — The LBS Foundry platform integrates with Discord to provide community engagement and user verification features. This document outlines the configuration...
• Discord Verification Frontend Flow guide — How the Discord verification frontend flow works: a backend-served verification page that hands off to the SvelteKit login page and back again to complete account linking.
• LBS Ballr MCP Server Setup Guide guide — The LBS Ballr MCP Server provides secure, controlled access to sports data via the Model Context Protocol (MCP). It integrates with Clerk OAuth for...
• NuGet Package Publishing Guide guide — This guide provides step-by-step instructions for publishing NuGet packages to GitHub Packages for this repository.

Models

• American Football Benchmarks guide — BenchmarkDotNet harness for the NFL simulation and outcome-context pipeline. Tracks the cost of simulating a season and folding it into outcome contexts, so...
• Engine — NFL Game Simulator model — NFL game simulator — a code-driven finite state machine that mirrors the flowchart in docs/models/americanfootball/nfl-flow/rendered/nfl_sim_flowchart.md. This...
• Play Decision — Real Model Integration Contract reference — The Play Decision predictor is the first real model behind the Predictors seam: the quants' Play Decision network, replacing the LBS-1654 pseudo predictor...

American Football

• Allocation Reduction Concepts — Play Object model — The current simulation allocates ~35,000 Play class instances per season (288 games × ~130 plays per game). Each Play has 38 properties (situation, personnel...
• NFL Season Structure — Playoffs & Super Bowl note (archived) — The simulation previously produced a flat 18-week regular season with no structure beyond team and week. This PR adds the structural scaffolding needed to run...
• Play Decision Model Integration — Performance Comparison (LBS-1657) model — This document records the measured cost of the Play Decision neural network at each step of its
• Pseudo Simulation Model — Enabling Full Season Monte Carlo model — A pseudo American Football simulation model that generates play-by-play data for a complete 18-week NFL season (32 teams, 288 games, ~35,000 plays per season)....

NFL flow

• NFL Simulation Flowchart index — Mermaid visualization of the NFL game simulator state machine, organized into 3 phases (Initialization / Play Execution / Play Aftermath). Vendored from the...
• NFL Game Simulation Flowchart — Glossary model — Terms used across the flowchart and its supporting docs. Domain vocabulary (NFL game / simulator state machine) and doc-framework vocabulary (how this project...
• UPDATING.md model — Operating manual for docs/models/americanfootball/nfl-flow/. Read this before editing the flowchart.

Rendered

• NFL Game Simulation — State Machine Flowchart reference — A readable visualization of the state machine in nfl_model_flow_diagram.htm. The simulator models an NFL game as ~40 states with branching outcomes; this...

Outcome Context

• Outcome Context platform index — A probabilistic sports-prediction service. Customer asks a question
• American Football outcome catalogue reference — This is the list of outcomes the American Football simulation currently produces. Each
• OutcomeContext — Cross-Cutting Design Decisions design — Companion to the executive roadmap
• OutcomeContext — High-Level Design design — Three layers of code stacked over one shared data model. Every layer is
• OutcomeContext GraphQL — Assistant Master Prompt reference — This document is designed to be pasted as the first message of a fresh
• OutcomeContext — Per-Phase Breakdown plan — Companion to the executive roadmap.
• Outcome Context Platform — Strategic Roadmap plan — Validate platform architecture with real model working end to end through the season.
• OutcomeContext — Sequencing Rationale (ADR-lite) design — Companion to the executive roadmap,
• Simulation Runner Benchmarks — Outcome Context producer guide — End-to-end outcome-context producer benchmark, with ClickHouse faked.

Evaluations

• Redis as an Outcome-Context store — deferred evaluation notes evaluation — Current primary store: ClickHouse Cloud Production tier (validated 100K full-pipeline end-to-end in 2h 58m — see status-summary.md).

Storage experiment

• K Worlds in Under 60 Seconds — Problem Statement evaluation (archived) — We have measured this on a laptop. The cost is dominated by pure simulation CPU — the storage/database layer is no longer the bottleneck.
• Storage Experiment — R&D Findings evaluation (archived) — Activity period covered: 2026-04-16 → 2026-04-21 (Australian income year FY2025-26)
• Storage Experiment — Status Summary evaluation (archived) — High-level test state + performance numbers. For process, architecture, and retrospective analysis, see status.md. For the R&D Tax evidence write-up...
• Storage Experiment — Status Update evaluation (archived) — K full-pipeline end-to-end validated on ClickHouse Cloud in 2h 58m for ~$27/run. All three outcome tables (game_outcome_context, play_by_play...
• Storage Experiment: Making NFL Simulation Data Fast evaluation (archived) — A plain-English walkthrough of what we're building and why.

Query layer

• Outcome Context — Query Layer Build Plan plan — Reads alongside: gap analysis, convergence reference.
• Outcome Context — query-layer convergence gap analysis design — Point-in-time gap analysis between the GraphQL query-layer prototype and the Outcome Context storage experiment (historical snapshot).
• Outcome Context Query Layer — R&D Findings evaluation — Activity period covered: 2026-04-25 → 2026-05-10 (Australian income year FY2025-26)
• Outcome Context — Query Layer Reference reference — This document is the orientation point for the Outcome Context query layer and the storage layer it sits on top of. It describes what the system is, what each...

Sub-designs

• D2 sub-design — Derivation build pipeline design — Reads alongside: gap analysis, build plan implementation status.
• D3 sub-design — Pre-simulation catalog design — Reads alongside: gap analysis, build plan implementation status.
• D4 sub-design — IOutcomeContextStore method shape design — Reads alongside: gap analysis, build plan implementation status.

Sport / domain

• GetLadderQuery — Reference reference — Source-of-truth reference for GetLadderQuery: the read-model query that returns competition ladder
• GetSportingEventsQuery — Filter Mode Reference reference — Reference for the three mutually exclusive filter modes of GetSportingEventsQuery and the fixed priority ladder the handler uses to resolve exactly one mode per request.
• GetMappedPlayers Query reference — Retrieves the full list of mapped players from ClickHouse, providing a cross-reference between FOX Sports, NRL, and SuperCoach player identifiers.
• ScoreBoard Unit Tests Documentation reference — How the ScoreBoard aggregate unit-test suite is structured (Cricket and Rugby League partials, integrator, projection builder) and how to run it.
• Process Flow of SetGroupCommand reference — This document describes the end-to-end flow for handling a SetGroupCommand against a sporting event aggregate, including validation, change detection, event...

SuperCoach participant stats

• Cricket SuperCoach Participant Stats Rules reference — This document outlines the scoring rules and statistics tracked for Cricket SuperCoach participants. Each player receives one document per match that is...

Data engineering

• Foundry Data Ingestion — Data Engineering Guide guide — Data science and data engineering are the first pass on any new data source. By the time a provider's data reaches Foundry, your team has already done the hard...

Testing

• Notification System Testing Guide guide — This guide covers testing strategies for the LBS Real-Time Notification System across unit tests, integration tests, and end-to-end scenarios.
• Testing CQRS Command System guide — This document provides examples for testing the command endpoint (POST /api/command) using existing commands in the system. Requests are intended to be run...
• Importer System Testing guide — This document provides examples for testing the import endpoint (POST /api/import). Requests are intended to be run with Bruno; each example shows the request...
• Read-Model Query Testing guide — This document provides examples for testing the read-model endpoint (POST /api/readmodel) and its authentication behaviour. Requests are intended to be run...

Runbooks

• Runbook: Archive Non-LuckBox Aggregates runbook — Scope: Marten event streams in events.mt_events whose Create event carried a non-LuckBox DataSource. These are duplicate aggregates left behind by the...

Configuration

• Configuration Samples index — This directory contains sample configuration files for various integrations and features in LBS Foundry.

Samples

• Sample Outputs index — Point-in-time snapshots generated by the accumulator test suite. These let
• First Game Diagnostic sample — Final Score: DEN 41, ATL 55
• Single World Accumulator Output Sample sample — Generated: 2026-05-06 13:31:03 UTC

Experiment runs

• Experiment Run Results index — Captured output from real runs of the storage experiment against a local ClickHouse container.

Use cases

• Use Cases for Viewing and Data Integration index — Title: View live fantasy points predictions for Supercoach players during the game.

User guides

• Cricket Projections: How It Works guide — Cricket projections provide predictive insights for matches, including:
• Event History Viewer: How It Works guide — The Event History Viewer lets you see a complete timeline of every change made to an item in the system. Think of it as a detailed audit log that shows:

End-user guides

• Projection Visibility Management guide — Projection Visibility Management allows content managers to control which rounds of player projections are visible to Ballr users. All projection data for...

Meta (docs about docs)

• Canonical Entity Mapping — Presentation Outline note (archived) — A 5–6 slide deck with a live demo in the middle, aimed at a mixed audience: execs, managers, end users, and developers. The structure leads with the problem in...
• Documentation Audit & OKF Alignment Roadmap note — Review of docs/ against Google's Open Knowledge Format, with a phased roadmap and file-by-file remediation.
• Documentation Conventions guide — How docs in this repo are typed, named, placed, and frontmatter-tagged (the OKF-aligned convention).
• Documentation Review — Relevance & Correctness note — Systematic review of all 170 docs against the codebase; fixes applied and issues flagged for decision.
• OKF docs: access & contributing guide — How to reach the LBS Foundry documentation (the site, the downloadable bundle, and the machine-readable manifest) and how to add to it.