# Randify.pro — Knowledge Base

**Stack:** Astro 4 + Tailwind CSS 4 + TypeScript + PostgreSQL (Drizzle ORM)
**Deploy:** Docker Compose (app + postgres) on VPS, nginx reverse proxy, Let's Encrypt SSL

## Overview

Bilingual (EN/RU) static/hybrid site hosting random-value generators (10 live). Recently expanded with **DM Dashboard** — a server-rendered OAuth-authenticated subdomain (`/dm/`) with dice roller, initiative tracker, Open5e reference, and notes.

## Structure

```
/
├── src/
│   ├── pages/           # Astro pages (EN + RU mirrors)
│   │   ├── api/auth/    # OAuth 2.1 + PKCE (VK ID + Yandex)
│   │   ├── generators/  # Static generator pages
│   │   ├── dm/          # DM Dashboard (server-rendered, prerender=false)
│   │   └── ru/          # Russian mirror pages
│   ├── components/
│   │   ├── generators/  # Interactive generator components (see sub-AGENTS)
│   │   └── dm/          # DM Dashboard UI (see sub-AGENTS)
│   ├── layouts/         # BaseLayout, GeneratorLayout, DmLayout
│   ├── lib/
│   │   ├── auth/        # JWT, OAuth configs, session utils
│   │   ├── client/      # Browser utilities (dice, animations, random)
│   │   └── open5e/      # Open5e API client + cache
│   ├── db/              # Drizzle schema, migrations, client
│   ├── i18n/            # Translations (en/ru) + DM translations
│   ├── content/         # Astro Content Collections (generators, blog)
│   └── data/            # Static data (generator list, config)
├── tests/               # Vitest + Playwright tests
├── drizzle/             # SQL migrations
├── docker-compose.yml   # App + PostgreSQL production setup
└── .github/workflows/   # CI/CD deploy via rsync
```

## Where to Look

| Task | Location | Notes |
|------|----------|-------|
| Add new generator | `src/content/generators/`, `src/components/generators/`, `src/pages/generators/` | Must create EN + RU simultaneously |
| Fix OAuth | `src/pages/api/auth/`, `src/lib/auth/`, `src/middleware/index.ts` | VK ID uses `id.vk.ru`, Yandex uses `oauth.yandex.com` |
| DB schema change | `src/db/schema.ts` → `drizzle/` | Run `npm run db:generate` then migrate |
| DM Dashboard UI | `src/components/dm/`, `src/pages/dm/` | Orange theme `#E87722`, RU-only |
| i18n strings | `src/i18n/translations.ts`, `src/i18n/dm-translations.ts` | `useT(lang)` returns typed object |
| Production deploy | `.github/workflows/deploy.yml`, `docker-compose.yml` | GitHub Actions → rsync → Docker Compose restart |

## Conventions

- **Path aliases:** `@/*` → `src/*` used everywhere
- **i18n routing:** Astro built-in. `Astro.currentLocale` drives locale. EN pages at root, RU under `/ru/`
- **Generator pages:** Each generator has its own `.astro` page file (never dynamic `[slug].astro` for generators — Astro bundles all imported scripts)
- **Color system:** `var(--accent)` in BaseLayout = `#534AB7` (purple). DM Dashboard overrides to `#E87722` (orange) via `.dm-theme` CSS class
- **Auth cookie name:** `auth_token` (unified across OAuth callback, middleware, logout)
- **DB connection:** `process.env.DATABASE_URL` — must match docker-compose `postgres` service hostname inside containers

## Anti-Patterns

- **Dynamic `[slug].astro` for generators:** Forbidden. Each generator must have its own page file to avoid script bundling issues
- **Using `url.origin` in OAuth callbacks:** Broken behind nginx proxy. Always use `process.env.PUBLIC_APP_URL || url.origin`
- **Joining multiple `Set-Cookie` with comma:** Browsers reject this. Use `Headers.append()` for each cookie
- **`SameSite=Strict` on session cookie:** Breaks cross-site OAuth redirects. Use `SameSite=Lax` + `Secure`
- **Static `prerender` for DM pages:** Middleware won't run, `Astro.locals.user` stays `null`. DM pages MUST have `export const prerender = false`
- **`Math.random()` for cryptographic purposes:** Generators should use `crypto.getRandomValues()` via `src/lib/client/random.ts`
- **Importing `import.meta.env` in server code:** Use `process.env` for server-side secrets (OAuth, JWT, DB)
- **Unknown fields in generator JSON:** `src/lib/generator-schema.ts` uses Zod `.strict()`. Any unknown field breaks the build
- **Unescaped `innerHTML` with user input:** Generators use `innerHTML` extensively. Always escape user input via `escapeHtml()` (currently duplicated in 3 files — consolidate to `src/lib/client/`)
- **OAuth empty-string fallbacks:** `process.env.VK_CLIENT_ID || ''` silently produces invalid requests. Validate env vars explicitly or fail fast
- **JWT secret non-null assertion:** `process.env.JWT_SECRET!` in `src/lib/auth/jwt.ts` crashes at runtime if env var is missing

## Commands

```bash
npm run dev          # Dev server (localhost:4321)
npm run build        # Static + server build → dist/
npm run preview      # Preview built dist/
npm run test         # Vitest unit tests
npm run test:e2e     # Playwright E2E tests
npm run db:generate  # Generate Drizzle migration
npm run db:migrate   # Run migrations
```

## Notes

- **No test runner or linter** configured in CI (per CLAUDE.md)
- **Health endpoint** (`/api/health`) checks DB connectivity via `SELECT 1`
- **Analytics:** Yandex Metrika + Top.Mail.Ru counters, IDs in `src/data/config.ts`
- **Service Worker** registered in BaseLayout for PWA support
- **Blog** uses Astro Content Collections with MDX/Markdown
- **Dockerfile** is single-stage Node 20 Alpine (not multi-stage as CLAUDE.md claims)
- **ESLint override:** `public/sw.js` has `@typescript-eslint/no-unused-vars` disabled for service worker globals
- **Zero TODO/FIXME/HACK markers** in source code — codebase is clean
- **Explicit prerender required:** Hybrid output mode means every `.astro` page MUST declare `export const prerender = true/false`