MAB Play

Architecture Notes

# CLAUDE.md

## Rules

- **NEVER commit or push without explicit user request**
- **NEVER deploy directly to VPS** — all changes go through GitHub, CI/CD deploys automatically
- **NOT a Telegram Mini App** — this is a regular web app (PWA). No Telegram integration at all. Never reference Telegram Mini App in the context of this project.
- **No Telegram auth** — authentication is email/password and Yandex OAuth only. No Telegram login.

## Project

Billiards Central Hub — web app (PWA) for billiards tournaments, ratings, sparring, subscriptions.

## Commands

```bash
pnpm dev             # Dev server :8080 → stage backend (sb.dev.tourny.ru)
pnpm dev:docker      # Dev server :8080 → local Supabase (auto-starts Docker + auto-login as admin)
pnpm build           # Production build
pnpm test            # Vitest (68 tests)
```

## Stack

Frontend: React 18 + TypeScript + Vite + shadcn/ui + Tailwind + React Query + React Router v6
Backend: Supabase (PostgreSQL + Auth + Edge Functions) + YooKassa payments
Deploy: Docker → Nginx → VPS via GitHub Actions

## Structure

```
src/pages/           # Route components
src/components/ui/   # shadcn/ui (don't modify)
src/hooks/           # Custom hooks (useSubscription, useOnboardingCheck)
src/integrations/supabase/types.ts  # Auto-generated DB types (don't edit)
supabase/functions/  # Edge Functions (Deno) — see docs/subscriptions.md
supabase/migrations/ # Schema migrations
```

Imports: `@/` → `src/`. Routes: `src/App.tsx`. Context order: QueryClient → Telegram → Impersonation.

## Key Flows (details in docs/)

**Onboarding** → `docs/onboarding.md`
`/` → `/onboarding` (3 screens) → `/auth` → `/skill-questionnaire` → `/welcome` (trial) → `/`

**Subscriptions & Payments** → `docs/subscriptions.md`
Trial 1₽ → 14 days → auto-upgrade to Премиум. Decline retry (soft/hard/technical). Auto-renewals.

**Email** → `docs/email-sending.md`
Unisender Go via shared helper `_shared/unisender-go.ts`. Format: `html` only. `UNISENDER_GO_API_KEY` needed.

**Release to Prod** → `docs/release-flow.md`
`main` → auto stage (dev.tourny.ru) → test → `git tag v2.1.0 && git push origin v2.1.0` → auto prod (tourny.ru)

**Local Development** → `docs/local-development.md`
Supabase start, env files, DBeaver, known issues (ES256 JWT, YooKassa webhook).

**VPS & Infrastructure** → `docs/vps-infrastructure.md`
Server, containers, nginx, SSL certs, useful commands, GitHub Secrets.

**Analytics** → `docs/analytics.md`
PostHog (EU cloud). Autocapture on prod only. Disabled on stage/local.

**Error Tracking** → `docs/error-tracking.md`
Sentry (DE region). Auto-capture errors + replay on prod only.

## Database

Core: `profiles`, `tournaments`, `tournament_matches`, `tournament_participants`, `subscriptions`, `subscription_plans`, `payment_history`
Supporting: `messages`, `notifications`, `sparring_requests`

## Edge Functions (key)

`create-payment` / `yookassa-webhook` — payments
`transition-trial-to-paid` / `process-auto-renewals` / `process-payment-retries` — cron
`notify-expiring-subscriptions` — pre-expiration alerts (cron)
`telegram-auth` / `yandex-auth` / `phone-auth` — authentication
`send-email` — Unisender Go transactional email

## Environment

`.env` — Vite vars, points to **stage** Supabase (sb.dev.tourny.ru) by default
`supabase/functions/.env` — Edge function secrets (YOOKASSA_*, YANDEX_*, UNISENDER_GO_API_KEY)
Secrets source: VPS `/opt/tourny/supabase-tourny-dev/.env` (see `docs/email-sending.md`)

**Dev auto-login**: `VITE_DEV_AUTOLOGIN=admin|player1-6|demo` — auto-login with seed user in dev mode. Enabled by default in `dev:docker`. For stage: uncomment in `.env`.

## Git Flow

Feature branches → PR → `main` (auto stage) → `git tag vX.Y.Z` (auto prod). See `docs/release-flow.md`.