LinguaCompanion — Техническое задание v1.0

Техническое задание

Lingua
Companion

Мультиязычный ИИ-ассистент для изучения языков и помощи в реальном общении

PWA React + TypeScript FastAPI 6 AI-провайдеров 5 языков

Содержание

01Общее описание проекта
02Режимы работы приложения
03Технический стек
04Абстракции над провайдерами
05Архитектура
06Поддерживаемые языки
07Хранение данных
08Бэкенд API
09Нефункциональные требования
10Фазы разработки
11Принципы разработки

01Общее описание проекта

1.1Название

LinguaCompanion — мультиязычный ИИ-ассистент для изучения языков и помощи в реальном общении.

1.2Цель

Создание PWA-приложения с двумя основными режимами, которое можно использовать во время езды на велосипеде, прогулок и в повседневной жизни. Приложение должно снять языковой барьер при общении с носителями языка и помочь в изучении иностранных языков.

1.3Целевая аудитория

Изучающие иностранные языки (прежде всего сам разработчик)
Студенты
Потребители новостей на иностранных языках
Пожилые люди и дети
Предприниматели, работающие с иностранными партнёрами
Иммигранты в Европе, которым нужна помощь в повседневном общении

1.4Целевой рынок

Прежде всего Европа. Серверы размещаются в Германии (Hetzner), приложение соответствует требованиям GDPR. Поддерживаемые языки в первой версии: русский, немецкий, английский, испанский, французский. Архитектура позволяет легко добавлять новые языки.

02Режимы работы приложения

2.1Режим 1: Изучение языка + ИИ-чат

Пользователь общается с ИИ для практики иностранного языка. Доступны три подрежима взаимодействия:

2.1.1. Голосовой режим (для велосипеда)

Пользователь говорит голосом, ИИ отвечает голосом. Руки свободны, экран не нужен.

Голос→ STT→ LLM→ TTS→ Ответ голосом

2.1.2. Текстовый режим (на остановках)

Пользователь пишет текст, ИИ отвечает текстом с возможностью озвучивания. Можно просмотреть историю голосового чата, переводы, исправления.

2.1.3. Пассивное прослушивание

ИИ генерирует дайджест новостей на изучаемом языке и озвучивает. Пользователь слушает как подкаст. В MVP источник новостей — ИИ. Позже добавляется RSS.

2.2Режим 2: Помощник в реальном общении

Помогает общаться с носителями языка в реальных ситуациях: звонки в больницу, работодателю, государственные учреждения и т.д.

2.2.1. MVP: Текстовый чат с переводом

Пользователь пишет или говорит на родном языке, система переводит и отображает текст на иностранном. Можно озвучить перевод через TTS. Также можно принять голосовое сообщение собеседника через микрофон, распознать (STT) и перевести.

Ввод (текст/голос)→ [STT]→ Перевод→ [TTS]→ Озвучка

2.2.2. Будущее: Микрофон для живого разговора

Приложение слушает живой разговор через микрофон телефона, в реальном времени показывает STT и перевод на экране, озвучивает перевод через TTS.

Фаза 3

2.2.3. Будущее: VoIP/WebRTC звонки

Звонки через приложение с автоматическим переводом в обе стороны.

Фаза 3

03Технический стек

3.1Фронтенд

Компонент	Технология	Примечание
Фреймворк	React + TypeScript	Архитектура для лёгкой миграции на Vue
Тип приложения	PWA	Service Worker, офлайн-кэш
Сборщик	Vite	Быстрая сборка, HMR
Локальное хранение	IndexedDB (Dexie.js)	Синхронизация с сервером
Хостинг	Vercel	CDN, европейские edge-серверы

3.2Бэкенд

Компонент	Технология	Примечание
Язык	Python
Фреймворк	FastAPI	Async, авто-документация OpenAPI
База данных	PostgreSQL	На Hetzner VPS
ORM	SQLAlchemy + Alembic	Миграции БД
Хостинг	Hetzner VPS (Германия)	GDPR-compliant, от 4€/мес

04Абстракции над провайдерами

Ядро приложения — фреймворк-агностик библиотека на чистом TypeScript. Не зависит от React/Vue. Это 70-80% всей логики. Каждый провайдер реализует единый интерфейс, что позволяет менять провайдеров без изменения бизнес-логики.

4.1AI Chat — абстракция над LLM

Провайдер	Модели	Особенности
OpenAI	GPT-4o, GPT-4o-mini	Самый широкий функционал
Anthropic	Claude Sonnet, Claude Haiku	Лучший для длинных диалогов
Google	Gemini Pro, Gemini Flash	Быстрый, мультимодальный
Mistral	Mistral Large, Mistral Small	Европейский провайдер (GDPR)
Qwen	Qwen 2.5	Альтернативный провайдер
AssemblyAI	LeMUR	Специализация на аудио

Интерфейс: IChatProvider с методами sendMessage(), streamMessage(), getModels(). Выбор провайдера через конфигурацию или настройки пользователя.

4.2STT — абстракция над распознаванием речи

Провайдер	Технология	Особенности
AssemblyAI	Universal-2	Лучшая точность, real-time
OpenAI	Whisper API	Хорошее качество, многоязычный
Google	Cloud Speech-to-Text	Низкая латентность
Браузер будущее	Web Speech API	Офлайн-фолбэк

Интерфейс: ISTTProvider с методами transcribe(audio), startStreaming(), stopStreaming(), onPartialResult().

4.3TTS — абстракция над синтезом речи

