Randomness Lab

Interactive Randomness Lab web app — commit–reveal draws and frequency / chi-square testing — with a short landing page styled after The Randomness Dossier research report.

Stack

• Frontend: Next.js (App Router) + TypeScript + TailwindCSS (apps/web)
• Backend: FastAPI + shared services (backend)
• MCP: same services exposed as MCP tools (backend/app/mcp_server.py)
• Package manager: pnpm workspaces
• Tests: pytest (business logic), Playwright (core user journeys)

Prerequisites

• Node.js 20+
• pnpm 9+
• Python 3.11+

Setup

If pnpm install fails with TLS / certificate errors (common on corporate networks), this repo includes .npmrc with strict-ssl=false. You can also set NODE_TLS_REJECT_UNAUTHORIZED=0 for the install session.

# Install frontend + e2e deps
pnpm install

# Playwright browser (once)
pnpm --filter e2e exec playwright install chromium

# Backend virtualenv
cd backend
python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS/Linux:
# source .venv/bin/activate
pip install -e ".[dev]"
cd ..

Run

Terminal 1 — API (default http://127.0.0.1:8000):

cd backend
.venv\Scripts\activate   # or source .venv/bin/activate
uvicorn app.main:app --reload --port 8000

Terminal 2 — web (default http://localhost:3000):

pnpm dev

Set NEXT_PUBLIC_API_URL=http://127.0.0.1:8000 in apps/web/.env.local if needed (defaults to that URL).

Google Sheets (Ultra Lotto history)

The Lab can load Ultra Lotto 6/58 via the Google Sheets API and run the chi-square tester on real draw combinations.

1. In Google Cloud Console: create/select a project → enable Google Sheets API → Credentials → API key.
2. Share the spreadsheet as Anyone with the link (Viewer).
3. Copy backend/.env.example to backend/.env and set:

GOOGLE_SHEETS_API_KEY=your_key_here

4. Restart uvicorn, open /lab, and click Load from Google Sheets.

Endpoint: POST /api/stats/from-sheet
MCP tool: analyze_lotto_sheet

MCP server

Must run from the backend folder with the project venv (not system Python from the repo root):

cd backend
.\.venv\Scripts\Activate.ps1
python -m app.mcp_server

Or without activating:

cd backend
.\.venv\Scripts\python.exe -m app.mcp_server

Tools: commit_draw, reveal_draw, run_frequency_test, health.

Tests

PowerShell (this repo’s default shell) — use ; instead of &&:

# Unit tests (business logic)
cd backend
.\.venv\Scripts\Activate.ps1
pytest
cd ..

# E2E (starts API + Next.js via Playwright webServer)
pnpm e2e

One-liner from repo root:

cd backend; .\.venv\Scripts\python.exe -m pytest; cd ..

Deploy (Google Cloud Run)

Target project: random-numbers-504204 (region asia-southeast1).

Prerequisites:

• gcloud installed and logged in
• Billing linked to the project (Cloud Run / Cloud Build / Artifact Registry require it)
• On Windows with Avast HTTPS scanning, use the helper below (Python 3.11 + Avast CA)

# From repo root — builds & deploys API + web
.\scripts\deploy-cloud-run.ps1

This deploys:

• randomness-api from backend/ (sets GOOGLE_SHEETS_* from backend/.env)
• randomness-web from apps/web/ with NEXT_PUBLIC_API_URL pointed at the API URL

Manual gcloud env fix (if SSL fails):

. .\scripts\gcloud-env.ps1
gcloud config set project random-numbers-504204

Layout

apps/web/     Next.js UI
backend/      FastAPI + MCP + pytest
e2e/          Playwright
scripts/      Cloud Run deploy helpers