# CLAUDE.md

## Project
Georgia-focused IQ/EQ/knowledge quiz platform with local leaderboards and clubs (name TBD). Full context: PROJECT.md. Architecture and required patterns: ARCHITECTURE.md. Current progress: PHASES.md — check it before starting work, update it when you finish something.

## Stack
Laravel 13 (PHP 8.3+), MySQL/Postgres, Redis, Reverb, custom admin (Livewire + Alpine, not Filament), Sanctum + Socialite. Hosted on a self-managed cPanel/WHM server. Flutter mobile app lives in a separate repo, consumes this app's API.

## Always
- Mark items in PHASES.md `[x]` when actually complete and verified — not when the code is written. Keep it truthful.
- Never trust client-reported quiz scores or timing — validate server-side, every time.
- Stars/points: append to the ledger table, never write directly to a balance field.
- Config that a non-developer might reasonably change goes in the admin-editable settings table, not `.env`. `.env` is for DB credentials, `APP_KEY`, mail, Redis, and payment gateway secrets only.
- Every user-facing string and every piece of quiz content goes through the translation layer, even though content is English-only until Phase 6 — never hardcode display strings. Mark untranslated content with the agreed TODO convention.
- Admin panel UI itself is English-only, permanently — don't route it through the translation layer.
- Leaderboard reads go through Redis, not direct `ORDER BY` queries against the primary DB.
- Visual (matrix-style) questions are stored as a rule description and rendered client-side — never generate/store a fixed image per question.
- Before adding a new feature, table, or pattern, check PROJECT.md and ARCHITECTURE.md for an existing decision first.
- Before every push to `main`: run `npm ci && npm run build` locally and commit the resulting `public/build`. The cPanel server has no Node.js — built assets must already be in git or the deploy scripts (`deploy.yml`/`.cpanel.yml`, see DEPLOY.md) will serve stale or missing assets.

## Commands
_(fill in once the app is scaffolded: install, migrate, test, lint, deploy)_