# VoIdea — Specification

## Overview

VoIdea ("Голос Идей") — гибридное приложение для фиксации и проработки идей с помощью группового ИИ-анализа. Работает как PWA (устанавливается на телефон), с перспективой нативных iOS/Android-клиентов.

## Stack & Rationale

| Layer | Choice | Why |
|-------|--------|-----|
| Frontend framework | React 18.3 LTS | Стабильность, экосистема, перспектива React 19 |
| Language | TypeScript 5.5 strict | Типобезопасность, самодокументируемость |
| Styling | Tailwind CSS 3.4 | Utility-first, тёмная тема из коробки, PWA-ready |
| State management | Zustand | 1.1 KB, без Provider, работает вне React (можно читать токен в api/client) |
| Forms | react-hook-form + zod | Валидация через схему = один источник истины (типы TS = runtime) |
| Routing | react-router-dom 6 | Стандарт React |
| PWA | vite-plugin-pwa | Service worker + manifest из коробки |
| Build | Vite 5 | Быстрая сборка, HMR |
| Backend | FastAPI (Python) | Асинхронный, Pydantic-валидация |
| Database | PostgreSQL | ACID, JSONB |
| Queue | Celery + Redis | AI-вызовы, бэкапы, email |

## Key Decisions

### Zustand over Context
- Context ререндерит ВСЕХ подписчиков при изменении. Zustand — только тех, кто читает изменившееся поле.
- Zustand-стор можно читать вне React (в `api/client.ts` для token refresh).
- Для существующего `AuthContext` — постепенный перенос в `stores/auth.ts`.

### react-hook-form + zod over native forms
- Валидация через zod-схему: TypeScript тип = runtime тип, расхождение невозможно.
- `errors` из коробки, `isSubmitting`, `dirty`/`touched`.
- Для простых форм (2 поля: логин) — можно оставить нативный `<form>`.

### WCAG AA
- Целевой уровень доступности: AA (стандарт для РФ/ЕС).
- Enforcement: eslint-plugin-jsx-a11y в CI.

### Error Boundaries
- Глобальный ErrorBoundary — защита от белого экрана.
- Per-page для VoiceChat (голосовые API могут падать).

### i18n
- Сейчас: только русский.
- Но строки вынесены в `constants/strings.ts`, рендерятся через `<T>`, что позволит перейти на react-i18next без переписывания UI.

## Project Documentation Map

```
PROJECT_GUIDE.md        ← навигатор по всей документации
├── SPECIFICATION.md    ← этот файл
├── TECHNICAL.md        ← архитектура и схемы
├── STYLE_GUIDE.md      ← код-стайл webui
├── versioning.md       ← версионирование
├── user-guide.md       ← пользовательская инструкция
├── admin-guide.md      ← администрирование
├── docs/blocks/        ← блоки правил
└── docs/design-system/ ← дизайн-токены + генераторы
```