Перейти к основному содержимому

Архитектурная основа платформы Vitiana — главная ось верхнего слоя

Версия: 3.0 Дата: 25.04.2026 Статус: Готов к обсуждению

Назначение документа​

Этот документ — главная архитектурная ось платформы vitiana-api-platform верхнего слоя документации. Он не описывает технологические выборы, не перечисляет таблицы базы данных, не фиксирует контракты API. Он отвечает на главный вопрос: что мы строим, на каких принципах, в каких пределах ответственности, и как все верхнеуровневые оси связаны между собой.

Этот документ читается первым при любом входе в архитектурную документацию платформы. Все остальные документы первичного слоя (overview/) и нижележащих слоёв (reference/, operations/, development/) интерпретируются через призму этого документа и манифеста переосмысления платформы.

Версия 2.0 этого документа сохранена как overview/index-old-2026-04-25.md (статус Черновик, архивная). Решения, зафиксированные в архивной версии, остаются валидными для тех частей, которые не противоречат текущей версии и манифесту.

Правила, на которых основан документ​

Документ построен поверх правил, зафиксированных в рабочей памяти архитектора:

  • Правило 00000 — платформа главенствует над поставщиками (высший приоритет). Платформа задаёт каноничную модель и условия; поставщики — точка входа информации, не ориентир.
  • Современные лучшие практики (modern best practices) — паттерны платформ верхнего уровня (Stripe, Twilio, Algolia, Cloudflare, Snowflake, Vercel, Plaid).
  • Эластичное масштабирование и упаковка по фазам (elastic scaling and packaging) — авто-масштабирование (auto-scaling) как baseline; упаковка вычислений разворачивается через 4 фазы с метрическими и доменными триггерами.
  • Развитие, не деградация (growth not degradation) — никаких заглушек, временных решений без плана миграции, hardcode-привязок.
  • Тезисное обоснование (thesis-based justification) — каждое нетривиальное решение содержит цели, тезисы, отклонённые альтернативы, компромиссы.
  • Удержание контекста связанных логик и документов — все ссылки между документами поддерживаются явно через DocMap.
  • Язык документации — только русский, англоязычные термины с расшифровкой в скобках, без смешения языков в одном предложении.

Что мы строим​

Vitiana как глобальная гибкая модульная платформа верхнего уровня​

vitiana-api-platform — это документная архитектура глобальной гибкой модульной платформы верхнего уровня (top-tier global flexible modular platform) для туристической индустрии.

Это означает следующее:

  • Глобальность — платформа изначально проектируется на десятки и сотни поставщиков информации, разные юрисдикции, разные географии. Не на одного поставщика, не на одну страну.
  • Гибкость — каноничная модель (canonical model) рассчитана на расширение через добавление, не через переписывание.
  • Модульность — каждая возможность платформы — это отдельный модуль с явным контрактом. Модули собираются в нужные комбинации собственными интерфейсами Vitiana и партнёрами с платным доступом.
  • Верхнеуровневость (top-tier) — платформа не подражает upstream-системам; она задаёт собственный стандарт работы с туристическим инвентарём, ценой, обещаниями, бронированием, композицией туров.

Чем платформа НЕ является​

Чтобы границы переосмысления были честными:

  • Не «улучшенный Booking.com» — Booking.com — каталог отелей с прямой продажей конечному клиенту. Vitiana — платформа для тех, кто продаёт туристические продукты, включая собственные сайты Vitiana и партнёров с платным API-доступом.
  • Не proxy над поставщиками — платформа имеет собственную каноничную модель.
  • Не закрытая экосистема одного бренда — двойное использование: собственные сайты + закрытая система с raw API constructor для платящих партнёров.
  • Не MVP — никаких заглушек, временных решений, hardcode-привязок.

Источники монетизации​

