Как мы сделали «Маяк» — веб-приложение для волонтеров и организаций

Введение

Эта статья посвящена нашему первому опыту участия в продуктовом хакатоне Kodik Launchpad, про разработку веб-приложения за ограниченное время и про то, как AI может быть не просто модной надстройкой, а полноценным инструментом в процессе создания продукта.

Мы участвовали в треке AI + Automation, куда входили AI-ассистенты, генерация кода и интерфейсов, автоматизация бизнес-задач и интеграции с API. Формат хакатона был построен не вокруг идеи «сделать прототип за пару дней», а вокруг полноценного цикла запуска - придумать идею, собрать MVP, доработать продукт, подготовить демо и довести проект до публикации.

Наша команда называлась drooling cat. Нас было двое, поэтому разработка получилась довольно интенсивной. Нужно было одновременно думать о продукте, архитектуре, интерфейсе, backend-логике, AI-функциях и пользовательском опыте. Наши гитхабы:

На хакатоне часто хочется сделать что-то одновременно полезное, понятное и технически интересное. Так появился «Маяк» - веб-приложение, которое помогает волонтерам и организациям находить друг друга.

Идея простая. Организация публикует задачу, волонтер находит подходящую возможность помочь, откликается, общается с организацией и отслеживает свои заявки в личном кабинете. Но когда мы начали раскладывать это на реальные сценарии, оказалось, что внутри довольно много продуктовой и инженерной логики: роли, отклики, чаты, уведомления, верификация организаций, избранное, рекомендации и помощь ИИ при создании задач.

Мы думали о проекте, который не будет выглядеть как абстрактная учебная задача. Хотелось, чтобы в нем была понятная человеческая проблема.

С волонтерством такая проблема есть сразу с двух сторон. Организациям часто нужны люди под конкретные задачи: помочь на мероприятии, привезти вещи, поучаствовать в акции, помочь приюту, закрыть разовую активность. Но поиск людей может быть неудобным. Информация разбросана по чатам, соцсетям, отдельным сайтам и личным контактам.

У волонтеров обратная проблема. Человек может хотеть помочь, но не всегда понимает, где его помощь сейчас действительно нужна, подходит ли ему задача по месту, времени, навыкам и формату. Чем сложнее путь от желания помочь до конкретного действия, тем выше шанс, что человек просто отложит это «на потом».

Мы захотели сделать сервис, который работает как ориентир. Отсюда и название - «Маяк».

Перед разработкой мы постарались разложить «Маяк» не просто как набор страниц, а как систему с несколькими типами участников и понятным движением данных между ними.

На верхнем уровне у нас есть несколько групп пользователей: волонтеры, НКО/организации и потенциально корпоративные партнеры. В MVP основной фокус был на двух ключевых ролях - волонтере и организации, потому что именно между ними происходит главный сценарий: организация публикует задачу, а волонтер находит ее, откликается и дальше взаимодействует с организацией внутри платформы.

Frontend реализован как веб-клиент на Vue 3, TypeScript, Vite, Tailwind CSS, Pinia и Vue Router. На уровне интерфейса мы выделили несколько основных зон: ленту рекомендаций, поиск задач, раздел с мероприятиями и личный кабинет. Личный кабинет отличается в зависимости от роли пользователя: у волонтера это отклики, избранное, история и чаты, у организации - профиль, задачи, отклики волонтеров, верификация и коммуникация.

Связь между frontend и backend идет через HTTPS REST API. Отдельно мы выделяли слой API Gateway - не как отдельный микросервис, а как логический уровень, через который проходят авторизация, проверка JWT, маршрутизация запросов и разграничение доступа по ролям. Это важно, потому что почти каждое действие в системе зависит от того, кто его выполняет: волонтер, организация или администратор.

Серверная часть написана на FastAPI. Backend отвечает за основную бизнес-логику: регистрацию и авторизацию, профили пользователей и организаций, создание задач, статусы откликов, избранное, уведомления, чаты и административные функции. Для работы с данными используется PostgreSQL и SQLAlchemy ORM.

Отдельным блоком в архитектуре мы заложили AI-модуль рекомендаций. Он отвечает за сопоставление волонтеров и задач: анализирует параметры задачи, описание, теги, навыки и другие признаки, чтобы помогать пользователю быстрее находить подходящие варианты. Внутри этого блока можно выделить две части: matching-механику, которая считает соответствие, и NLP-обработку, которая помогает работать с текстовыми описаниями задач.

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

В «Маяке» есть две основные роли: волонтер и организация. Волонтер может:

Организация может:

Сначала мы думали, что основным сценарием будет просто «организация создала задачу - волонтер откликнулся». Но в процессе стало понятно, что этого мало. Нужны личные кабинеты, понятные статусы, уведомления, роли, разные ограничения доступа и нормальный пользовательский путь после отклика.

