Архитектура

Раздел "Как устроена Вселенная IT" не нужен для обучения. Существует он только для тех, кому интересно.

Сайт "Вселенная IT" — связка сервисов с единой навигацией и перекрёстными ссылками. Текст и структура знаний живут в репозитории it-knowledge-base; тяжёлый интерактив и длинный код вынесены на отдельные домены, чтобы энциклопедию можно было собирать и отдавать быстро.

Общая идея близка к многоуровневой архитектуре и паттернам микросервисов, но в прагматичном виде — без оркестратора контейнеров на каждый абзац статьи. На практике «Вселенная IT» — это не три–четыре логических уровня, а каскад зон: экосистема продакшена → слой интеграции iframe/postMessage → исходники каждого репозитория → пайплайны сборки (npm-скрипты + SSG) → деплой → runtime в браузере, плюс satellite-сервисы assets и html. Полная карта — на О проекте → архитектура и в info/it-universe-architecture.drawio.

Общая схема

Сборка и выкат связаны с DevOps и CI/CD. Исходники хранятся в Git — см. Основы работы с Git.

Зоны экосистемы (swimlanes)

На полной Draw.io-схеме (info/it-universe-architecture.drawio) восемь горизонтальных зон. Каждая отвечает на свой вопрос — не сводится к «фронт / бэк / БД».

Зона	Вопрос	Ключевые элементы
0. Экосистема	Кто с кем на продакшене?	spirzen.ru, search, terms, lab, kids, games, code, play, html, writer, schema, sql, tools, color, random, assets, status; it-management; APK
0b. Интеграция	Как статья встраивает внешний код?	External*Embed, postMessage, CSP, trusted origins
1. Источники KB	Из чего собирается spirzen.ru?	`docs/` (~3700 в git; на spirzen — энциклопедия, about, context, philosophy, section, toc; glossary/lab/tools и spinoff 9-03/9-04/9-11 — редиректы на порталы), `src/`, `scripts/`, `static/`
2. Сборка KB	Что до `docusaurus build`?	wiki-links, search-index, redirects, collection-titles, webpack
3. it-code-examples	Откуда iframe с кодом?	Astro, Shiki, `/e/embed/<slug>/`
4. it-play	Откуда iframe с демо?	Astro + React, `/p/embed/<slug>/`
5. Деплой	Как попадает на Pages?	GitHub Actions → `deploy-pages` (каждый репозиторий)
6. Runtime	Что грузит браузер?	SPA-оболочка, MDX-статья, click-to-load iframe, inline lazyDemo, DocSearch

Satellite assets и html на swimlane 0 и в таблице О проекте: иллюстрации по прямому URL, WebEditor — отдельное приложение со ссылками из статей.

Упрощённая схема it-universe-three-tier.drawio показывает только 0 + 0b в виде «хаб ↔ code ↔ play» — удобно для первого знакомства, но без сборки, деплоя и runtime.

Роли сервисов

Полная таблица — на О проекте → архитектура и status.spirzen.ru.

Ядро

Сервис	Назначение	Технология
spirzen.ru	Энциклопедия; DocSearch только по статьям (Ctrl+K)	Docusaurus 3 + React 19
search.spirzen.ru	Поиск по всей экосистеме (KB, code, play, terms, lab, tools)	Astro 5, `it-search`
status.spirzen.ru	Хаб и мониторинг доменов	Astro 5, `it-portals`
assets.spirzen.ru	CDN иллюстраций	Статика

Контентные порталы

Глоссарий, лаборатория, инструменты, игры и kids живут на отдельных доменах; пункты меню spirzen.ru ведут туда через редиректы (*ExternalRedirects.json).

Сервис	Назначение	Репозиторий
terms.spirzen.ru	~4250 терминов	`it-terms`
lab.spirzen.ru	Практика, экзамены, тренажёры (~180)	`it-lab`
tools.spirzen.ru	Справочник утилит (~60)	`it-tools`
kids.spirzen.ru	IT для детей (~80)	`it-kids`
games.spirzen.ru	Игровая индустрия и разработка (~130)	`it-games`

Embed (iframe + postMessage)

