База знаний по системному дизайну: архитектурные паттерны, фундаментальные принципы, выбор технологий, production-практики, источники и проектные правила. Цель структуры — быстро находить нужную заметку, поддерживать связи между темами и не дублировать одно и то же знание в разных местах.
- Patterns OVERVIEW — оглавление раздела и learning path.
- System design principles — базовые вопросы, которые держат дизайн в фокусе.
- Capacity estimation — грубая математика нагрузки, storage и bandwidth.
- Availability and reliability — SLO, redundancy, graceful failure.
- Consistency models — tradeoff между freshness, latency и coordination.
- Load balancing — распределение трафика и отказоустойчивый ingress.
- Storage selection — выбор primary store, индексов и read models.
- Tools OVERVIEW — canonical страницы технологий.
| Раздел | Роль |
|---|---|
| patterns | Принципы, архитектурные решения, workflow, recipes, learning path |
| tools | Базы данных, очереди, кэши, observability-инструменты |
| sources | Книги, статьи, доклады и provenance |
| meta | Скрипты, шаблоны, проектные skills, память проекта |
- Пользовательские папки и Markdown-файлы называем строго на английском в
kebab-case:load-balancing.md,capacity-estimation.md. - Для обзорных страниц используем единое имя
OVERVIEW.md. - Служебные dot-файлы и файлы инструментов могут сохранять стандартные имена экосистемы:
.gitignore,.githooks/pre-commit. - Порядок разделов задается этой таблицей, а не числовыми префиксами в названиях папок.
Одна мысль должна иметь один основной дом:
- фундаментальный принцип или архитектурный паттерн — в
patterns/; - технология, продукт или инструмент — в
tools/; - внешний источник — в
sources/; - проектные правила, шаблоны и проверки — в
meta/; - overview-файлы только навигируют и кратко объясняют, куда идти.
Каждая сущность в базе знаний имеет единственную canonical страницу, где живут ее факты. Все остальные заметки только ссылаются на эту страницу и не дублируют содержание.
| Сущность | Где canonical страница | Что содержит |
|---|---|---|
| Архитектурный паттерн или принцип | patterns/ |
Проблема, решение, tradeoffs, когда применять |
| Технология или продукт | tools/ |
Назначение, сильные стороны, ограничения, use cases |
| Внешний источник | sources/ |
Что это, откуда, дата добавления, relevance, связи |
| Практический workflow | patterns/production-operations/ или patterns/architecture-design/ |
Алгоритм, проверка результата, частые ошибки |
Если новая заметка повторяет существующую, ставь ссылку на canonical страницу, а не копируй текст.
- Определить тип материала: принцип, паттерн, технология, production-практика, сравнение или источник.
- Создать заметку в соответствующем разделе.
- Добавить ссылку в
OVERVIEW.mdэтого раздела. - Если материал пришел из внешнего источника, добавить карточку в
sources/по шаблону source.md. - Запустить проверку:
python3 meta/scripts/validate.shВ проекте есть три уровня валидации:
- Валидация vault: битые Markdown-ссылки и frontmatter у source-карточек.
- Регенерация canonical-map.json из
patterns/иtools/. - Canonical cross-reference: bare mentions известных сущностей должны быть ссылками.
Все проверки подключены в локальный pre-commit hook .githooks/pre-commit.
- Связи между заметками делаем Markdown-ссылками на существующие файлы.
- Списки в обзорных страницах должны быть ссылками, если материал уже создан.
- Не оставляем битые ссылки как заглушки.
- После meaningful изменения запускаем
python3 meta/scripts/validate.sh. - Перед коммитом включаем hook:
git config core.hooksPath .githooks.