Платформа имеет три источника монетизации, все три — first-class с нулевого дня архитектуры:

  1. Собственные сайты (vitrip.store) — продажа туристических продуктов от своего имени конечным клиентам с собственной коммерческой надбавкой.
  2. Партнёры с платным доступом к API — продажа доступа к каноничной модели, поисковой проекции, композиции туров (Tour Builder API), системе бронирования (booking commit) и сопутствующим возможностям.
  3. Агентский слой (agency working surface) — рабочее место для туристических агентств с подпиской и/или комиссией с продаж.

Цена услуг платформы для партнёров — динамическая, зависит от нагрузки (см. overview/platform-as-product.md, часть про динамическое ценообразование). Платформа взимает плату не за «результаты поиска отелей», а за свой агрегационный труд: нормализация, governance, проверка целостности предложений, поисковая проекция, фиксация коммерческих обещаний, гарантии взаиморасчётов.

Архитектурный якорь и приоритеты направлений​

Primary anchor: B2B API marketplace.

Архитектурный якорь определяет порядок инвестиций архитектурных усилий, не исключает другие направления.

Все четыре направления сохраняются в зрелой архитектуре:

НаправлениеПриоритет инвестицийРоль
B2B API marketplacePrimaryГлавный источник монетизации — платный API-доступ для downstream-партнёров
vitrip.store (собственные сайты)Demonstration + own channelДемонстрация возможностей платформы + собственный канал продаж туров
Agency working platformFast-followerРабочее место для туристических агентств; разворачивается после стабилизации Partner API
B2C broader storefrontsSustainedРасширение собственных каналов продаж в зрелых фазах

Расширенное обоснование выбора якоря — в overview/architectural-anchor-and-business-model.md.

Цепочка ответственности​

Зафиксированная цепочка merchant-of-record (классическая модель агрегатора, гибридная per-tenant):

платформа → поставщики (платформа отвечает перед поставщиком)
       ↑
наши клиенты (агентства, партнёры с платным API) → платформа (клиент отвечает перед нами)
       ↑
конечные клиенты партнёров → партнёры (downstream обязательства партнёра)

Все commercial / partner-finance / settlement / post-booking / refund / chargeback документы должны явно поддерживать эту цепочку.

География первой волны​

Восточная Европа + Казахстан: Украина (UA), Чехия (CZ), Польша (PL), Казахстан (KZ) + EU broader.