Например, волонтер не должен видеть кнопку создания задачи как активное действие. Организация, наоборот, не должна откликаться на задачи как волонтер. У каждой роли должен быть свой кабинет, своя навигация и свои основные действия.

Основной сценарий для волонтера выглядит так:

Для организации сценарий другой:

На frontend мы старались разделять логику по зонам ответственности.

Есть страницы:

Есть отдельные API-модули, которые отвечают за запросы к backend:

Отдельно используются Pinia stores для данных, которые нужны в разных частях приложения: пользователь, профиль, организация, уведомления, состояние авторизации.

Конечно, в условиях хакатона структура не сразу была идеальной. Проект быстро рос, сначала одна страница, потом роли, потом кабинеты, потом отклики, чаты, уведомления, верификация, AI. Поэтому часть работы была не только в добавлении новых функций, но и в постоянном приведении кода в более понятный вид.

Backend построен вокруг нескольких основных сущностей:

Для MVP важно было не просто сделать набор endpoint’ов, а добиться, чтобы frontend и backend действительно работали вместе: совпадали поля, корректно обрабатывались роли, статусы, ошибки и пустые состояния.

Одна из типичных проблем в таком проекте - когда backend уже отдает данные, но frontend ожидает поле с другим названием. Например, где-то используется avatar_url, где-то logo_url, где-то статус приходит на английском, а в интерфейсе должен отображаться на русском. Такие мелочи быстро начинают ломать пользовательский опыт, поэтому их приходилось постоянно вылавливать и унифицировать.

Мы не хотели добавлять ИИ просто «для галочки». Поэтому выбрали сценарии, где он действительно может помочь пользователю.

Для волонтера ИИ может объяснить, почему задача ему подходит. Например, учитываются описание задачи, навыки, формат и другие параметры.

Для организации ИИ помогает:

Это оказалось полезным именно в продуктовой логике. Организации не всегда удобно писать хорошее описание задачи с нуля. А плохое описание снижает шанс, что волонтер откликнется: непонятно, что делать, где, когда, какие условия, есть ли требования.

ИИ здесь выступает не как отдельная «магическая» функция, а как помощник внутри конкретного сценария.

На первый взгляд роли кажутся простой частью проекта. Есть волонтер, есть организация, у каждого свои кнопки.

На практике почти каждая страница начинает зависеть от роли:

Из-за этого приходилось внимательно проверять не только happy path, но и пограничные случаи. Например, организация не должна видеть интерфейс волонтера как доступный для действия, даже если страница задачи открывается публично.

Много времени ушло на стык frontend/backend. Это нормальная боль для fullstack-проекта: backend меняется, frontend уже что-то ожидает, потом появляются новые поля, статусы, проверки и ошибки.

Особенно часто проблемы возникали в таких местах:

Решали это через постепенную унификацию API-модулей и аккуратную обработку данных на frontend.

На хакатоне легко попасть в ловушку, функция технически работает, но пользоваться ей неприятно.

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

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

Сначала кажется, что делаешь небольшое приложение. Потом появляются:

В какой-то момент главной задачей становится не просто «добавить еще одну функцию», а не дать проекту развалиться от количества связей между частями.

В итоге у нас получился рабочий прототип платформы для волонтеров и организаций. В нем есть:

Это не финальный продукт, а MVP/прототип, который можно развивать дальше. Но уже на этом этапе он показывает основную идею.

После хакатона у проекта есть несколько очевидных направлений развития.

Первое - доверие и безопасность. Для волонтерской платформы важно, чтобы пользователи понимали, кто стоит за задачей, насколько организация проверена и можно ли ей доверять. Поэтому верификацию можно развивать дальше: документы, модерация, история задач, отзывы.

Второе - рекомендации. Сейчас AI-функции уже помогают с задачами, но в будущем можно сделать более умный подбор: учитывать интересы волонтера, город, формат помощи, опыт, доступное время и прошлые отклики.

Третье - коммуникация. Чаты и уведомления можно развивать в полноценный центр взаимодействия: статусы договоренностей, напоминания, быстрые ответы, системные сообщения.

Четвертое - аналитика для организаций. Например, сколько людей увидели задачу, сколько откликнулись, какие задачи закрываются быстрее, какие описания работают лучше.

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

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

С технической стороны это был fullstack-проект с ролями, API, состояниями, чатами, уведомлениями и AI-функциями. С продуктовой - попытка сделать сервис, который помогает людям быстрее находить друг друга и договариваться о помощи.

Главный вывод по разработке с ИИ - он действительно ускоряет работу, особенно на хакатоне. Но чем больше проект, тем важнее не отдавать ему контроль полностью. ИИ может быстро написать код, но он не всегда понимает контекст, роли, ограничения, уже существующую архитектуру и реальные пользовательские сценарии.

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

«Маяк» для нас стал именно таким проектом: с одной стороны - быстрый хакатонный прототип, с другой - основа для сервиса, который можно развивать дальше и который решает понятную человеческую задачу.