ReMind

ReMind — для всех. Даже для тех, кто ещё не понял зачем.

Обзор · Возможности · Быстрый старт · Docker · Архитектура · Качество

✨ Обзор

ReMind это full-stack AI-приложение на React/Vite и Flask, собранное как реальная продуктовая база: streaming chat, сохранение сессий, share-ссылки, авторизация, безопасные загрузки, privacy endpoints, OpenAPI-контракт, Telegram bot, Celery worker и Docker Compose-инфраструктура лежат в одном репозитории.

Проект находится в статусе beta: основные пользовательские сценарии уже доступны, а UX и внутренняя архитектура продолжают развиваться.

Что важно	Как это устроено
AI chat workspace	SSE-стриминг, история сообщений, session management, guest/auth режимы
Мультимодальность	File upload pipeline, image flow, voice synthesis, translate endpoint
Приватность	Экспорт данных, удаление аккаунта/данных, secure session handling
Production base	Nginx, PostgreSQL, Redis, Celery, health checks, metrics, CI/security gate
Extensibility	OpenAPI, shared services, Telegram bot поверх того же service layer

🚀 Возможности

• Streaming AI chat через POST /chat с server-sent events.
• История диалогов, список сессий, удаление и восстановление контекста.
• Public read-only share links через /sessions/<id>/share и /c/<public_id>.
• Guest mode и auth mode в одном интерфейсе.
• Регистрация, логин, профиль, настройки, избранное и Google OAuth.
• Безопасная загрузка файлов с проверкой имени, MIME-типа и содержимого.
• Перевод текста и text-to-speech через отдельные API endpoints.
• Privacy flows: export/delete пользовательских данных.
• HTML/JSON health check, Prometheus-style /metrics и audit logging.
• Telegram bot на aiogram, использующий общий backend/service layer.

🧱 Технологический стек

Слой	Стек
Frontend	React 19, TypeScript, Vite 7, i18next, Chart.js, D3, Mermaid, Nomnoml
Backend	Python 3.11, Flask, Flask-SQLAlchemy, Flask-Session, Authlib, Waitress, Gunicorn
AI / Media	Gemini API, local echo, demo_image, Pillow, gTTS
Storage / Queue	SQLite for local development, PostgreSQL for deployment, Redis, Celery
Infra	Docker, Docker Compose, Nginx
Quality	Ruff, Black, MyPy, Pytest, Vitest, Playwright, GitHub Actions

⚡ Быстрый старт

Требования

• Python 3.11
• Node.js 20+
• Redis 7+
• Git
• GEMINI_API_KEY для основного Gemini-сценария

1. Клонирование

git clone https://github.com/ReNothingg/ReMind.git
cd ReMind

2. Установка зависимостей

PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
npm ci
Copy-Item .env.example .env

Bash:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
npm ci
cp .env.example .env

3. Настройка .env

Минимальная полезная локальная конфигурация:

SECRET_KEY=replace-with-a-long-random-secret
DATABASE_URL=sqlite:///database/users.db
REDIS_URL=redis://localhost:6379/0
CELERY_BROKER_URL=redis://localhost:6379/1
CELERY_RESULT_BACKEND=redis://localhost:6379/1
GEMINI_API_KEY=

GEMINI_API_KEY нужен для основного AI provider. Для локальных smoke-тестов UI, SSE и истории можно использовать встроенные echo и demo_image.

4. Запуск frontend + backend

npm run dev

Команда запускает:

Сервис	URL
Flask API	http://127.0.0.1:5000
Vite dev server	http://127.0.0.1:5173

Vite проксирует API-запросы на backend.

Если нужно запустить части отдельно:

npm run dev:backend
npm run dev:frontend

5. Дополнительные процессы

Celery worker:

celery -A celery_worker.celery worker --loglevel=info --concurrency=2

Telegram bot:

python -m telegram_bot

Требуется TELEGRAM_BOT_TOKEN.

🐳 Docker

В репозитории есть отдельные Compose-конфигурации для разработки и production-like проверки.

