Русский · English

QuizMind Platform

Совместная full-stack control-plane платформа для QuizMind
Next.js web app · NestJS API · BullMQ worker · Prisma/PostgreSQL · Redis · Docker

Это совместный проект / contributed fork. Связь с исходным fork намеренно сохранена, чтобы реальная история разработки оставалась видимой, включая commit history, показывающую основную часть моей работы в этом fork.

Обзор

QuizMind Platform — monorepo-основа для SaaS-подобного control plane вокруг quiz/learning продукта. Она объединяет web dashboard, backend API, background workers, shared domain packages, database schema, support workflows, billing primitives, feature flags, remote configuration и политики совместимости расширений.

Проект полезен как portfolio example, потому что показывает работу с реальной multi-application архитектурой, а не с одним изолированным demo-приложением.

Мой вклад

Большая часть видимой истории разработки в этом fork создана мной. Я сохраняю репозиторий как fork, чтобы контекст совместной разработки и commit history оставались прозрачными, вместо повторной загрузки того же кода в новый репозиторий без истории.

Моя работа была сосредоточена на превращении проекта в более сильный platform-style monorepo и включала:

• развитие структуры monorepo вокруг apps/web, apps/api, apps/worker и границ shared packages/*;
• работу с Next.js web app, admin/dashboard областями и support-oriented UI flows;
• расширение NestJS API modules и shared domain packages для auth, billing, permissions, feature flags, remote config, extension compatibility, logging, queues и support/admin workflows;
• подключение Prisma/PostgreSQL-backed runtime flows для auth, workspaces, billing, admin users, remote config, extension bootstrap, support tickets и operator support sessions;
• поддержку Docker-based локальной инфраструктуры с PostgreSQL, Redis, API, web, worker services, health checks, environment examples и runbooks;
• повышение надёжности через TypeScript type checks, workspace scripts, tests, validation и более ясную operational documentation.

Что демонстрирует проект

• Full-stack platform architecture с Next.js web app, NestJS API, BullMQ worker и shared packages.
• Backend product domains: auth, workspaces, billing, RBAC/ABAC, entitlements, feature flags, remote config, extension compatibility, audit/security events и support workflows.
• Database-backed runtime с Prisma, PostgreSQL, migrations, seed data, demo users и repository-backed API flows.
• Operational setup с Docker Compose для PostgreSQL, Redis, API, web и worker services.
• Team-oriented monorepo structure с pnpm workspaces, Turborepo-style scripts, shared contracts и typed package boundaries.

Архитектура

flowchart LR
    Web[Next.js Web App] --> API[NestJS API]
    API --> DB[(PostgreSQL / Prisma)]
    API --> Redis[(Redis)]
    Worker[BullMQ Worker] --> Redis
    Worker --> DB
    API --> Packages[Shared Packages]
    Web --> Packages
    Worker --> Packages

    Packages --> Contracts[Contracts]
    Packages --> Auth[Auth]
    Packages --> Billing[Billing]
    Packages --> Permissions[Permissions]
    Packages --> Extension[Extension Compatibility]
    Packages --> Logger[Logger]

Loading

Основные приложения

Область	Путь	Назначение
Web app	apps/web	Next.js-приложение для landing pages, auth flows, dashboard и admin/support surfaces.
API	apps/api	NestJS backend для auth, billing, RBAC, feature flags, remote config, extension compatibility, support/admin APIs и connected Prisma flows.
Worker	apps/worker	BullMQ worker для background jobs, scheduled tasks, billing/notification workflows, quota resets и config propagation.
Shared packages	packages/*	Переиспользуемые contracts, permissions, auth, billing, extension, logger, config, database, email, queue, provider, usage и UI boundaries.
Documentation	docs/*	Architecture, data model, API surface, service composition, remote config, billing, web app, support и Docker/platform runbooks.

Продуктовые модули

• Authentication, sessions, refresh/logout flows, email verification и workspace membership.
• Основа ролей и permissions: system roles, workspace roles, RBAC/ABAC и entitlement-aware access control.
• Billing primitives: subscriptions, entitlements, add-ons, overrides, wallet и usage-related domain models.
• Feature flags, remote config layers, extension version compatibility и bootstrap policies.
• Admin и support surfaces: user directory, support ticket queue, ticket workflow transitions, operator support sessions, handoff notes, favorite queue presets и audit-backed timeline history.
• Foundations для audit, activity, domain, telemetry, security events и structured logging.

Технологический стек

Слой	Технологии
Frontend	Next.js, React, TypeScript, shared UI package
Backend	NestJS, TypeScript, workspace packages, typed contracts
Database	Prisma, PostgreSQL, migrations, seed data
Background jobs	BullMQ, Redis, worker service
Infrastructure	Docker, Docker Compose, health checks, environment examples
Tooling	pnpm, Turborepo-style workspace scripts, TypeScript type checking, Node test runner, Prettier

Структура репозитория

apps/
  web/       # Next.js application
  api/       # NestJS backend
  worker/    # BullMQ background worker
packages/
  auth/
  billing/
  config/
  contracts/
  database/
  email/
  extension/
  logger/
  permissions/
  providers/
  queue/
  secrets/
  ui/
  usage/
docs/
  architecture.md
  api-surface.md
  billing-flow.md
  control-plane-primitives.md
  data-model.md
  foundation-roadmap.md
  remote-config-flow.md
  service-composition.md
  support-flow.md
  web-app-flow.md
infra/
scripts/

Быстрый старт

Предварительные требования

• Node.js с включённым Corepack
• pnpm 10.x
• Docker и Docker Compose для полного connected runtime

Установка зависимостей

corepack enable
pnpm install

Запуск проверок

pnpm lint
pnpm typecheck
pnpm test
pnpm build

Запуск локального режима разработки

pnpm dev

Локальные сервисы по умолчанию:

• Web: http://localhost:3000
• API: http://localhost:4000
• Worker: по умолчанию запускается в mock-friendly режиме

Connected Docker runtime

Docker-конфигурация запускает полный локальный platform stack:

• PostgreSQL 16
• Redis 7
• API service
• Web service
• Worker service

docker compose up --build

Docker-порты по умолчанию:

Сервис	URL / порт
Web	http://localhost:3000
API	http://localhost:4000
PostgreSQL	localhost:5432
Redis	localhost:6379

При запуске контейнеров API автоматически применяет Prisma migrations и seed demo data. Worker ждёт, пока API и backing services станут healthy, и только после этого запускается.

Подробнее:

• docs/docker-guide.md
• docs/site-platform-extension-connection-runbook.md

Настройка базы данных

Для ручной локальной работы с базой данных:

corepack pnpm --filter @quizmind/database db:migrate:dev
corepack pnpm --filter @quizmind/database db:seed

После seed доступны demo personas; актуальные development credentials указаны в seed data и local runbooks.

Demo personas

Web app поддерживает role-oriented demo views через query parameters:

• platform-admin — полный dashboard и admin visibility.
• support-admin — support workflows и ограниченная admin visibility.
• workspace-viewer — только dashboard с состоянием отказа в admin access.

Примеры:

/app?persona=platform-admin
/admin?persona=workspace-viewer

Основные API и runtime возможности

Connected mode включает Prisma-backed foundations для:

• register, login, refresh, logout, /auth/me и email verification.
• GET /workspaces и GET /billing/subscription.
• GET /admin/users и admin user directory UI.
• GET /admin/feature-flags.
• POST /admin/remote-config/publish.
• POST /extension/bootstrap для compatibility policy, feature flags, active remote config layers и workspace subscription plan.
• Support sessions, ticket queues, ticket ownership/workflow transitions, handoff notes, audit-backed timeline history и operator favorite presets.

Карта документации

• docs/architecture.md — высокоуровневая platform architecture.
• docs/data-model.md — заметки по domain и database model.
• docs/api-surface.md — обзор API surface.
• docs/service-composition.md — границы services/modules.
• docs/remote-config-flow.md — flow публикации remote config.
• docs/billing-flow.md — billing и entitlement flow.
• docs/web-app-flow.md — flow web application.
• docs/support-flow.md — support и operator workflows.
• docs/foundation-roadmap.md — запланированные platform foundation milestones.

Статус

Этот репозиторий — развивающаяся platform foundation. Несколько connected Prisma-backed flows уже реализованы, при этом часть platform modules намеренно остаётся в виде roadmap-ready primitives.

Почему проект важен для технического обзора

Для рекрутеров и инженерных ревьюеров проект демонстрирует практический опыт в:

• организации monorepo;
• typed full-stack TypeScript development;
• backend service boundaries;
• концепциях authentication и authorization;
• проектировании database schema;
• Dockerized local infrastructure;
• support/admin workflows;
• platform-style product thinking.