nakama/PROJECT_STRUCTURE.md

📂 Структура проекта NakamaSpace

Полная карта проекта с описанием каждого файла и директории.

🗂️ Корневая директория

nakama/
├── backend/              # Backend сервер (Node.js + Express)
├── frontend/             # Frontend приложение (React + Vite)
├── .gitignore           # Игнорируемые файлы для Git
├── .env.example         # Пример переменных окружения
├── package.json         # Зависимости backend и скрипты
├── README.md            # Основная документация
├── SETUP.md             # Подробная инструкция по установке
├── QUICKSTART.md        # Быстрый старт за 5 минут
├── CONTRIBUTING.md      # Гайд для разработчиков
├── LICENSE              # MIT лицензия
└── start.sh             # Скрипт быстрого запуска

🔧 Backend (/backend)

Структура

backend/
├── models/              # MongoDB схемы
│   ├── User.js         # Модель пользователя
│   ├── Post.js         # Модель поста с комментариями
│   ├── Notification.js # Модель уведомлений
│   └── Report.js       # Модель жалоб
├── routes/              # API endpoints
│   ├── auth.js         # Авторизация через Telegram
│   ├── posts.js        # CRUD постов, лайки, комментарии
│   ├── users.js        # Профили, подписки, поиск
│   ├── notifications.js # Система уведомлений
│   ├── search.js       # Интеграция e621 и gelbooru
│   └── moderation.js   # Модерация и жалобы
├── middleware/          # Middleware функции
│   └── auth.js         # Проверка Telegram Init Data
└── server.js            # Точка входа, Express сервер

Модели данных

User (Пользователь)

• telegramId - ID из Telegram (уникальный)
• username, firstName, lastName - Данные пользователя
• photoUrl - Аватар из Telegram
• bio - Описание профиля (до 300 символов)
• role - Роль: user / moderator / admin
• followers / following - Подписчики и подписки
• settings - Настройки фильтров и поиска
• banned - Флаг блокировки

Post (Пост)

• author - Автор (ref User)
• content - Текст поста (до 2000 символов)
• imageUrl - URL изображения
• tags - Массив тегов: furry / anime / other
• mentionedUsers - Упомянутые пользователи
• isNSFW - Флаг 18+ контента
• likes - Массив ID пользователей
• comments - Встроенные комментарии
• reposts - Массив ID пользователей

Notification (Уведомление)

• recipient - Получатель (ref User)
• sender - Отправитель (ref User)
• type - Тип: follow / like / comment / repost / mention
• post - Связанный пост (опционально)
• read - Флаг прочтения

Report (Жалоба)

• reporter - Кто пожаловался (ref User)
• post - На какой пост (ref Post)
• reason - Причина жалобы
• status - Статус: pending / reviewed / resolved / dismissed
• reviewedBy - Модератор (ref User)

API Endpoints

Авторизация

• POST /api/auth/verify - Верификация Telegram Init Data

Посты

• GET /api/posts - Получить ленту (с фильтрами и пагинацией)
• POST /api/posts - Создать пост (с изображением)
• POST /api/posts/:id/like - Лайк/дизлайк
• POST /api/posts/:id/comment - Добавить комментарий
• POST /api/posts/:id/repost - Репост
• DELETE /api/posts/:id - Удалить (автор или модератор)

Пользователи

• GET /api/users/:id - Профиль пользователя
• GET /api/users/:id/posts - Посты пользователя
• POST /api/users/:id/follow - Подписаться/отписаться
• PUT /api/users/profile - Обновить свой профиль
• GET /api/users/search/:query - Поиск пользователей

Уведомления

• GET /api/notifications - Список уведомлений
• PUT /api/notifications/:id/read - Отметить прочитанным
• PUT /api/notifications/read-all - Прочитать все

Поиск

• GET /api/search/furry?query=tags - Поиск в e621
• GET /api/search/anime?query=tags - Поиск в gelbooru
• GET /api/search/furry/tags?query=tag - Автокомплит e621
• GET /api/search/anime/tags?query=tag - Автокомплит gelbooru
• GET /api/search/proxy/:encodedUrl - Проксирование изображений с e621/gelbooru

Модерация (требуют роли moderator/admin)

• POST /api/moderation/report - Создать жалобу (все пользователи)
• GET /api/moderation/reports - Список жалоб
• PUT /api/moderation/reports/:id - Обработать жалобу
• PUT /api/moderation/posts/:id/nsfw - Установить NSFW
• PUT /api/moderation/users/:id/ban - Заблокировать пользователя