Режим	Команда	Назначение
Dev	docker compose -f docker-compose.dev.yml up --build	Hot reload frontend, backend and worker
Dev shortcut	npm run docker:dev	Запуск dev Compose stack
Production-like	docker compose up --build	Nginx + Flask app + worker + PostgreSQL + Redis

Dev URLs:

• Frontend: http://127.0.0.1:5173
• Backend: http://127.0.0.1:5000

Подробности по Docker: docs/docker.md.

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

graph TD
  UI[React + Vite SPA] -->|HTTP / SSE| API[Flask API]
  TG[Telegram Bot] --> SERVICES[Shared Services]
  API --> SERVICES
  API --> AUTH[Auth + Session Layer]
  API --> FILES[Secure Upload Pipeline]
  SERVICES --> AI[Gemini / Echo / Demo Image]
  SERVICES --> DB[(SQLite / PostgreSQL)]
  API --> REDIS[(Redis)]
  REDIS --> CELERY[Celery Worker]
  NGINX[Nginx] --> API

Loading

Ключевые точки входа:

Путь	Ответственность
app_factory.py	Flask app assembly, middleware, security, sessions and routes
routes/features/	Feature-oriented API modules
services/	Chat history, files, model access, voice and shared business logic
ai_engine/	AI provider adapters and local smoke-test providers
src/	React SPA
telegram_bot/	Bot integration over the shared service layer
openapi/openapi.json	API contract used to generate src/generated/openapi.ts

Больше архитектурных заметок: docs/architecture.md.

🔌 API-контракт

Полезные endpoints:

Endpoint	Назначение
POST /chat	Streaming chat response
GET /sessions	Список сессий
GET /sessions/<id>/history	История выбранной сессии
POST /sessions/<id>/share	Создание public read-only share link
POST /translate	Translate text
POST /synthesize	Text-to-speech synthesis
GET /api/privacy/export	Экспорт пользовательских данных
POST /api/privacy/delete	Удаление пользовательских данных
GET /health	Health check
GET /metrics	Runtime metrics
GET /openapi.json	OpenAPI schema

Проверить generated TypeScript client:

npm run openapi:check

✅ Качество

Backend

pip install -r requirements/dev.txt -c requirements/constraints.txt
ruff check .
black --check .
mypy app_factory.py routes utils services
pytest --cov=routes --cov=services --cov=utils --cov-report=term-missing --cov-fail-under=70

Frontend

npm run typecheck
npm run openapi:check
npm run lint
npm run test:unit:coverage
npm run build

End-to-end

npm run test:e2e:install
npm run test:e2e

CI покрывает secret scanning, backend checks, frontend checks, Playwright e2e и security pipeline через pip-audit, npm audit, bandit и semgrep.

📁 Карта репозитория

.
├── src/                 React + TypeScript frontend
├── routes/features/     Flask feature routes
├── services/            общие backend-сервисы
├── ai_engine/           adapters к AI providers
├── telegram_bot/        Telegram-интеграция
├── openapi/             API-схема
├── tests/               backend-тесты
├── public/              branding, images, manifest и static assets
├── docs/                заметки по архитектуре и запуску
└── .github/             CI, issue templates, PR template и CODEOWNERS

🤝 Участие в разработке

Вклад приветствуется, если он помогает держать проект надежным, безопасным и поддерживаемым.

Перед открытием PR:

1. Прочитайте CONTRIBUTING.md.
2. Не добавляйте secrets и персональные данные в commits.
3. Добавьте или обновите тесты для пользовательского поведения.
4. Запустите релевантные проверки качества из README.
5. Используйте pull request template и приложите подтверждение проверки.

Документы проекта:

• Security Policy
• Support Guide
• Code of Conduct
• Governance
• Pull Request Template
• Issue Templates
• CODEOWNERS

📌 Текущее состояние

• beta: UX и внутренняя архитектура продолжают активно меняться.
• Основной AI-флоу требует GEMINI_API_KEY.
• SQLite удобен для локальной разработки.
• Shared/public deployments лучше запускать на PostgreSQL + Redis.

📄 Лицензия

ReMind распространяется под лицензией GNU AGPLv3. Подробности в LICENSE.