Полнофункциональная платформа для волонтеров и благотворительных организаций, созданная для геймификации добрых дел и построения активного сообщества.
- ✨ О проекте
- 📸 Скриншоты
- 🚀 Основные возможности (Features)
- 🛠️ Технологический стек и архитектура
- ⚙️ Быстрый старт и запуск
- 🚶♂️ Пользовательские сценарии (User Scenarios)
- 👨💻 Руководство для разработчиков
- ☁️ Развертывание (Deployment)
- 👥 Авторы и контакты
- 📜 Лицензия
MAX Добро — это веб-приложение, созданное для объединения людей, желающих делать добрые дела, и организаций, нуждающихся в помощи. Платформа не только служит доской объявлений для волонтерских мероприятий, но и добавляет элементы геймификации и социальной сети для повышения вовлеченности.
Ключевые цели проекта:
- Упростить поиск волонтерских активностей.
- Мотивировать пользователей через систему кармы, достижений и наград.
- Обучать волонтеров через встроенные курсы и тесты.
- Создать сообщество с помощью историй, комментариев и системы друзей.
- Предоставить удобные инструменты для организаторов мероприятий.
Здесь разместите несколько ключевых скриншотов приложения, чтобы наглядно показать его интерфейс.
| Главный экран | Детали события | Профиль пользователя |
|---|---|---|
 |
 |
 |
| Магазин наград | Панель организатора | Достижения |
|---|---|---|
 |
 |
 |