Сервис	Назначение	Технология
code.spirzen.ru	Листинги (~2500), `/e/embed/<slug>/`	Astro + Shiki
play.spirzen.ru	Визуализаторы (~500 демо), `/p/embed/<slug>/`	Astro + React

Standalone-приложения (ссылки, без iframe)

Сервис	Назначение
html.spirzen.ru	WebEditor — HTML/CSS/JS
writer.spirzen.ru	Редактор статей (frontmatter, embed, экспорт `.md`)
schema.spirzen.ru	Диаграммы и блок-схемы
sql.spirzen.ru	SQL-песочница
color.spirzen.ru	Студия цвета, WCAG
random.spirzen.ru	Генераторы случайных данных

Разделение сделано осознанно.

Размер бандла. Интерактив и порталы (terms, lab, tools, …) держатся вне main bundle spirzen.ru.
Независимые релизы. Обновить глоссарий на terms или тренажёр на lab можно без полной пересборки энциклопедии.
Изоляция. iframe + postMessage для code/play; для порталов — HTTP-редиректы и общая навигация (ecosystem-urls.json).

Паттерны в архитектуре

Ниже — паттерны, которые можно узнать по энциклопедии, и то, как они проявляются именно в "Вселенной IT".

Паттерн	Суть	Где в проекте	Теория в энциклопедии
Static Site Generation (SSG)	HTML/JS собираются заранее, сервер отдаёт файлы	`docusaurus build` → spirzen.ru	Как работают сайты, CDN
SPA с гидратацией	После загрузки HTML React "оживляет" страницу	Docusaurus + React	SPA и frontend-стек
Разделение по bounded context	У каждого домена своя зона ответственности	spirzen / search / terms / lab / code / play / tools / …	Паттерны микросервисов
Embed / Facade	Статья видит простой компонент, внутри — сложный iframe	`ExternalPlayEmbed`, `ExternalCodeEmbed`	Модульность
Lazy loading	Код грузится, когда нужен	`lazyMdxDemoImports`, `lazyDemoInView`	Proxy и lazy loading
Code splitting	Один бандл режется на чанки	Webpack/Rspack `splitChunks`	SPA и bundler
Compile-time transform	Markdown меняется до рендера	remark-плагины	Markdown в вебе
Client-side index	Поиск по заранее собранному JSON	`doc-search-index.json` (spirzen) + `universe-search-index.json` (search.spirzen.ru)	Основы БД и индексы (аналогия)
External redirect	Контент уехал на другой домен	`glossaryExternalRedirects.json`, `labExternalRedirects.json`, …	HTTP-справочник
Redirect / compatibility layer	Старые URL ведут на новые	`plugin-client-redirects`	HTTP-справочник
Gate / deferred init	Тяжёлое стартует по действию пользователя	Click-to-load, `EmbedClickGate`	Polling и push (отложенная загрузка данных)
Cross-cutting enhancement	Общая логика без дублирования в статьях	`DocItem/Layout`, `articleMetaEnhancement`	Составные паттерны
Theme extension (swizzle)	Подмена частей фреймворка	`src/theme/*`	Основы архитектуры

Паттерны сознательно прагматичные — приоритет скорости сборки тысяч статей и предсказуемости для читателя важнее формальной "чистоты" монолита.

Интеграции и способы взаимодействия

1. spirzen.ru ↔ читатель (HTTP)

Браузер запрашивает статику по HTTP. После первой загрузки навигация между статьями идёт как SPA — без полной перезагрузки страницы, с подгрузкой JS-чанков маршрута.

2. spirzen.ru ↔ code.spirzen.ru / play.spirzen.ru (iframe + postMessage)

Этап	Кто	Что происходит
Разметка	MDX-статья	`<ExternalPlayEmbed example="slug" />`
Обёртка	React на spirzen.ru	Click-to-load заглушка, затем `<iframe src="…/p/embed/slug/">`
Выполнение	play / code	Демо или листинг в изолированном документе
Обратная связь	iframe → родитель	postMessage с высотой; проверка origin
Тема	query `?theme=light` или `dark`	Согласование яркости с переключателем на spirzen.ru

Это синхронная встраиваемая интеграция — один общий контракт (slug в URL embed, доверенные origins в src/constants/) вместо отдельного REST-API на каждую статью.