🎨 Frontend (/frontend)

Структура

frontend/
├── src/
│   ├── components/      # React компоненты
│   │   ├── Layout.jsx          # Основной Layout с навигацией
│   │   ├── Navigation.jsx      # Нижняя панель навигации
│   │   ├── PostCard.jsx        # Карточка поста
│   │   ├── CreatePostModal.jsx # Модалка создания поста
│   │   ├── CommentsModal.jsx   # Модалка комментариев
│   │   └── PostMenu.jsx        # Меню поста (удалить, пожаловаться)
│   ├── pages/           # Страницы-вкладки
│   │   ├── Feed.jsx            # Лента постов
│   │   ├── Search.jsx          # Поиск (e621 + gelbooru)
│   │   ├── Notifications.jsx   # Уведомления
│   │   ├── Profile.jsx         # Свой профиль
│   │   └── UserProfile.jsx     # Профиль другого пользователя
│   ├── utils/           # Утилиты
│   │   ├── api.js              # Axios API клиент
│   │   └── telegram.js         # Telegram Mini App SDK
│   ├── styles/          # Глобальные стили
│   │   └── index.css           # CSS переменные и базовые стили
│   ├── App.jsx          # Корневой компонент
│   └── main.jsx         # Точка входа React
├── index.html           # HTML шаблон
├── vite.config.js       # Конфигурация Vite
├── package.json         # Зависимости frontend
└── .env.example         # Пример переменных окружения

Компоненты

Layout & Navigation

• Layout - Обёртка с навигацией, содержит React Router Outlet
• Navigation - 4 кнопки: Лента, Поиск, Уведомления, Профиль
  • Использует lucide-react иконки
  • Активная вкладка подсвечивается синим

PostCard (Карточка поста)

Основной компонент для отображения постов:

• Аватар и имя автора (кликабельно → профиль)
• Дата публикации
• Текст поста
• Изображение (если есть)
• Теги с цветовой кодировкой:
  • 🦊 Furry - оранжевый (#FF8A33)
  • 🎌 Anime - синий (#4A90E2)
  • ⚪ Other - серый (#A0A0A0)
• NSFW badge (если помечено)
• Действия: лайк, комментарий, репост
• Меню (три точки): удалить или пожаловаться

CreatePostModal (Создание поста)

Модальное окно с функциями:

• Текстовое поле (до 2000 символов)
• Загрузка изображения (до 10MB)
• Выбор тегов (обязательно хотя бы один)
• Поиск и упоминание пользователей (@username)
• Чекбокс NSFW
• Превью изображения с кнопкой удаления

CommentsModal (Комментарии)

• Список комментариев с аватарами
• Форма добавления (Enter для отправки)
• Время публикации ("только что", "5 мин", "2 ч")
• Автоматическая прокрутка к новому комментарию

PostMenu (Меню поста)

• Для своих постов: Удалить
• Для чужих: Пожаловаться
• Для модераторов: дополнительные опции

Страницы

Feed (Лента)

• Хедер с названием и кнопкой "+"
• Фильтры: Все / Furry / Anime / Other
• Бесконечная загрузка (пагинация)
• Применяет whitelist настройки пользователя
• Pull-to-refresh (планируется)

Search (Поиск)

• Переключатель: Furry / Anime / Mixed
• Строка поиска с автокомплитом тегов
• Сетка результатов (2 колонки)
• Просмотрщик изображений:
  • Полноэкранный режим
  • Swipe влево/вправо
  • Скачивание изображения
  • Информация о тегах и рейтинге

Notifications (Уведомления)

Telegram-стиль баблов:

• Цветовая кодировка по типу уведомления
• Аватар отправителя с иконкой действия
• Превью поста (текст или изображение)
• Непрочитанные выделены фоном
• Счётчик непрочитанных
• Кнопка "Прочитать все"
• Клик → переход к посту или профилю

Profile (Свой профиль)

• Аватар из Telegram
• Имя, username, роль (модератор/админ)
• Редактируемое био (до 300 символов)
• Статистика: подписчики / подписки
• Донаты через Telegram Stars
• Быстрые настройки:
  • Без Furry контента
  • Только Anime
  • Без NSFW
• Кнопка настроек → полная модалка

UserProfile (Профиль другого пользователя)

• Информация о пользователе
• Кнопка подписаться/отписаться
• Список постов пользователя
• Кнопка "Назад"

Утилиты

api.js

Axios клиент с:

• Автоматической добавкой Telegram Init Data в headers
• Обработкой ошибок
• Типизированными методами для всех endpoints
• Dev моками для разработки без Telegram

telegram.js

Обёртка над Telegram Mini App SDK:

• initTelegramApp() - Инициализация
• getTelegramUser() - Получить данные пользователя
• getTelegramInitData() - Init Data для API
• showAlert(), showConfirm() - Нативные диалоги
• hapticFeedback() - Тактильная обратная связь
• openLink(), openTelegramLink() - Открыть ссылки
• Dev моки для тестирования

Стили

Цветовая палитра (CSS переменные)

--bg-primary: #F2F3F5       /* Основной фон */
--bg-secondary: #FFFFFF     /* Фон карточек */
--text-primary: #1C1C1E     /* Основной текст */
--text-secondary: #5C5C5C   /* Второстепенный текст */
--border-color: #C7C7CC     /* Границы */
--divider-color: #E5E5EA    /* Разделители */

--tag-furry: #FF8A33        /* Оранжевый */
--tag-anime: #4A90E2        /* Синий */
--tag-other: #A0A0A0        /* Серый */

--button-dark: #1C1C1E      /* Тёмная кнопка */
--button-accent: #007AFF    /* Акцентная кнопка (iOS синий) */

--search-bg: #E6E6E8        /* Фон поиска */

Анимации

• fadeIn - Плавное появление (0.3s)
• slideUp - Слайд снизу (0.3s)
• scaleIn - Масштабирование (0.2s)

Компоненты

• Радиус скругления: 16px для карточек, 12px для кнопок
• Тени: мягкие rgba(0,0,0,0.08)
• Отступы: 16px стандарт
• Шрифт: SF Pro Display (iOS) / Roboto (Android)

🚀 Скрипты

Корневые (package.json)

npm run dev      # Запуск backend + frontend
npm run server   # Только backend (nodemon)
npm run client   # Только frontend (vite)
npm run build    # Сборка frontend для production
npm start        # Production сервер

Frontend (frontend/package.json)

npm run dev      # Dev сервер Vite (HMR)
npm run build    # Сборка для production
npm run preview  # Превью production сборки

🔐 Безопасность

Backend

• Telegram Init Data валидация с HMAC-SHA256
• JWT для сессий (опционально)
• Multer для безопасной загрузки файлов
• Rate limiting (TODO)
• Санитизация входных данных

Frontend

• XSS защита через React
• CORS настройки
• HTTPS only для production
• Нет хранения секретов в коде

📦 Зависимости

Backend

• express - Web framework
• mongoose - MongoDB ORM
• cors - CORS middleware
• dotenv - Переменные окружения
• axios - HTTP клиент (для API e621/gelbooru)
• multer - Загрузка файлов
• crypto - Криптография для Telegram

Frontend

• react + react-dom - UI библиотека
• react-router-dom - Роутинг
• @twa-dev/sdk - Telegram Mini App SDK
• axios - HTTP клиент
• lucide-react - Иконки
• vite - Сборщик

🎯 Ключевые особенности

Дизайн

• ✅ iOS-стиль минимализм
• ✅ Нейтральная серая палитра
• ✅ Bubble-дизайн для уведомлений
• ✅ Плавные анимации
• ✅ Адаптивная вёрстка

Функциональность

• ✅ Полный CRUD постов
• ✅ Лайки, комментарии, репосты
• ✅ Система тегов (Furry, Anime, Other)
• ✅ Интеграция e621 и gelbooru API
• ✅ Проксирование изображений для доступа из РФ
• ✅ Система уведомлений
• ✅ Подписки на пользователей
• ✅ Модерация и жалобы
• ✅ Настройки whitelist фильтров
• ✅ Telegram авторизация

Качество кода

• ✅ Модульная архитектура
• ✅ Переиспользуемые компоненты
• ✅ Централизованное управление API
• ✅ Error handling
• ✅ Логирование
• ✅ Документация

📝 TODO / Планы развития

• Unit тесты
• E2E тесты
• Rate limiting
• Кэширование (Redis)
• WebSocket для real-time уведомлений
• Telegram Stars интеграция
• Поиск по постам
• Хэштеги
• Приватные сообщения
• Группы/сообщества
• Рекомендации постов (алгоритм)
• Статистика для авторов
• Dark mode
• Мультиязычность

---

Вопросы? Смотрите полную документацию в README.md, SETUP.md и CONTRIBUTING.md