- Лента и карта событий: Поиск мероприятий в виде списка или на интерактивной карте.
- Геймификация:
- Очки кармы и часы добра: Зарабатываются за участие в событиях.
- Достижения ("Ачивки"): Выдаются за выполнение определенных целей.
- Магазин наград: Возможность потратить карму на виртуальные предметы.
- Еженедельные челленджи: Дополнительные задания для получения бонусов.
- Обучение: Встроенные курсы с тестами и возможностью получить сертификат.
- Социальные функции:
- Лента историй: Делитесь впечатлениями с мероприятий.
- Друзья, лайки, комментарии: Взаимодействуйте с другими волонтерами.
- Профиль: Отслеживайте свой прогресс, статистику, достижения и сертификаты.
- Подписки: Следите за новостями любимых организаций.
- Панель управления: Удобный интерфейс для управления деятельностью организации.
- Создание и управление событиями: Полный цикл от черновика до публикации.
- Управление участниками: Подтверждение и отклонение заявок волонтеров.
- Статистика: Аналитика по подписчикам, событиям и рейтингу.
- Аутентификация: Бесшовный вход через платформу MAX и стандартная регистрация через Supabase (email/пароль).
- AI-помощник: Чат-бот для быстрой навигации и поиска информации.
- Рейтинги (Лидерборды): Соревнуйтесь с другими волонтерами за звание самого активного.
Проект построен на микросервисной (в данном случае, сервисно-ориентированной) архитектуре и состоит из трех независимых частей:
- Backend (API): Ядро приложения, обрабатывающее всю бизнес-логику.
- Frontend (Mini App): Клиентское приложение, с которым взаимодействует пользователь.
- Chat Bot: Точка входа для пользователей платформы MAX.
Здесь можно вставить простую диаграмму архитектуры.
[Пользователь] <--> [MAX Platform] <--> [Chat Bot]
|
+-----> [Frontend (Mini App)] <--> [Backend API] <--> [PostgreSQL (Supabase)]
^
|
[Supabase Auth (Webhooks)]
- Фреймворк: NestJS (Node.js)
- Язык: TypeScript
- База данных: PostgreSQL (управляется через Supabase)
- ORM: Prisma
- Аутентификация: Supabase Auth + JWT + MAX Auth
- API: REST API с документацией Swagger
- Фреймворк: React
- Сборщик: Vite
- Язык: TypeScript
- Стилизация: Tailwind CSS
- Карты: Leaflet + React Leaflet
- Платформа: MAX Bot API
- Среда: Node.js + TypeScript
- Docker и Docker Compose
- Node.js (v20+) и npm
- Git
git clone https://github.com/ShutovKS/MAX-Dobro.git
cd MAX-DobroСоздайте .env файлы в каждой из папок (backend, frontend, chat-bot) на основе *.env.example файлов.
PORT: Порт для бэкенд-сервера. 3001 — стандартное значение.MAX_BOT_TOKEN: Токен вашего бота из платформы MAX. Нужен для валидации входа через MAX.MINI_APP_URL: URL вашего развернутого фронтенд-приложения.JWT_INTERNAL_SECRET: Секретный ключ для подписи внутренних JWT. Сгенерируйте командойopenssl rand -base64 32.DATABASE_URL: Строка подключения к вашей базе данных Supabase (Project Settings -> Database -> Connection string -> URI). Добавьте?pgbouncer=trueв конец для лучшей производительности.DIRECT_URL: То же самое, что иDATABASE_URL.SUPABASE_URL: URL вашего проекта Supabase (Project Settings -> API -> Project URL).SUPABASE_ANON_KEY: Анонимный публичный ключ Supabase (Project Settings -> API -> Project API Keys).SUPABASE_WEBHOOK_SECRET: Придумайте любую секретную строку. Ее нужно будет указать в настройках вебхука в Supabase ( Database -> Webhooks).
VITE_API_BASE_URL: URL вашего локального бэкенда (например,http://localhost:3001).VITE_API_MODE: Установитеrealдля работы с бэкендом илиmockдля использования моковых данных.VITE_SUPABASE_URL: URL вашего проекта Supabase.VITE_SUPABASE_ANON_KEY: Анонимный публичный ключ Supabase.
BOT_TOKEN: Токен бота от платформы MAXBOT_NAME: Ник бота в MAX без @
Этот файл запускает все три сервиса (без локальной БД, так как используется Supabase).
docker-compose up --build -d- Frontend будет доступен по адресу:
http://localhost:3000 - Backend API будет доступен по адресу:
http://localhost:3001 - Swagger Docs будут доступны по адресу:
http://localhost:3001/api/docs
После первого запуска контейнеров примените миграции и наполните базу данных.
# Применить миграции к базе данных Supabase
docker-compose exec backend npm run migrate:dev
# (Опционально) Наполнить базу тестовыми данными
docker-compose exec backend npm run seed- Пользователь регистрируется в приложении через Supabase или входит через MAX.
- Проходит короткий онбординг, выбирая интересующие его направления (например, "Экология", "Животные").
- На главном экране видит карту с ближайшими событиями и ленту мероприятий.
- Находит "Субботник в парке", открывает детали, читает требования.
- Нажимает "Я помогу", подтверждает участие.
- После мероприятия оставляет отзыв и получает очки кармы, часы и, возможно, первое достижение.
- Пользователь с ролью
organizationвходит в систему. Его перенаправляет в панель управления. - Нажимает "Создать событие", заполняет все поля: название, описание, дата, место, требования.
- Публикует событие. Оно появляется в общей ленте у волонтеров.
- В разделе "Управление событиями" отслеживает новые заявки.
- Просматривает профили волонтеров и подтверждает их участие.
- После проведения мероприятия чат события архивируется, а участники автоматически получают награды.
Проект разделен на три основных каталога:
/backend: NestJS приложение./frontend: React (Vite) приложение./chat-bot: Node.js приложение для бота MAX.
Все команды выполняются из корневой папки соответствующего сервиса (например, cd backend).
npm run start:dev: Запуск сервиса в режиме разработки с hot-reload.npm run build: Сборка продакшен-версии.npm run lint: Проверка кода с помощью ESLint.npm run format: Форматирование кода с помощью Prettier.
- Backend: Настроен для развертывания на Vercel (
vercel.json). - Frontend: Docker-контейнер с Nginx для отдачи статики.
- Chat Bot: Может быть развернут на любом хостинге для Node.js (например, Render, Vercel).
Здесь укажите информацию о себе или команде.