Qadam Platform — продуктовый и архитектурный контур

Паспорт документа

• Статус документа: working spec
• Актуально на: 28 марта 2026 года
• Владелец: backend/platform-команда
• Пересмотр: при изменении платформенной архитектуры, roadmap или статуса реализации
• Область применения: канонические платформенные spec-документы для текущего ядра Qadam
• Связанные документы:
  • Текущее состояние
  • Roadmap
  • Индекс документации

1. Назначение платформы

Qadam — маркетплейс и операционная платформа для дополнительного образования в Узбекистане. Базовая задача продукта — быстро и качественно соединять родителей и учеников с учебными центрами, онлайн-школами и частными преподавателями.

Ключевой базовый путь:

1. Пользователь находит курс или учебный центр.
2. Изучает карточку айтема.
3. Оставляет лид.
4. Продавец получает лид и обрабатывает его.
5. Платформа фиксирует это как бизнес-событие и основу для будущей монетизации.

2. Аудитории и роли

Buyer

• Родитель или ученик.
• Ищет курсы, оставляет заявки, пишет отзывы, ведёт персональный кабинет.

Seller

• Офлайн-школа.
• Онлайн-школа.
• Частный репетитор или индивидуальный эксперт.

Seller Staff

• Сотрудник организации продавца.
• Нужен для дальнейшего развития CRM, управления преподавателями и операционными ролями.

Admin

• Модерация контента.
• Управление справочниками.
• Операционный контроль качества каталога и лидов.

3. Центральная доменная сущность

Главная сущность платформы — Item.

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

• каталог и поиск;
• карточка курса;
• лиды;
• отзывы;
• модерация;
• SEO-слой;
• будущая биллинговая логика.

4. Продуктовые блоки текущего ядра

4.1. Авторизация

• Регистрация и логин по email/phone + password.
• Работа через httpOnly cookies.
• Refresh-flow с ротацией refresh token.

4.2. Каталог

• Публичная выдача айтемов.
• Фильтрация и поиск.
• Детальная страница айтема.
• Публичные страницы продавца.

4.3. Buyer-кабинет

• Профиль пользователя.
• Мои лиды.
• Мои отзывы.

4.4. Seller-кабинет

• Профиль организации.
• Управление айтемами.
• Управление лидами.
• Управление сотрудниками.

4.5. Admin-слой

• Очередь модерации.
• Базовые дашборды и сводки.
• Управление справочниками.

4.6. Внутренняя документация

• Отдельный домен qadam-roadmap.2fab.app.
• Просмотр канонических markdown-документов из qadam-core/docs с переходами в связанные specs и docs/Agents.
• Комментарии к документам.
• Загрузка и удаление файлов.

5. Архитектурная модель

Репозиторий

• Два канонических репозитория: qadam-core и qadam-web.
• Внутри каждого репозитория используется pnpm workspace.
• Общие пакеты покрывают Prisma, shared-схемы и build/config слой; отдельный UI workspace-пакет не является частью текущего production-контура.

Backend

• NestJS + Fastify.
• Глобальный API prefix: /api/v1.
• Prisma как ORM для operational database.
• Redis для token-логики, кэша и инфраструктурных задач.

Frontend

• Next.js App Router.
• React Server Components по умолчанию для публичных страниц.
• TanStack Query для hydration и client-side серверного состояния.
• next-intl для i18n.

Инфраструктура

• Текущий production работает как host deployment.
• systemd для запуска API, product web и roadmap-service.
• nginx как reverse proxy.
• PostgreSQL и Redis на хосте.
• TLS через Let’s Encrypt.

6. Модель данных верхнего уровня

На платформе существуют следующие доменные блоки:

• Account и связанная auth-модель.
• Buyer с профилями родителя или ученика.
• Seller с профилем организации или индивидуального преподавателя.
• SellerStaff и будущие performer/CRM-сущности.
• Item как центральная продаваемая сущность.
• Lead как заявка пользователя.
• Review как отзыв на айтем.
• Subject, Location и другие справочники.
• Tracking/Event для аналитики и наблюдаемости поведения пользователей.

7. Ключевые продуктовые правила

• Публиковаться в каталоге должны только валидные и допущенные к публикации айтемы.
• Buyer и Seller не должны получать доступ к чужим кабинетным данным.
• Весь frontend получает данные только через backend API, а не напрямую из базы.
• Каноническая валидация и transport-контракт определяются backend-схемами в packages/shared и публикуются во frontend через OpenAPI artifact.
• Публичные страницы должны быть совместимы с SSR и SEO.

8. Ограничения текущего этапа

• Платформа ещё не является завершённым коммерческим продуктом.
• CRM, платежи и продвинутая аналитика находятся за пределами текущего ядра.
• Часть buyer/seller/admin-потоков присутствует в коде, но ещё требует доводки до production-grade качества.

9. Канонический следующий фокус

Ближайший приоритет — не расширение количества направлений, а завершение уже реализованного ядра:

1. Стабилизация и quality gates.
2. Доведение buyer/seller/admin сценариев.
3. Подготовка к GTM и PMF validation.