Project Overview

UberLotto v2 is a headless online lottery platform built with Shopify Hydrogen and React Router v7. It uses Shopify's Storefront and Customer Account APIs for commerce, Supabase for database and transaction management, and Plisio + MoonPay for cryptocurrency payments. The app is deployed as a PWA on Shopify Oxygen (Cloudflare Workers).

Tech Stack

Layer	Technology
Framework	Shopify Hydrogen
Routing	React Router v7 (file-based via @react-router/fs-routes)
Build Tool	Vite 6 with @tailwindcss/vite
Language	TypeScript (strict mode)
Styling	Tailwind CSS v4, Shadcn/ui (New York style), Radix UI, Motion
State	Zustand (client), TanStack Query (server cache)
Database	Supabase (PostgreSQL) — custom fetch client, no SDK
Commerce	Shopify Storefront API (GraphQL), Customer Account API
Payments	Plisio (crypto), MoonPay (fiat-to-crypto on-ramp), Shopify Checkout (credit loading)
Analytics	PostHog
Deployment	Shopify Oxygen (Cloudflare Workers edge runtime)
PWA	vite-plugin-pwa with Workbox service worker

Critical Import Rule

ALWAYS use react-router imports

This project uses React Router v7, NOT Remix. All route-related imports must come from react-router.

// CORRECT
import { useLoaderData, Link, Form, redirect } from 'react-router';
import type { LoaderFunctionArgs, ActionFunctionArgs } from 'react-router';

// INCORRECT — never use these
import { ... } from '@remix-run/react';      // ❌
import { ... } from 'react-router-dom';      // ❌

Path Aliases

The project uses TypeScript path aliases defined in tsconfig.json:

Alias	Maps To	Usage
~/*	app/*	General app imports
@/*	./*	Project root imports
@components/*	app/components/*	UI components
@lib/*	app/lib/*	Core utilities
@utils/*	app/utils/*	Helper functions
@hooks/*	app/hooks/*	Custom React hooks
@store/*	app/store/*	Zustand stores
@graphql/*	app/graphql/*	GraphQL queries
@services/*	app/services/*	Business logic services
@sections/*	app/components/sections/*	Page sections
@skeletons/*	app/components/skeletons/*	Loading skeletons
@shared-types/*	app/shared-types/*	Shared type definitions

Common Commands

# Start dev server with GraphQL codegen watch
npm run dev

# Production build
npm run build

# Preview production build locally
npm run preview

# TypeScript type checking
npm run typecheck

# Run ESLint
npm run lint

# Generate GraphQL types from queries
npm run codegen

TIP

All scripts use shopify hydrogen CLI under the hood. Running npm run dev executes shopify hydrogen dev --codegen, which starts the Vite dev server with automatic GraphQL type generation.