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/ ← дизайн-токены + генераторы

3.4 KiB Raw Permalink Blame History