Соответствующая база соответствия требованиям:

  • GDPR (для всех граждан EU);
  • EU TOMS (Tour Operators' Margin Scheme — режим маржинального налога на добавленную стоимость для туроператоров);
  • UA tax (украинский налоговый режим);
  • KZ tax (казахстанский налоговый режим);
  • Package Travel Directive (Директива EU 2015/2302) — для случаев, когда Tour Builder создаёт «пакетный туристический продукт» (≥2 компонента);
  • Cross-border data transfer mechanisms (трансграничная передача данных) — Standard Contractual Clauses (SCCs) для UA↔EU, KZ↔EU.

Multi-currency: UAH + EUR + CZK + PLN + KZT + USD как cross-currency reference.

Multi-language: UK / RU / CZ / PL / EN / KZ как минимум.

Шесть архитектурных осей верхнего слоя​

Платформа строится вдоль шести взаимосвязанных верхнеуровневых осей. Эти оси — основная декомпозиция архитектуры на уровне overview/. Каждая ось — отдельный документ, который раскрывает её детальнее.

Ось 1: Каноничная доменная ось (canonical domain spine)
       ├── модули, сущности, контуры истины
       ├── что есть Property, Offer, Quote, Booking, Tour и так далее
       └── документ: overview/canonical-domain-spine.md

Ось 2: Поверхности и контуры взаимодействия (surfaces and interaction contours)
       ├── internal / agency / partner / B2C / service-to-service
       ├── tour builder closed surface
       └── документ: overview/layers.md

Ось 3: Платформа как продукт (platform as product)
       ├── B2B API marketplace, dynamic pricing, tenant tiers
       ├── developer experience, sandbox, certification, billing
       ├── Tour Builder как modular API
       └── документ: overview/platform-as-product.md

Ось 4: Ось данных и интеллекта (data and intelligence spine)
       ├── события (events tracking)
       ├── хранилище данных (data warehouse)
       ├── пайплайны (ETL/streaming)
       ├── машинное обучение (ML platform)
       ├── A/B тестирование
       └── документ: overview/data-and-intelligence-spine.md

Ось 5: Операционная ось (operational spine)
       ├── эластичное масштабирование, фазы упаковки
       ├── надёжность, восстановление после аварий
       ├── observability, инциденты, релизы
       └── документ: overview/operational-spine.md

Ось 6: Связь с реализацией (relation to implementation baseline)
       ├── stuba-api как первая реализация ingestion
       ├── технический долг и путь конвергенции
       └── документ: overview/relation-to-implementation-baseline.md

Карта пересечений между осями — отдельный документ: overview/architectural-axes-and-cross-links.md.

Ось 1. Каноничная доменная ось​

Каноничная доменная модель платформы — первичный объект мышления. Все технологические выборы, контракты API, схемы хранения, операционные решения — производные от каноничной модели.

Главный принцип (правило 00000): каноничная модель проектируется от целей платформы, не от структур поставщиков. Любой поставщик отключаем без переделки модели.

Главные группы сущностей:

  • Каноничные мастер-сущности (canonical master entities) — Property (объект размещения), CanonicalProduct (каноничная продуктовая единица), Organization (организация), User (пользователь), Partner (партнёр), Agency (агентство), PolicySet (набор политик), GovernanceDecision (решение управления).
  • Сущности, производные от поставщиков (supplier-derived entities) — Supplier (поставщик), SupplierProperty (представление объекта у поставщика), SupplierProduct (продуктовая единица поставщика), SupplierPayload (полезная нагрузка от поставщика), SupplierSyncRun (запуск синхронизации), SupplierCapabilityProfile (профиль возможностей поставщика), SupplierBookingReference (ссылка на бронирование на стороне поставщика).
  • Операционные сущности предложения (operational offer entities) — Offer (предложение), AvailabilitySnapshot (снимок доступности), PriceSnapshot (снимок цены), Quote (коммерческая фиксация), RevalidationResult (результат повторной проверки), SearchSession (сессия поиска).
  • Транзакционные сущности (transactional entities) — Booking (бронирование), BookingItem (элемент бронирования), BookingEvent (событие бронирования), PaymentIntent (намерение платежа), Refund (возврат), AmendmentRequest (запрос на изменение).
  • Композиционные сущности (composition entities) — TourDraft (черновик тура), TourDraftItem (элемент черновика), TourProposal (коммерческое предложение тура), ProposalVersion (версия предложения), ProposalArtifact (артефакт предложения).
  • Сущности управления и проверки (governance and review entities) — ReviewCase (кейс проверки), MappingDecision (решение о маппинге), MergeDecision (решение о слиянии), Anomaly (аномалия), FieldLineage (происхождение поля), SourcePrecedenceRule (правило приоритета источника).
  • Сущности субъектов, тенантов и доступа (identity, tenancy, access entities) — Tenant (тенант), Workspace (рабочее пространство), RoleAssignment (назначение роли), CapabilityGrant (выданное право), ApiClient (API-клиент), ApiCredential (учётные данные API).

Полное раскрытие каноничной доменной оси — в overview/canonical-domain-spine.md. Детальное описание сущностей и их жизненных циклов — в reference/domain-model.md (документ второго круга, остаётся валидным для зафиксированных в нём решений).

Связи с другими осями:

  • Ось 2 (Surfaces) — каноничные сущности проявляются в контрактах поверхностей по-разному; surface-aware visibility.
  • Ось 3 (Platform as Product) — Tour Builder работает с композиционными сущностями; tenant tiers — с тенантными сущностями.
  • Ось 4 (Data) — все сущности генерируют события; events tracking захватывает их жизненный цикл.
  • Ось 5 (Operational) — sentencyenced lifecycle определяет операционные требования (SLA, мощность, восстановление).
  • Ось 6 (Implementation) — реальные таблицы stuba-api (hotels, usr, events_themes) — первая реализация подмножества каноничной модели.

Ось 2. Поверхности и контуры взаимодействия​

Платформа взаимодействует с миром через разные поверхности (surfaces). Каждая поверхность — отдельный контракт со своей стабильностью, темпом эволюции, набором допустимых полей, политикой видимости коммерческой информации, политикой согласия и аутентификации.

Шесть основных поверхностей:

ПоверхностьКто используетГлавные характеристики
Internal Operational Surface (внутренняя операционная)Внутренние команды Vitiana, операторы, governance, support, financeБогатая модель данных, lineage, mutation-операции, быстрый темп изменений
Agency Working Surface (агентская рабочая)Туристические агентства, агентыПоиск, quote, booking, Tour Builder, customer context, agency-scoped reporting
Partner API Surface (партнёрский API)Партнёры с платным доступом, B2B-интеграторыУзкий стабильный контракт, версионирование, квоты, environment separation
B2C Storefront Surface (B2C-витрина)Конечные клиенты vitrip.store и партнёрских витринRead-heavy, высокий объём, презентационная безопасность, conversion-ориентация
Service-to-Service Surface (сервис-к-сервису)Внутренние сервисы платформыСильная связность с доменной моделью, idempotency, replay safety
Tour Builder Closed Surface (закрытый Tour Builder)Собственные интерфейсы Vitiana + платящие партнёры с тарифом Tour BuilderМодульный API композиции, raw constructor по модулям

Полное раскрытие — в overview/layers.md. Детальные контракты — в reference/api-contracts.md (документ второго круга).

Связи с другими осями:

  • Ось 1 (Domain) — поверхности проявляют каноничные сущности с разной видимостью.
  • Ось 3 (Platform as Product) — Partner API Surface = главная коммерческая поверхность.
  • Ось 4 (Data) — каждое взаимодействие генерирует события; tracking events на B2C/agency поверхностях критичны для продуктовой аналитики.
  • Ось 5 (Operational) — у каждой поверхности своя цель по задержке (latency target), своё SLA.
  • Ось 6 (Implementation) — текущая Stuba-поверхность (https://api.vitrip.store/stuba) — это адаптер ingestion, не часть Partner API Surface.

Ось 3. Платформа как продукт​

Платформа — это самостоятельный коммерческий продукт, не «доступ к чужим данным». Эта ось описывает Vitiana как продукт со всеми атрибутами зрелой B2B SaaS-платформы.

Ключевые атрибуты:

  • Тарифные уровни (tenant tiers) — Free / Starter / Professional / Enterprise с явным набором возможностей.
  • Динамическая тарификация (dynamic pricing) — стоимость зависит от объёма поисковых запросов, quote, booking, ML-инференса, supplier-call budget, сложности запросов.
  • Опыт разработчика (developer experience, DX) — sandbox с реалистичными mock-данными, self-service onboarding, версионированная документация, code samples, SDKs, Postman/HTTP collections.
  • Сертификация (certification flow) — переход партнёра из sandbox в production через интеграционные тесты, KYC/AML, проверку бизнес-модели.
  • SLA-контракт — обещания по uptime, latency, freshness, downtime credits.
  • Модель поддержки (support tiers) — community / email / dedicated success engineer.
  • Self-service инструменты — ротация ключей, управление webhooks, usage dashboard, quota alerts, audit log download.
  • Tour Builder как модульный API — закрытая система с raw API constructor по модулям, доступная собственным интерфейсам Vitiana и платящим партнёрам с соответствующим тарифом.

Полное раскрытие — в overview/platform-as-product.md. Углубление по доменам — в reference/api-as-product.md, reference/economic-model.md, reference/multi-tenant-isolation-strength.md (создаются в фазе 4).

Связи с другими осями:

  • Ось 1 (Domain) — модель тенанта, API-клиента, организации.
  • Ось 2 (Surfaces) — Partner API Surface + Tour Builder Closed Surface — продуктовые поверхности.
  • Ось 4 (Data) — usage metering, partner-facing analytics product.
  • Ось 5 (Operational) — SLA = операционная характеристика; capacity envelopes per tenant tier.
  • Ось 6 (Implementation) — текущий stuba-api имеет работающий Stuba-эндпоинт, но не имеет partner-tier модели.

Ось 4. Ось данных и интеллекта​

Слои данных, машинного обучения, эксперимента — first-class с нулевого дня архитектуры. Решение зафиксировано 25.04.2026.

Тезис: ranking, recommendation, dynamic pricing, anomaly detection, conversion optimization, partner-facing analytics product — всё это требует промышленной data-платформы. Если её не закладывать с нуля, попытка добавить машинное обучение через 12 месяцев потребует переписывания event sourcing, retention policies, schema governance, privacy boundaries.

Контуры оси:

  • Захват событий (events tracking) — schema-aware, governed, разделённый на доменные события (domain events) и аналитические события (analytical events) с границами приватности.
  • Хранилище данных (data warehouse, DWH) — отдельный класс хранилища, append-only лог + materialized views, retention/privacy/cross-tenant aggregation rules.
  • Пайплайны (ETL/streaming) — реальное время через event bus, пакетная обработка через CDC (change data capture), replay capability как first-class.
  • Платформа машинного обучения (ML platform) — feature store, model registry, model serving, model monitoring. Применяется для ранжирования поиска, рекомендаций, динамического ценообразования, обнаружения аномалий приёма данных, оценки риска партнёров.
  • A/B тестирование — feature flags, cohort assignment, exposure tracking, метрики основные/вторичные/охранные (primary/secondary/guardrail), статистическая значимость.
  • Аналитика и BI — внутренняя аналитика для собственной команды + tenant-facing reporting product как часть Platform as Product.

Полное раскрытие — в overview/data-and-intelligence-spine.md. Углубление — в reference/data-platform-and-events-tracking.md, reference/ml-platform.md, reference/ab-testing-platform.md, reference/analytics-and-bi.md (создаются в фазе 4).

Связи с другими осями:

  • Ось 1 (Domain) — все каноничные сущности генерируют события; FieldLineage = ось данных.
  • Ось 2 (Surfaces) — tracking events на B2C/agency, analytics product на Partner API.
  • Ось 3 (Platform as Product) — analytics product = monetizable surface для tenant.
  • Ось 5 (Operational) — observability = data ось наложенная на операционные метрики.
  • Ось 6 (Implementation) — текущий events_themes в stuba-api — первая реализация event capture, требует разделения на domain vs analytical events.

Ось 5. Операционная ось​

Операционная ось — это как платформа живёт в производстве: как масштабируется, как восстанавливается после аварий, как наблюдается, как релизится, как обрабатывает инциденты.

Главные принципы:

  • Эластичность как baseline — горизонтальное масштабирование, авто-масштабирование, изоляция контуров исполнения, capacity envelopes per tenant tier, обратное давление (backpressure), грациозная деградация (graceful degradation).
  • Фазовая упаковка вычислений — 4 фазы (Bootstrap → Service isolation → Workload-specific packaging → Multi-region и dedicated) с метрическими и доменными триггерами перехода.
  • Управляемые сервисы первичны — managed PostgreSQL, Kafka, OpenSearch, Object Storage у OVHcloud — снимают операционное бремя, освобождают команду.
  • Открытые стандарты, без замыкания — PostgreSQL, S3-совместимое хранилище, стандартный Kubernetes API, Kafka, OpenAPI/AsyncAPI; миграция на AWS/GCP возможна без переписывания.
  • План восстановления (disaster recovery) — RTO/RPO targets, geo-redundant backup, restore drills.
  • Наблюдаемость как продукт — metrics, traces, logs + tenant-visible dashboards.
  • Инцидент-менеджмент — runbooks для топ-10 сценариев, on-call rotation, SLA как контракт с credits.

Полное раскрытие — в overview/operational-spine.md. Дорожная карта инфраструктурного масштабирования — в operations/scaling-and-packaging-roadmap.md. Углубление — в operations/runbooks-incident-playbooks.md, operations/sla-and-on-call-model.md, operations/disaster-recovery-and-capacity.md (создаются в фазе 6).

Связи с другими осями:

  • Ось 1 (Domain) — booking lifecycle определяет операционные требования; governance — это операционный процесс с человеком в цикле (human-in-the-loop).
  • Ось 2 (Surfaces) — у каждой поверхности своё SLA.
  • Ось 3 (Platform as Product) — SLA = коммерческое обещание тенанту.
  • Ось 4 (Data) — observability = data spine применённая к операционным метрикам.
  • Ось 6 (Implementation) — текущая инфраструктура stuba-api ещё не покрывает операционную ось целиком (нет multi-region, нет полного DR plan).

Ось 6. Связь с реализацией​

Реальный код-проект stuba-api уже существует и частично работает: первый поставщик Stuba в production, 127 304 отелей загружены, 4.6 миллиона фотографий, 182 страны синхронизированы, базы apivitianadb PostgreSQL 18.1 с задеплоенными схемами hotels, usr, events_themes, geo, amenity.

Это означает: vitiana-api-platform — архитектура поверх уже работающего ядра, не green-field. Архитектура проектируется от целей платформы (правило 00000), но не игнорирует существующую реализацию.

Принципы связи:

  • Реальная реализация — первая итерация ingestion и базового storage. Stuba — первый поставщик, не приоритет.
  • Каноничная модель Vitiana — архитектурный приоритет. Существующие схемы рефакторятся к каноничной модели через адаптер ingestion.
  • При расхождении между каноничной моделью и текущей схемой — расхождение фиксируется как технический долг ingestion слоя, не как ограничение архитектуры.
  • Редактирование stuba-api запрещено архитектору без явного указания пользователя.

Полное раскрытие — в overview/relation-to-implementation-baseline.md. Карта соответствия каноничной модели и реальных таблиц — там же.

Связи с другими осями:

  • Ось 1 — текущие таблицы (hotels, usr, events_themes) — первая реализация подмножества каноничной модели.
  • Ось 4 — events_themes — первая реализация event capture; требует доработки до полного захвата domain + analytical событий.
  • Ось 5 — текущая инфраструктура (managed PostgreSQL vitianaapipg.psql.tools) — первая реализация фазы Bootstrap операционной оси.

Источники истины и политика свежести​

Каноничная и операционная истина (canonical and operational truth) разделены явно. Платформа не смешивает мастер-данные, операционные снимки, транзакционные факты, проверочные решения.

Уровни истины​

УровеньЧто включаетГде живётСрок жизни
Master truth (мастер-истина)Property identity, география, классификаторы, организации, пользователи, политики, governance decisionsПостоянная модель платформы (managed PostgreSQL Public Cloud)Долгоживущая, audit-critical
Supplier truth (истина поставщика)SupplierPayload, SupplierProperty, SupplierProduct, supplier-side statePersistent supplier trace layerAppend-heavy, replay-friendly
Operational truth (операционная истина)Offer, AvailabilitySnapshot, PriceSnapshot, Quote, RevalidationResultPersistent operational layer + rebuildable cacheКраткоживущая, но reproducible
Transactional truth (транзакционная истина)Booking, BookingEvent, PaymentIntent, Refund, AmendmentRequestPersistent transactional layerAudit-critical, retention-grade
Governance truth (истина управления)ReviewCase, MergeDecision, MappingDecision, FieldLineage, SourcePrecedenceRulePersistent governance layerДолгоживущая, audit-critical
Analytical truth (аналитическая истина)События, агрегаты, эксперименты, ML-фичи, ML-предсказанияData warehouseДолгоживущая, retention с privacy boundary

Политика свежести (freshness policy)​

Каждая категория данных имеет явные правила:

  • какой срок допустимой устарелости (acceptable staleness);
  • когда можно использовать кешированную аппроксимацию (cached approximation);
  • когда обязательна повторная проверка с поставщиком (revalidation);
  • что можно показать пользователю как «по лучшим данным» (best effort);
  • что нельзя использовать без живой перепроверки (live recheck);
  • что сохраняется для аудита, даже если перестало быть актуальным операционно.

Политика повторной проверки (revalidation policy)​

Особенно важна для:

  • перехода от поиска к коммерческой фиксации (search → quote);
  • перехода от коммерческой фиксации к бронированию (quote → booking);
  • повторного открытия существующих предложений;
  • сборки тура из нескольких компонентов;
  • повторного расчёта при изменении курсов, supplier data или состава продукта.

Без явных политик свежести и повторной проверки платформа неизбежно начнёт жить в нескольких конфликтующих реальностях.

Архитектурные принципы платформы​

Принцип 1. Поставщик-агностичное ядро (supplier-agnostic core)​

Каноничная модель платформы не подстраивается под модели отдельных поставщиков. Поставщик-специфичные особенности остаются на стороне адаптеров, маппингов и provenance.

Принцип 2. Offer-центричная операционная модель (offer-centric operational model)​

Платформа мыслит не hotel-центричными карточками, а offer-центричной операционной реальностью. Именно offer участвует в quote, pricing, revalidation, booking transition.

Принцип 3. Разделение мастер- и изменчивых данных (separation of master and volatile data)​

Стабильные данные и краткоживущие данные не смешиваются концептуально, даже если технически живут рядом.

Принцип 4. Домен раньше инфраструктуры (domain-first before infra-first)​

Сначала фиксируются доменные сущности, политики истины, операционная семантика. Только потом стабилизируются конкретные технологии, развёртывание, топология.

Принцип 5. Явные правила истины и повторной проверки (explicit truth and revalidation rules)​

Платформа явно знает, что считается правдой, когда эта правда устаревает, в какой точке нужна живая перепроверка.

Принцип 6. Многосубъектный дизайн (multi-subject design)​

Платформа с самого начала учитывает существование разных субъектов: внутренняя команда, агентства, партнёры, конечные клиенты, сервисные клиенты. Это влияет на доступ, контракты API, коммерцию, аудит.

Принцип 7. Аудитируемость и восстанавливаемость (auditability and recoverability)​

Любой критический контур не только функционален, но и объясним, наблюдаем, восстанавливаем после сбоя.

Принцип 8. Человек в цикле там, где нужен (human-in-the-loop where needed)​

Не все проблемные зоны решаются только автоматикой. Matching, governance, anomaly handling, часть операционных сценариев имеют контролируемый ручной путь.

Принцип 9. Эластичность с нулевого дня (elasticity from day zero)​

Платформа проектируется с авто-масштабированием с самого первого документа. Никаких «масштабируем потом».

Принцип 10. Открытые стандарты (open standards)​

Все технологические выборы — по открытым стандартам (PostgreSQL, S3-совместимое, Kubernetes, Kafka, OpenAPI, AsyncAPI). Без проприетарного замыкания.

Принцип 11. Развитие, не деградация (growth not degradation)​

Никаких заглушек, временных решений без плана миграции, hardcode-привязок. Каждый переход между фазами — расширение, не миграция.

Принцип 12. Тезисное обоснование решений (thesis-based justification)​

Каждое нетривиальное архитектурное решение в документе содержит цели, тезисы, отклонённые альтернативы, компромиссы.

Высокоуровневая архитектурная схема​

Текущую архитектурную ось верхнего уровня нужно понимать так:

Внешний мир
   ↓
Поставщики (data ingress points)
   ↓
Адаптеры приёма данных (ingestion adapters)
   ↓
Каноничная модель (canonical model) ← главный объект мышления
   ├── мастер-сущности
   ├── операционные сущности (Offer, Quote)
   ├── транзакционные сущности (Booking, Payment)
   ├── композиционные сущности (Tour)
   ├── governance сущности
   └── tenancy и доступ
   ↓
Поверхности взаимодействия (surfaces)
   ├── Internal Operational
   ├── Agency Working
   ├── Partner API
   ├── B2C Storefront
   ├── Service-to-Service
   └── Tour Builder Closed Surface
   ↓
Клиенты и партнёры
   ├── собственные сайты Vitiana
   ├── туристические агентства
   ├── партнёры с платным API
   ├── конечные клиенты партнёров
   └── сервисные интеграции

   ↕ (поперёк всего)
Ось данных и интеллекта (events, DWH, ETL, ML, A/B)
Операционная ось (масштабирование, observability, инциденты, релизы)
Governance, compliance, ответственность

Это концептуальный порядок, не схема runtime-компонентов. Runtime — следствие, описывается в операционной оси.

Этап зрелости и ограничения текущего состояния​

Что уже считается несущим каркасом​

Что предстоит закрыть в следующих фазах​

В фазе 4 (новые домены):

  • Compliance & Legal Domain (reference/compliance-and-legal.md).
  • Payment Domain (reference/payment-domain.md).
  • Search & Discovery Domain (reference/search-and-discovery.md).
  • API as Product (reference/api-as-product.md).
  • Data Platform & Events Tracking (reference/data-platform-and-events-tracking.md).
  • ML Platform (reference/ml-platform.md).
  • A/B Testing Platform (reference/ab-testing-platform.md).
  • Notification & Communication (reference/notification-and-communication.md).
  • Media & Content (reference/media-and-content.md).
  • Internationalization & Localization (reference/internationalization-and-localization.md).
  • Analytics & BI (reference/analytics-and-bi.md).
  • Economic Model (reference/economic-model.md).

В фазе 5 (углубление):

  • Tour Builder Operational Model (reference/tour-builder-operational-model.md).
  • Booking State Machine (reference/booking-state-machine.md).
  • Multi-tenant Isolation Strength (reference/multi-tenant-isolation-strength.md).

В фазе 6 (operations):

  • Runbooks & Incident Playbooks (operations/runbooks-incident-playbooks.md).
  • SLA & On-call Model (operations/sla-and-on-call-model.md).
  • Disaster Recovery & Capacity (operations/disaster-recovery-and-capacity.md).
  • Расширение operations/settlement-and-reconciliation.md.

В фазе 7 (переработка):

  • Roadmap (выкинуть Year-1 timeline в архив).
  • Clients (пересвязать с tenancy и API as product).
  • Deployment (связать с runbooks/SLA/capacity/DR).

В фазе 8-9 (governance документации и команда):

  • Documentation Governance (development/documentation-governance.md).
  • Team & Staffing Plan (development/team-and-staffing-plan.md).

Что это означает практически​

Сейчас зафиксирован первый сильный опорный слой верхнеуровневой архитектуры. Все принципы, оси, ответственности, источники истины — на месте. Дальнейшая детализация происходит вниз по слоям документации (reference/, operations/, development/).

Ничто не отложено «на потом» в смысле архитектурных принципов — все принципы зафиксированы сейчас. Реализация (и более детальные документы) — следствие верхнего слоя.

Связь с правилами разработки документации​

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

  • Правило 00000 — каноничная модель проектируется от целей платформы, поставщики не упоминаются как ориентир.
  • Современные лучшие практики — ссылки на Stripe/Twilio/Algolia/Cloudflare и другие платформы верхнего уровня.
  • Эластичное масштабирование — операционная ось содержит фазовую упаковку с триггерами.
  • Развитие, не деградация — никаких заглушек, никаких временных решений; каждый принцип закреплён сейчас.
  • Тезисное обоснование — каждый принцип обоснован.
  • Удержание контекста — явные ссылки на 6 осей и связанные документы; полная карта пересечений в overview/architectural-axes-and-cross-links.md.
  • Язык — только русский, англоязычные термины с расшифровкой в скобках при первом упоминании.

Связанная документация​

Документы первичного слоя (overview/)​

Дорожная карта инфраструктуры​

Документы второго круга (reference/)​

Документы развития (development/)​