From cca3f3fd9770b85015c3bc8c561c5b2ccfd5b8ed Mon Sep 17 00:00:00 2001 From: abdulluda3 Date: Sat, 6 Jun 2026 14:32:43 +0500 Subject: [PATCH] docs(tooling): map web and monorepo commands The tooling guide needed concrete commands for web, bot and root checks. Documenting the current npm workspace setup helps contributors choose the right local and CI validation step. Co-Authored-By: Claude Opus 4.8 --- docs/architecture/MONOREPO_TOOLING.md | 69 +++++++++++++++++++-------- 1 file changed, 48 insertions(+), 21 deletions(-) diff --git a/docs/architecture/MONOREPO_TOOLING.md b/docs/architecture/MONOREPO_TOOLING.md index 1cba7cf..0756eb8 100644 --- a/docs/architecture/MONOREPO_TOOLING.md +++ b/docs/architecture/MONOREPO_TOOLING.md @@ -1,31 +1,58 @@ -Monorepo Tooling +# Monorepo Tooling -Этот документ объясняет monorepo. +Metrix хранит web-клиент, Telegram bot runtime, общие пакеты, Prisma схему, +документацию и тесты в одном репозитории. Цель tooling - дать одинаковые +команды для локальной разработки и CI без лишней платформенной сложности. -Что такое monorepo +## Карта репозитория -Это один репозиторий, где лежит несколько приложений и пакетов. +- `apps/web` - Next.js web-клиент. +- `apps/bot` - npm workspace для Telegram microservices. +- `packages/api` - общий API/data пакет. +- `packages/*` - shared библиотеки, контракты и UI/helpers. +- `prisma` - root Prisma schema и миграции для API слоя. +- `tests` - root unit, integration и contract tests. +- `docs` - архитектура, эксплуатация и workflow команды. -В Metrix есть: +## Root scripts -- apps/web; -- apps/bot; -- packages/api; -- packages/shared; -- packages/ui; -- docs; -- tests. +Root `package.json` держит команды, которые нужны всей команде: -Почему npm workspaces достаточно сейчас +- `npm run typecheck` - API, bot и web typecheck. +- `npm run typecheck:api` - только `packages/api`. +- `npm run typecheck:bot` - build всех bot workspaces. +- `npm run typecheck:web` - Next typegen и web TypeScript. +- `npm test` - root test suite через `node --test`. +- `npm run openapi:validate` - проверка OpenAPI spec. +- `npm run prisma:validate` - синтаксис и валидность root Prisma schema. -Проект уже может: +## Web tooling -- ставить зависимости; -- собирать bot workspaces; -- запускать root scripts; -- проверять API, bot и web отдельно. +`apps/web` использует Next.js, React, TypeScript и ESLint: -Когда нужен Turborepo или Nx +- `npm --prefix apps/web run dev` - локальный dev server. +- `npm --prefix apps/web run build` - production build. +- `npm --prefix apps/web run typecheck` - Next typegen и `tsc`. +- `npm --prefix apps/web run lint` - web ESLint rules. -Если станет много пакетов, тяжелые builds и сложный cache. -Пока npm workspaces достаточно и проще. +TypeScript настройки лежат в `apps/web/tsconfig*.json`. ESLint конфигурация +лежит в `apps/web/eslint.config.mjs`, а prettier правила берутся из root +`prettier.config.js`. + +## Bot tooling + +`apps/bot` сам является npm workspace. Каждый сервис в `apps/bot/services/*` +имеет собственный `package.json`, но общая команда `npm --prefix apps/bot run +build` собирает все сервисы через workspace scripts. + +## Почему npm workspaces достаточно + +Сейчас проекту хватает npm workspaces, потому что: + +- пакетов еще немного; +- build graph понятен вручную; +- CI jobs разделены по API, bot, web, Docker и contract tests; +- кэширование можно держать на уровне npm и GitHub Actions. + +Turborepo или Nx стоит добавлять только когда появятся тяжелые инкрементальные +builds, сложные зависимости между пакетами или заметная экономия от remote cache.