id	ROOT-DOC-001
title	Шаблон production-grade монорепозитория
type	root
status	approved
owner	manager
version	1.2.0
updated	2026-07-29

Шаблон production-grade монорепозитория

Репозиторий задает готовую инженерную основу для микросервисного продукта:

• внутренние сервисы и внешние gateway на Go;
• PWA на Vue и TypeScript;
• OpenAPI, Proto/gRPC, AsyncAPI и WebSocket-контракты;
• PostgreSQL как источник истины, Redis как ограниченный read-through cache;
• доменные события через transactional outbox, broker-neutral relay и durable inbox;
• mTLS, подписанный authorization context и replay protection;
• Kubernetes, Vault, NATS JetStream, S3, Prometheus, Grafana, OpenTelemetry, Jaeger и Sentry;
• разработку одним полным unit на PR, три параллельных направления review, повторные циклы исправлений и human gate.

Это не готовый бизнес-продукт. Шаблон фиксирует структуру, технические инварианты, процесс разработки и заполняемые документы, которые новый проект адаптирует под свои домены и требования.

Как создать проект

1. Создать репозиторий через GitHub Use this template.
2. Заменить <organization>/<repository>, <project-name> и другие placeholders.
3. Заполнить источники требований в docs/contract.
4. Описать продукт в docs/product.
5. Зафиксировать архитектуру и доменные границы в docs/architecture и docs/domains.
6. Обновить реестр документов GOV-DOC-001 и реестр контрактов contracts/registry.yaml.
7. Утвердить профиль проверок GOV-DOC-003.
8. Создать первый эпик и реализовывать каждый сервис, gateway, PWA или job одним законченным PR по GUIDE-DOC-004.

Источники правил

• AGENT-DOC-001 — обязательные инструкции людям и агентам;
• GOV-DOC-001 — кодификация и реестр документов;
• CONTRACT-DOC-002 — внутренние Proto/gRPC-контракты;
• CONTRACT-DOC-003 — AsyncAPI, envelope и NATS subjects;
• REPO-DOC-001 — структура монорепозитория и deployable-компонентов;
• GO-DOC-001 — устройство Go-сервисов;
• GO-DOC-002 — PostgreSQL, named SQL и goose;
• GO-DOC-003 — логи, метрики, traces и Sentry;
• GO-DOC-004 — transactional outbox, relay и durable inbox;
• GO-DOC-005 — gRPC, доменные события и NATS JetStream;
• GO-DOC-006 — каталог и границы общих Go-библиотек;
• GUIDE-DOC-003 — распределенная security boundary;
• FE-DOC-001 — Vue/TypeScript PWA;
• INFRA-DOC-001 — Kubernetes, Vault и code-first эксплуатация;
• GUIDE-DOC-004 — один полный unit на PR, три параллельных review и human gate.

Структура

.
├── .github/               # Issues, PR и automation
├── contracts/             # OpenAPI, Proto, AsyncAPI и машинные policy
├── deploy/                # Kubernetes base и environment overlays
├── docs/                  # продукт, архитектура, домены, гайды и runbooks
├── examples/              # нейтральные деревья и компилируемый Go reference
├── infra/                 # bootstrap, IaC и инфраструктурный код
├── libs/go/               # переиспользуемые Go-примитивы
├── services/
│   ├── external/          # внешние gateway
│   ├── internal/          # внутренние доменные сервисы
│   ├── jobs/              # фоновые workers и jobs
│   ├── user/              # пользовательские PWA
│   ├── partner/           # партнерские PWA
│   └── staff/             # служебные PWA
└── tools/                 # генераторы и управляемые операции

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

• бизнесовые домены и названия сервисов без подтвержденной необходимости;
• договор, персональные данные и секреты исходного проекта;
• временные MVP-исключения, если они не утверждены владельцем нового проекта;
• конкретные namespace, Vault paths, registry, URL и account identifiers.

Лицензия и публикация

Владелец нового проекта выбирает лицензию отдельно. Наличие этого шаблона не задает лицензию создаваемому репозиторию.