Провайдер	Технология	Особенности
OpenAI	TTS API (tts-1, tts-1-hd)	Самые натуральные голоса
Google	Cloud Text-to-Speech	Много языков и голосов
Браузер (фолбэк)	SpeechSynthesis API	Бесплатно, офлайн

Интерфейс: ITTSProvider с методами speak(text, lang, voice), stop(), getVoices(lang). Автоматический фолбэк на браузерный SpeechSynthesis при недоступности облака.

4.4Translation — абстракция над переводом

Провайдер	Технология	Особенности
DeepL	DeepL API	Лучшее качество для европейских языков
LLM	Claude / GPT / Gemini	Контекстный перевод, объяснения
Google	Google Translate API	Широкий языковой охват

Интерфейс: ITranslationProvider с методами translate(text, from, to), detectLanguage(text), getSupportedLanguages().

05Архитектура

5.1Принцип разделения

Приложение строится на принципе чёткого разделения на два слоя:

Core-библиотека (фреймворк-агностик) — вся бизнес-логика, абстракции над провайдерами, работа с данными. Не зависит от React/Vue. ~70-80% кода.
UI-слой (React) — компоненты, хуки, роутинг. ~20-30% кода. При необходимости переписывается на Vue без изменения core.

5.2Структура проекта

lingua-companion/ ├── packages/ │ ├── core/ — Фреймворк-агностик библиотека │ │ ├── providers/ — Адаптеры AI, STT, TTS, Translation │ │ ├── services/ — ChatService, TranslationService, NewsService │ │ ├── interfaces/ — TypeScript интерфейсы │ │ └── utils/ — Вспомогательные функции │ ├── react-ui/ — React-компоненты и хуки │ └── shared/ — Общие типы и константы ├── apps/ │ ├── web/ — PWA-приложение (React + Vite) │ └── server/ — FastAPI бэкенд └── docs/ — Документация

5.3Поток данных

Голосовой режим

Микрофон→ AudioCapture→ STTProvider→ Текст→ ChatProvider→ Ответ→ TTSProvider→ 🔊

Переводчик

Ввод (текст/голос)→ [STT]→ TranslationProvider→ Перевод→ [TTS]→ 🔊

Новости

ChatProvider→ Дайджест→ TTSProvider→ Аудиопоток 🎧

06Поддерживаемые языки

Язык	Код	Роль в MVP
Русский	`ru`	Родной язык пользователя
Немецкий	`de`	Основной изучаемый
Английский	`en`	Дополнительный
Испанский	`es`	Дополнительный
Французский	`fr`	Дополнительный

Архитектура поддерживает добавление новых языков через конфигурацию без изменения кода.

07Хранение данных

7.1Локальное хранение (IndexedDB)

История чатов с ИИ
Настройки пользователя (языки, провайдеры, голоса)
История переводов
Прогресс изучения
Кэшированные аудио-ответы TTS

7.2Серверное хранение (PostgreSQL)

Синхронизация данных между устройствами
Агрегированный прогресс пользователя
Подготовка к многопользовательскому режиму

7.3Авторизация

В MVP авторизация отсутствует (приложение для личного использования). Архитектура бэкенда закладывает middleware для авторизации, который в MVP пропускает все запросы. Позже: JWT-токены, OAuth2, регистрация.

08Бэкенд API

Все API-запросы к внешним провайдерам проходят через бэкенд (проксирование API-ключей).

Эндпойнт	Метод	Описание
`/api/chat`	POST	Отправка сообщения в LLM (streaming)
`/api/stt`	POST	Распознавание речи (audio → text)
`/api/tts`	POST	Синтез речи (text → audio)
`/api/translate`	POST	Перевод текста
`/api/news`	GET	Генерация дайджеста новостей
`/api/sync`	POST/GET	Синхронизация данных
`/api/health`	GET	Здоровье сервиса

09Нефункциональные требования

GDPR: данные хранятся в Германии (Hetzner), минимальный сбор персональных данных
Латентность: ответ STT < 2с, TTS < 1.5с, перевод < 1с для коротких фраз
Офлайн: интерфейс работает офлайн, история доступна без сети
Мобильность: оптимизация под мобильные устройства, управление одной рукой, крупные кнопки
Безопасность: API-ключи только на сервере, HTTPS, CORS
Миграция: код пишется с учётом возможной миграции UI-слоя с React на Vue

10Фазы разработки

Фаза 1 — MVP

Настройка монорепозитория и инфраструктуры
Core-библиотека: интерфейсы + адаптеры для AI, STT, TTS, Translation
FastAPI бэкенд с проксированием API
Режим 1: ИИ-чат (голос + текст)
Режим 2: Текстовый чат с переводом + голосовой ввод/вывод
PWA: Service Worker, офлайн-оболочка, установка на телефон

Фаза 2 — Новости и прослушивание

Новостной дайджест через ИИ
Озвучивание новостей для пассивного прослушивания
RSS-интеграция

Фаза 3 — Реальное общение

Микрофон для живых разговоров с реал-тайм переводом
VoIP/WebRTC звонки с автопереводом

Фаза 4 — Многопользовательскость

Авторизация (JWT, OAuth2)
Офлайн STT (фолбэк)
Расширенный прогресс изучения языка
Дополнительные языки

11Принципы разработки

Максимально использовать готовые решения — не изобретать велосипед
Быстрые и надёжные решения — проверенные библиотеки и API
Абстракция над провайдерами — лёгкая замена любого компонента
Разделение core/UI — возможность миграции React → Vue
Offline-first — приложение работает даже без сети
Mobile-first — интерфейс для использования на ходу
Europe-first — GDPR, европейские серверы, низкая латентность

ТЗ черный.