# kuzyak.in (LLM Map)

> Персональное портфолио, статистика и блог Павла Кузякина. Построено на Next.js 16, Supabase и Notion.

## 🧭 Краткий обзор
- **Стек**: Next.js 16.2.6 (App Router, Turbopack, `cacheComponents` RFC), React 19.2.7, TS 6.0.3, SCSS Modules (публичный сайт), Mantine UI 9 + `@mantine/hooks` + `@mantine/charts` (админка). Типографика: [`typograf`](https://github.com/typograf/typograf) v7.7+ (автоматическая обработка кавычек, тире, NBSP, висячей пунктуации для всего контента — [`docs/typography.md`](docs/typography.md)).
- **Архитектура**: Feature-Sliced Design (FSD). Потоки: `app` -> `widgets` -> `features` -> `entities` -> `shared`. ~56 feature-слайсов, 12 widgets (в т.ч. `gta6-countdown`, `vacation-countdown`, `travels`).
- **База данных**: Supabase (Postgres, Auth, Storage). Единственный источник истины схемы — [sql/init.sql](sql/init.sql).
- **Node.js**: `22` ([.nvmrc](.nvmrc); CI и Docker — тот же мажор).
- **Порт сервера**: `7274` (`npm run dev`, привязан к `0.0.0.0`).
- **Тесты**: Vitest v4 + `@vitest/coverage-v8` + Testing Library. CI (`.github/workflows/ci.yml`) — eslint + test на PR в `main`/`develop` и push в `main`; push в `develop` CI не триггерит. Stylelint и typecheck — только в pre-commit хуке Husky. `npm run build` только в Docker workflow Deploy/Deploy Staging.
- **CI/CD**: 7 workflow-файлов в `.github/workflows/` — ci, deploy, deploy-staging, rollback, security-audit, threads-token-refresh, webmentions-sync.

## 📂 Документация & Правила
- [AGENTS.md](AGENTS.md) — **Критично!** Инструкции для AI-ассистентов, архитектурные ограничения и workflow.
- [docs/architecture.md](docs/architecture.md) — Подробное описание слоев FSD и API-клиентов.
- [docs/api.md](docs/api.md) — Референс всех REST эндпоинтов.
- [docs/integrations.md](docs/integrations.md) — Справочник интеграций (Last.fm, Notion, Google Sheets, Threads, Groq): секреты, API, POSSE.
- [docs/DESIGN.md](docs/DESIGN.md) — Дизайн-система и визуальные стандарты.
- [docs/ideas.md](docs/ideas.md) — Бэклог из 125 идей для развития проекта.

## 🏗️ Ключевые модули (src/features)
- `stats`: Агрегатор активности (GitHub, WakaTime, Last.fm, Strava, NASA APOD). `/stats` — DayCard (editorial KPI-сетка), YearProgress, CodecovIcicle, live-счётчики (`Counter`), `kpi-snapshot.json` с полем `dynamics`.
- `blog`: Движок блога на базе Notion API.
- `guestbook`: Гостевая книга с пре-модерацией и защитой от спама (reCAPTCHA).
- `cv`: Интерактивное резюме и управление статусом работы.
- `museum`: Коллекция цифровых артефактов.
- `weather`: Климатические метрики и графики (Raspberry Pi → Supabase). Страница `/weather`, `/weather/air`.
- `meteostation`: Info-страница `/meteostation` о балконной станции (ESP32 + BME280 + PMS5003 → Supabase → Pi 4 → sensor.community); live-карточки через `getWeatherSummary()`, контент в `src/features/meteostation/`.
- `projects`: Showcase open-source проектов (`/projects`, bento-сетка, данные в `src/shared/data/projects.json`).
- `voice`: Голосовые сообщения в Telegram через Google TTS.
- `admin-*`: Слайсы админки (`admin-analytics`, `admin-guestbook`, `admin-pulse`, `admin-security`, `admin-stream`, `admin-host-metrics`).
- `morse-converter`: Конвертер текста в азбуку Морзе со звуком и вибрацией (`/tools/morse`).
- `nfc-reader`: Чтение, запись и бэкап NFC-меток через Web NFC API (`/tools/nfc`, только Android + Chrome).
- `colophon`: Страница «Об сайте» (`/colophon`).
- `hire`: Страница «Нанять» (`/hire`).
- `tools/fuck`: Пасхалка fullscreen (`/tools/fuck`).
- `admin-settings-seo`: Управление robots.txt и sitemap (`/admin/settings/seo`).
- **Поток (`/stream`)**: IndieWeb (h-entry, JSON-LD, webmentions через webmention.io + cron `.github/workflows/webmentions-sync.yml`), POSSE в Threads (дефолт загружается из `syndication_enabled` в интеграциях, авто-обновление токена раз в 30 дней `.github/workflows/threads-token-refresh.yml`), visible toggle в bottom bar, фильтр `?tag=`.

## 🛰️ Админ-панель, Raspberry Pi и особенности
- `/admin` — Mantine UI 9, light/dark тема через `useMantineColorScheme` (`defaultColorScheme="light"`). Theme-aware токены: `var(--mantine-color-default-border)`, `var(--mantine-color-body)`. Хардкод `dark-N` для поверхностей запрещён. Mantine Modal/Drawer: портал в `.adminRoot`, `--admin-*` дублируются на `body:has([data-admin-layout])`. Sidebar: группа «Аналитика» (Посещаемость, Pulse), ссылка «Настройки» → хаб `/admin/settings`; пункты с `settingsHub` скрыты, кроме `sidebar: true` — `src/shared/constants/adminNavigation.ts`. SEO: `/admin/settings/seo` — robots.txt и sitemap (`GET/PUT /api/seo-files`, `POST /api/seo-files/ai-generate` через Groq). Публичный `/robots.txt` — `src/app/robots.txt/route.ts` + `getRobotsTxt()` (`connection()`, без `revalidate`).
- `/admin/pi` — дашборд Raspberry Pi: климат, эндпоинты и видеонаблюдение с камеры. Прокси-роуты: `src/app/api/admin/camera/{status,snapshot,snapshots}/route.ts` + `piProxy.ts` (`fetchPiCamera`, таймаут 15s). Имя файла снимка через `?filename=`. Учётные данные Pi — `TEMPERATURE_API_USERNAME` / `TEMPERATURE_API_PASSWORD` (Basic Auth).
- `/maintenance` — full-screen терминальный UI без header/footer; rewrite в `src/proxy.ts` + cookie `kuzyak_maintenance_view`, хук `useIsMaintenanceView`. В proxy — cache-first maintenance (TTL 45s, `getMaintenanceModeCache`) и таймаут Supabase RPC 3s; `/api` и `/admin` пропускаются без проверки.
- `/discussion` — пасхалка «Стратегический фильтр» (интерактивный чеклист + `POST /api/discussion/analyze` для авторизованных, Groq), `src/features/easter-eggs/discussion/`.
- `/tools/fuck` — пасхалка fullscreen (`noindex`), без header/footer; `src/app/tools/fuck/`, ассет `public/fuck.webp`.
- `/offline` — SW-заглушка без header/footer: hero + карусель плашек для залогиненных.
- **Аутентификация**: `useAuth()` из `@/shared/contexts/AuthContext` — единая точка получения `user`/`session`. AuthProvider оборачивает дерево в `src/app/layout.tsx`. Гейтить UI-элементы по `user`.

## 🚨 Важные соглашения
1. **Стили**: Строго SCSS Modules с использованием `@use`. Проверка: `npm run stylelint` (автофикс `stylelint:fix`). Порядок CSS-свойств — `stylelint-config-idiomatic-order`.
2. **Типизация**: Strict TypeScript (`tsconfig.json`). Валидация внешних данных через Zod v4 (`zod` с `optimizePackageImports` в `next.config.mjs`).
3. **БД**: Изменения вносятся только в `sql/init.sql`. Без инкрементальных миграций.
4. **Коммиты**: Conventional Commits. Husky pre-commit: `npm run lint` (ESLint + Stylelint) + `npm run typecheck`. Обновление [CHANGELOG.md](CHANGELOG.md) обязательно.
5. **Язык**: Комментарии в коде и документация — на русском языке.
6. **API**: `successResponse`/`errorResponse` из `@/shared/utils/apiResponse`, фабрики Supabase из `shared/lib/supabase`. Server self-fetch — `fetchInternalApi` / `resolveOwnOrigin` из [`src/shared/lib/internalFetch.ts`](src/shared/lib/internalFetch.ts) (origin из `host`, не `NEXT_PUBLIC_SITE_URL` в dev; дефолтный таймаут 8s, `timeoutMs`). Внешние fetch: `sharedFetch` / `fetchIpWhoisData` (8s), Pi camera — `fetchPiCamera` (15s, [`piProxy.ts`](src/app/api/admin/camera/piProxy.ts)).
7. **Prod ops**: Docker healthcheck — `GET /api/health` ([`src/app/api/health/route.ts`](src/app/api/health/route.ts)); диагностика 502 — [`scripts/diagnose-502.sh`](scripts/diagnose-502.sh); `proxy.ts` — cache-first maintenance (45s) + таймаут Supabase 3s; лимит RAM контейнера 1536M, CPU 1.0 (`docker/docker-compose.prod.yml`). read_only RootFS, cap_drop ALL.
8. **Mantine hooks / Shared hooks**: Для UI-состояний админки предпочитай `@mantine/hooks` (`useDisclosure`, `useLocalStorage`, `useMediaQuery`, `useDebouncedValue`) вместо ручных `useState` + `useEffect`. Для публичных страниц с бесконечным скроллом и поиском используй общий хук `useDebouncedValue` из `@/shared/hooks/useDebouncedValue`.
9. **Next.js 16 gotchas**: `trailingSlash: true` + `skipTrailingSlashRedirect: true` — точка в **последнем** сегменте (`foo.jpg`) ломает динамические API. JSON постов — `GET /api/stream/posts?slug=`. **OG PNG** (паттерн `…/og/`): `/stream/[slug]/og/`, `/weather/og/`, `/weather/air/og/`; legacy `/api/og/*` → 308. Legacy Edge `opengraph-image`: `loadOgFonts` — динамический `import('node:fs/promises')` на Node-ветке. `cacheComponents: true` (RFC) — динамика требует `await connection()` в route handlers. Изображения: next/image, remotePatterns (Notion, Supabase, Wikimedia, picsum, и др.), unoptimized: false, SVG разрешены.
10. **Loading skeletons**: Публичные страницы используют layout-скелетоны с shimmer-анимацией. Базовый миксин в [`src/shared/styles/skeleton.scss`](src/shared/styles/skeleton.scss). Каждый `loading.tsx` повторяет структуру реальной страницы.
11. **ESLint flat config**: `eslint.config.mjs` — единый файл. Правила FSD-границ через `eslint-plugin-boundaries` v7. `import-x/order` с `@/` алиасами и `newlines-between: always`. Типы `import type {...}` — inline в фигурных скобках.
12. **Tooling**: `knip` для dead code (`npm run dead-code`), `tsx` для скриптов, `bundle-analyzer` через `npm run build:analyze`.