# UberLotto v2

> Technical Documentation

Shopify Hydrogen-based Online Lottery Platform

## Table of Contents

### Getting Started

- [Project Overview](/getting-started/overview.md): What is UberLotto v2, its tech stack, import conventions, path aliases, and common commands.
- [Local Development Setup](/getting-started/local-development.md): How to set up and run UberLotto v2 locally for development.
- [Environment Variables Reference](/getting-started/environment-variables.md): Complete reference for all environment variables used in UberLotto v2.

### Architecture

- [System Architecture](/architecture/overview.md): High-level architecture overview of UberLotto v2 — client, edge, and data layers.
- [Project Structure](/architecture/project-structure.md): Detailed breakdown of the UberLotto v2 directory structure and file organization.
- [Data Flow Patterns](/architecture/data-flow.md): Core data flow patterns in UberLotto v2 — SSR page loads, payment flows, and product enrichment.

### Products

- [Creating Lottery Products](/products/product-creation.md): Step-by-step guide for creating lottery game products in Shopify and connecting them to Supabase data via the game_slug metafield.
- [Metafields Reference](/products/metafields-reference.md): Complete catalog of all Shopify metafields used in UberLotto v2, organized by scope — product, variant, page, and shop level.
- [Shop & Variant Quantity Limits](/products/quantity-limits.md): How UberLotto v2 enforces quantity limits at the shop and variant level using a dual-namespace metafield system with Shopify native quantityRule integration.

### Payments

- [Credit Loading via Shopify Checkout](/payments/shopify-checkout-credits.md): How Shopify's native checkout is used to load UBL Points (credits) into user wallets.
- [Plisio Cryptocurrency Payments](/payments/plisio-crypto.md): Integration guide for the Plisio cryptocurrency payment gateway, including invoice creation, webhook handling, and multi-layer security pipeline.
- [MoonPay Fiat-to-Crypto Integration](/payments/moonpay.md): Complete integration guide for the MoonPay fiat-to-crypto onramp, including URL signing, webhook handling, transaction logging, and multi-layer security pipeline.

### Database

- [Supabase Database Guide](/database/supabase-guide.md): Complete guide to the Supabase database schema, tables, RLS policies, and TypeScript interfaces for UberLotto v2.
- [Migration Guide](/database/migrations.md): Database migration structure, existing migrations, and how to create and run new migrations for UberLotto v2.
- [Database Monitoring & Maintenance](/database/monitoring.md): Monitoring queries, scheduled maintenance tasks, and operational best practices for the UberLotto v2 Supabase database.

### Security

- [Security Architecture](/security/overview.md): Comprehensive security architecture overview covering network, application, and data layer protections.
- [Webhook Security Deep Dive](/security/webhook-security.md): Detailed walkthrough of the multi-layer webhook validation pipeline, replay protection, and GDPR-compliant security logging.
- [Rate Limiting Configuration](/security/rate-limiting.md): Three-tier rate limiting system with sliding window algorithm and LRU eviction for webhook and API protection.

### API Reference

- [API Routes Reference](/api/routes-reference.md): Comprehensive reference for all API endpoints and page routes in the UberLotto v2 application, including request/response formats, authentication, and security measures.

### Deployment

- [Deployment to Shopify Oxygen](/deployment/oxygen.md): Guide to deploying UberLotto v2 to Shopify's Oxygen edge hosting platform, including CI/CD workflows, environment management, and rollback procedures.
- [CI/CD Workflows](/deployment/ci-cd.md): Complete reference for UberLotto's GitHub Actions CI/CD pipelines, deployment workflows, secrets management, and branch strategy.