# 📂 Структура проекта 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 переменные)
```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)
```bash
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)
```bash
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