mdm-ordinis/docs-internal

Ordinis — internal documentation

Технические детали реализации, архитектура, operator runbooks и project state snapshots. НЕ deployment'ится через Diplodoc — это внутренние артефакты для команды Ordinis (не для consumers).

Consumer-facing документация находится в docs/ и build'ится через Diplodoc → static HTML.

Что внутри

docs-internal/
├── ops/              # Operator runbook (on-call, incidents, recovery)
│   ├── README.md
│   ├── slo.md
│   ├── outbox-dlq.md
│   ├── db-migrations.md
│   ├── vault-unseal.md
│   └── kafka-restart.md
├── status/           # Project state snapshots (по дням сессий)
│   └── *-state.md
└── tech/             # Архитектурные deep-dives, legacy документы
    └── api-integration.md  # legacy (мигрирован в docs/integration/api/)

Когда что использовать

Situation	Read
Я — consumer интегрирующий свой backend	docs/integration/api/ (Diplodoc)
Я — on-call инженер с alert	ops/README.md
Я — Ordinis dev планирующий feature	status/ latest snapshot + design docs в ~/.gstack/projects/claude/
Я — новый разработчик в команде	Сначала consumer docs, потом ops/, потом status/ для context

Архитектурные artifacts (вне репозитория)

Design docs / план-плансы хранятся в ~/.gstack/projects/claude/:

• zimin-main-design-production-prep-20260507-123032.md — prod stand-up plan
• zimin-main-design-approval-workflow-v2-20260507-121632.md — approval flow v2 (DEFERRED)
• zimin-main-design-dict-relationships-v2-20260507-230237.md — lineage + cascade rules
• checkpoints/*.md — session state checkpoints для context-restore

Rationale разделения

Diplodoc документация — public contract для интеграторов:

• Может быть опубликована на public Pages
• Не должна leak'ать internal architecture (security)
• Должна быть стабильной (consumer'ы строят на ней свои интеграции)

docs-internal/ — operational state:

• Runbooks меняются часто (incidents, lessons learned)
• Status snapshots — historical record для команды
• Tech deep-dives — для разработчиков, не consumers

Это разделение делает Diplodoc более фокусированным и менее шумным для consumers.