3. spirzen.ru ↔ assets.spirzen.ru (прямые URL)

Картинки в Markdown — ![описание](https://assets.spirzen.ru/...). Браузер качает файл напрямую; CDN кэширует у края сети. Энциклопедия не проксирует байты иллюстраций.

4. spirzen.ru ↔ контентные порталы (HTTP redirect)

Разделы Глоссарий, Лаборатория, Инструменты, Игры, Kids живут на terms / lab / tools / games / kids. Старые URL на spirzen.ru (/glossary/…, /lab/…, …) перенаправляются JSON-картами src/data/*ExternalRedirects.json + plugin-client-redirects. Меню navbar сохраняет привычные пункты; контент отдаёт отдельный Astro-портал.

5. search.spirzen.ru ↔ экосистема (сборка индекса)

При npm run build в it-search скрипт search:index читает метаданные из it-knowledge-base (doc-search-index.json), it-code-examples, it-play, it-terms, it-lab, it-tools и собирает universe-search-index.json. Поиск на search.spirzen.ru — клиентский, без backend. Это отдельно от DocSearch (Ctrl+K) на spirzen.ru, который индексирует только статьи энциклопедии.

6. Репозиторий ↔ сборка (npm-скрипты)

Перед docusaurus build скрипты в scripts/ генерируют артефакты.

Скрипт	Артефакт	Зачем
`docs:wiki-links`	`wikiLinkIndex.json`	Разрешение `[[wiki-ссылок]]` в remark
`docs:search-index`	`doc-search-index.json`	Клиентский поиск
`docs:redirects`	`docLegacyRedirects.json`	Редиректы со старых путей
`docs:collection-titles`	`collectionDocTitles.json`	Заголовки в хабах подборок

Подробнее — в главе Данные и скрипты.

7. remark ↔ MDX (этап компиляции)

remark-плагины — мост между авторским Markdown и бандлом React. wikiLink.js подставляет ссылки; lazyMdxDemoImports.js переписывает import компонентов на lazy-обёртки. Это интеграция на этапе сборки, в рантайме браузера remark уже не работает.

8. localStorage ↔ тема оформления

Палитра дизайна (data-design) и light/dark (data-theme) сохраняются в браузере. Client modules синхронизируют атрибуты при SPA-переходах — см. Темы и стили.

Что происходит при `npm start` / `npm run build`

Цепочка из package.json.

"start": "npm run docs:wiki-links && npm run docs:search-index && npm run docs:redirects && cross-env NODE_OPTIONS=--max-old-space-size=16384 docusaurus start"

Шаг	Скрипт	Результат
1	`docs:wiki-links`	`src/data/wikiLinkIndex.json`, индекс для `[[wiki-ссылок]]`
2	`docs:search-index`	`static/doc-search-index.json`, клиентский поиск (Ctrl+K)
3	`docs:redirects`	`src/data/docLegacyRedirects.json`, редиректы со старых URL
4	`docusaurus start/build`	Webpack/Rspack-сборка сайта

Для продакшена дополнительно запускается docs:collection-titles — заголовки статей в подборках.

Слои приложения spirzen.ru

Внутри одного домена spirzen.ru — ещё один «горный хребет» логических слоёв. Каждый пункт — отдельный слой приложения в смысле многоуровневой схемы.

1. Контент (`docs/`)

Файлы .md и .mdx — статьи, разделы, подборки (~3700 в репозитории: encyclopedia, about, context, philosophy, section, toc; копии glossary/lab/tools и часть spinoff остаются для редиректов, канонический контент — на порталах).
Frontmatter с полями title, description, slug, tags, related и др.
MDX позволяет import React-компонентов прямо в статью.
routeBasePath: '/' ставит документацию в корень сайта (/encyclopedia/...).

Текстовая основа — Markdown и языки разметки.

2. Презентация (`src/theme/`)

Swizzle-компоненты Docusaurus — обёртка статьи, navbar, sidebar, карточки. Здесь вшиты PDF-экспорт, прогресс главы и блок «Смотрите также» без импорта в каждой статье.

3. Интерактив (`src/components/`)

Embed — ExternalPlayEmbed, ExternalCodeEmbed (iframe на отдельные домены).
Inline-демо — *Demo.jsx, DemoShell, lazyDemoInView (~350+ файлов; тяжёлое — в async chunks).
Хабы — CollectionHub, LabTrainersHub, GettingStartedPaths.
Поиск — собственный DocSearch вместо Algolia.

4. Компиляция контента (`src/remark/`, `scripts/`)

Слой до React: remark-плагины (wikiLink, lazyMdxDemoImports) и npm-скрипты (docs:wiki-links, docs:search-index, docs:redirects, docs:collection-titles) генерируют JSON-индексы и редиректы. Это не runtime — но без него сборка и навигация не работают.

5. Данные (`src/data/`)

JSON и JS-модули с подборками, иконками технологий, палитрами дизайна и словарями терминов. Часть генерируется скриптами, часть редактируется вручную.

6. Клиентский bootstrap (`src/clientModules/`)

itDesignThemeInit, limitRoutePrefetch и др. — выполняются в браузере до гидратации React (темы data-design, отложенный prefetch тяжёлых маршрутов).

7. Стили (`src/css/`)

Infima (тема Docusaurus) плюс кастомная система --d-* токенов и 25+ палитр data-design. См. HTML и CSS.

8. Конфигурация и сборка (корень репозитория)

docusaurus.config.js (plugins, webpack splitChunks, customFields для URL embed), sidebars.js, package.json — связывают все слои выше в артефакт build/.

Поток запроса читателя

Браузер запрашивает HTML/JS/CSS с spirzen.ru (или localhost:3000).
Client modules (itDesignThemeInit, limitRoutePrefetch) выполняются на клиенте до гидратации React.
При открытии статьи MDX рендерит markdown; remark-плагины уже преобразовали [[ссылки]] и lazy-import компонентов.
ExternalPlayEmbed показывает click-to-load заглушку; после клика iframe грузит play.spirzen.ru и шлёт postMessage с высотой.
Поиск (Ctrl+K) читает doc-search-index.json и ищет локально в браузере — клиентский поиск.

Производительность как часть архитектуры

Решения заложены в нескольких местах сразу.

remark lazyMdxDemoImports переписывает статический import Foo from '@site/...' в MDX в lazyDemoInView / lazyExternalEmbed.
Webpack splitChunks в docusaurus.config.js выделяет отдельные чанки для React, Docusaurus, Prism, Mermaid и embed-компонентов.
limitRoutePrefetch пропускает prefetch тяжёлых маршрутов (/encyclopedia/, /lab/, /about/interactive).
Click-to-load iframe откладывает ws:// и тяжёлые демо до клика читателя.

На Windows в dev по умолчанию отключён Rspack faster (IT_DOCUSAURUS_FASTER=1 для включения) — иначе возможен EMFILE при тысячах файлов.

Где что искать в репозитории

it-knowledge-base/
├── docs/                  # Контент (статьи)
├── src/
│   ├── components/        # React для MDX и темы
│   ├── theme/             # Swizzle Docusaurus
│   ├── data/              # Статические данные
│   ├── css/               # Глобальные стили
│   ├── remark/            # Плагины markdown
│   ├── clientModules/     # Клиентский bootstrap
│   ├── constants/         # URL embed-сервисов
│   └── pages/             # Главная (отдельно от docs)
├── scripts/               # Генераторы перед сборкой
├── static/                # Файлы как есть (favicon, поисковый JSON)
├── docusaurus.config.js   # Главный конфиг
├── sidebars.js            # Боковое меню
└── package.json           # Зависимости и npm-скрипты

Глоссарий терминов

Краткие определения в контексте "Вселенной IT". Якоря (#сервис) — для ссылок из других глав этого раздела.

Сервис

Отдельно развёрнутое приложение или статический сайт с своим доменом и зоной ответственности. В экосистеме их более пятнадцати — от spirzen.ru до search, terms, lab, tools, writer, schema, sql, color, random, games, kids, code, play, assets, html. Полный список — status.spirzen.ru. Теория — паттерны микросервисов.

Способ перемещения читателя по материалам — navbar, sidebar, подборки, wiki-ссылки, поиск, пагинация статей, карта на главной. Единая навигация связывает все домены через ссылки в тексте.

Репозиторий

Git-хранилище исходников (it-knowledge-base на GitHub). В репозитории лежат docs/, src/, скрипты и конфиги; из него собирается spirzen.ru. См. Основы Git.

Интерактив

Запускаемый в браузере опыт — тренажёры, эмуляторы, игры, пошаговые схемы. В проекте основная масса интерактива на play.spirzen.ru и встраивается через Embed. Витрина — /about/interactive.

Домен

Имя хоста в URL (spirzen.ru, code.spirzen.ru). Отдельный домен даёт изоляцию cookies, origin для postMessage и независимый деплой. См. CDN и DNS.

Листинг

Фрагмент исходного кода в статье или на code.spirzen.ru — часто с подсветкой и возможностью запуска. Листинги на code отделены от текста энциклопедии, чтобы не раздувать бандл.

Визуализатор

Интерактивная схема или анимация (алгоритм, сеть, архитектура ПК). На play.spirzen.ru визуализаторы грузятся в iframe только после click-to-load.

Бандл

Один собранный JS-файл (или группа), который браузер скачивает для работы сайта. Цель архитектуры — держать бандл spirzen.ru лёгким, вынося демо на play/code. См. SPA и bundler.

Чанк

Часть бандла, подгружаемая отдельно (lazy route, embed-компонент). Webpack/Rspack splitChunks режет vendor-react, vendor-docusaurus, async-демо. Подробнее — docusaurus.config.js.

Origin

Пара схема + хост + порт (https://play.spirzen.ru). postMessage принимается только с доверенных origin из constants/codeExamples.js и playExamples.js. См. безопасность веба.

Продакшен

Боевая среда, куда попадает результат npm run build после деплоя. Продакшен-URL embed заданы в docusaurus.config.js (customFields). См. DevOps, CI/CD.

Индекс

Заранее собранная структура для быстрого поиска — wikiLinkIndex.json, doc-search-index.json. Аналогия с индексом в БД, но файл лежит в static/ и читается в браузере.

Клиентский поиск

Поиск по статьям без сервера и без Algolia — Ctrl+K, JSON-индекс, fuzzy-match в docSearchEngine.js. Подробнее — Данные и скрипты.

Редирект

HTTP-перенаправление со старого URL на новый после переименования папок энциклопедии. Источники — docLegacyRedirects.json и ручная карта в config. См. HTTP.

Слой приложения

Логический уровень системы — контент, презентация, интерактив, данные, стили. Соответствует слоям в архитектуре ПО.

Frontmatter

YAML-блок между --- в начале .md/.mdx — title, description, slug, теги. Frontmatter читают Docusaurus и скрипты docs:search-index. Правила — в манифесте и .cursor/rules.

Markdown

Язык разметки текста; в проекте расширен до MDX (Markdown + JSX). См. Текст в веб-технологиях.

Swizzle-компонент

Копия компонента темы Docusaurus в src/theme/, подменяющая стандартную реализацию. Позволяет менять обёртку статьи, navbar, sidebar без форка фреймворка.

Обёртка

React-компонент, который окружает контент — DocItem/Layout, Embed-оболочка вокруг iframe. Паттерн Facade из структурных паттернов.

Верхняя панель сайта — логотип, "Энциклопедия", "Указатель", поиск. Настраивается в themeConfig.navbar и swizzle src/theme/Navbar/.

Боковое меню документации из sidebars.js — дерево разделов, autogenerated для энциклопедии. См. sidebars.js.

Карточка

Компактный блок со ссылкой на статью (DocCard, карточки подборок на главной). Рендерится темой и хабами.

Экспорт

Выгрузка статьи в PDF через ArticlePdfExport (html2canvas + jsPDF) — кнопка в layout статьи.

Embed

Встраивание внешнего контента в страницу. В проекте — React-компонент + iframe на code/play. Отличие от простой ссылки — демо живёт внутри статьи.

Хаб

Страница-каталог — CollectionHub, LabTrainersHub, GettingStartedPaths. Собирает маршруты из src/data/ в один обзор.

Algolia

SaaS-поиск, который Docusaurus поддерживает из коробки. В "Вселенной IT" заменён клиентским поиском из соображений доступности и автономности.

Палитра дизайна

Визуальная тема оформления (data-design) — Matrix, Sakura, "Оригинал" и др. Независима от light/dark. См. Темы и стили.

Infima

CSS-фреймворк по умолчанию в Docusaurus (переменные --ifm-*, сетка, типографика). Кастомные палитры маппятся на Infima через it-design-bridge.css.

Гидратация

Процесс, когда React подключается к уже отрендеренному HTML и делает страницу интерактивной. До гидратации работают client modules и inline-скрипт data-design. См. React.

Заглушка

Плейсхолдер до загрузки тяжёлого блока — EmbedClickGate с кнопкой "Запустить демо". Снижает нагрузку при открытии длинной статьи.

iframe

HTML-элемент вложенного документа. Демо с play/code выполняется в изолированном контексте внутри iframe. См. веб-API браузера.

postMessage

API window.postMessage для обмена данными между окном и iframe. Play шлёт высоту контента; spirzen.ru слушает только доверенные origin.

remark

Экосистема плагинов для обработки Markdown в AST. Плагины в src/remark/ подключены в docusaurus.config.js. См. Markdown.

Click-to-load

Паттерн — iframe и WebSocket демо стартуют только после клика по заглушке. Реализован в ExternalPlayEmbed / ExternalCodeEmbed.

Rspack

Быстрый бандлер (альтернатива Webpack), включается через @docusaurus/faster и future.faster в config.

EMFILE

Ошибка ОС "слишком много открытых файлов". На Windows dev с тысячами MDX Rspack faster по умолчанию выключен.

Связь с остальными главами раздела

docusaurus.config.js — конфигурация сборки, плагины, webpack.
package.json и стек — зависимости и npm-скрипты.
Компоненты — Embed, хабы, MDX.
Темы и стили — Infima, палитра дизайна.
Данные и скрипты — remark, индекс, генераторы.

Общая схема​

Зоны экосистемы (swimlanes)​

Роли сервисов​

Ядро​

Контентные порталы​

Embed (iframe + postMessage)​

Standalone-приложения (ссылки, без iframe)​

Паттерны в архитектуре​

Интеграции и способы взаимодействия​

1. spirzen.ru ↔ читатель (HTTP)​

2. spirzen.ru ↔ code.spirzen.ru / play.spirzen.ru (iframe + postMessage)​

3. spirzen.ru ↔ assets.spirzen.ru (прямые URL)​

4. spirzen.ru ↔ контентные порталы (HTTP redirect)​

5. search.spirzen.ru ↔ экосистема (сборка индекса)​

6. Репозиторий ↔ сборка (npm-скрипты)​

7. remark ↔ MDX (этап компиляции)​

8. localStorage ↔ тема оформления​

Что происходит при npm start / npm run build​

Слои приложения spirzen.ru​

1. Контент (docs/)​

2. Презентация (src/theme/)​

3. Интерактив (src/components/)​

4. Компиляция контента (src/remark/, scripts/)​

5. Данные (src/data/)​

6. Клиентский bootstrap (src/clientModules/)​

7. Стили (src/css/)​

8. Конфигурация и сборка (корень репозитория)​

Поток запроса читателя​

Производительность как часть архитектуры​

Где что искать в репозитории​

Глоссарий терминов​

Сервис​

Навигация​

Репозиторий​

Интерактив​

Домен​

Листинг​

Визуализатор​

Бандл​

Чанк​

Origin​

Продакшен​

Индекс​

Клиентский поиск​

Редирект​

Слой приложения​

Frontmatter​

Markdown​

Swizzle-компонент​

Обёртка​

Navbar​

Sidebar​

Карточка​

Экспорт​

Embed​

Хаб​

Algolia​

Палитра дизайна​

Infima​

Гидратация​

Заглушка​

iframe​

postMessage​

remark​

Click-to-load​

Rspack​

EMFILE​

Связь с остальными главами раздела​

Полезные статьи энциклопедии​

См. также

📄️Как устроена Вселенная IT

📄️docusaurus.config.js

📄️package.json и стек

📄️sidebars.js

📄️TypeScript

📄️Структура src/

📄️Темы и стили

📄️Данные и скрипты

📄️Компоненты