Konstructorium: формальная документация

Данный сайт фиксирует полную техническую, эксплуатационную и организационную документацию платформы Konstructorium.

Нормативные принципы

• Документация описывает фактическое поведение кода и конфигурации, а не намерения.
• Для каждого сервиса используются единые разделы: контекст, API, данные, безопасность, эксплуатация, риски.
• Все межсервисные связи фиксируются на двух уровнях: HTTP-интеграции и shared-model/shared-DB связность.
• Для критичных сценариев предоставляются диаграммы C4, sequence, state, ER.
• Документация поддерживается как часть CI через строгую сборку MkDocs.

Состав платформы

• Прикладные сервисы: auth_service, user_service, product_service, order_service, review_service, admin_service, chat_service, analytics_service, telegram_bot_service.
• Инфраструктура: PostgreSQL, Redis, Docker Compose окружение.
• Тестовый контур: smoke API tests в CI.

Карта чтения

1. Master-документация проекта — единый верхнеуровневый источник правил, ролей, CI/CD, рисков и MVP-path.
2. Раздел Архитектура — для общего понимания системы и интеграций.
3. Раздел Сервисы — для детального контракта каждого компонента.
4. Раздел Инфраструктура — для deployment, env-модели и зависимостей.
5. Разделы Операции и Governance — для эксплуатации, QA и управляемых изменений.
6. Раздел Юридическая документация (РФ) — пользовательские тексты, cookie/аналитика, согласия в коде (обзор, для разработчиков).
7. Раздел Операции → Веб-аналитика — сбор статистики, админ-отчёты, проверки для контрибьюторов.
8. Раздел Справочник — для миграции wiki, глоссария, каталога ошибок и матриц.

Глобальная схема

flowchart TB
  webClient["WebClient"] --> authService["auth_service"]
  webClient --> userService["user_service"]
  webClient --> productService["product_service"]
  webClient --> orderService["order_service"]
  webClient --> reviewService["review_service"]
  webClient --> chatService["chat_service"]
  webClient --> analyticsSvc["analytics_service"]
  adminClient["AdminClient"] --> adminService["admin_service"]
  adminClient --> analyticsSvc
  telegramClient["Telegram"] --> telegramBot["telegram_bot_service"]
  telegramBot --> orderService
  telegramBot --> productService
  authService --> postgresDb["PostgreSQL"]
  userService --> postgresDb
  productService --> postgresDb
  orderService --> postgresDb
  reviewService --> postgresDb
  chatService --> postgresDb
  analyticsSvc --> postgresDb
  adminService --> postgresDb
  orderService --> redisNode["Redis"]
  orderCelery["order_celery"] --> redisNode