Tracium
Главная точка входа в документацию проекта. За несколько минут — что уже есть в репозитории, что описано только как target design, куда идти дальше.
В документации сосуществуют два типа знаний:
- Текущее состояние репозитория и локального контура — что уже есть в коде, deploy и tooling.
- Целевая продуктовая и архитектурная модель — какую систему проект должен получить по мере развития.
Если не держать это различие в голове, возникает ложное ощущение, что все сервисы и модули уже реализованы. Сейчас это не так: часть документов описывает target design, часть — текущее состояние. Правило маркировки статуса — в 50-processes/documentation-standard.md.
Быстрый старт
Новый разработчик: 00-overview/quickstart.md — пошаговый запуск локального контура с нуля.
С чего начать
- Что строим:
00-overview/vision.md→00-overview/high-level-concept.md→10-business/domain-model.md. - Что реально можно запускать сейчас:
00-overview/quickstart.md→40-operations/deployment.md→50-processes/contributing.md→50-processes/testing-strategy.md. - Что нельзя сломать на production-host:
40-operations/production-environment.md→40-operations/deployment.md→50-processes/gitlab-cicd.md. - Как устроена целевая архитектура:
20-architecture/principles.md→20-architecture/high-level-architecture.md→20-architecture/module-layout.md. - Границы сервисов и контракты:
30-services/index.md, затем README нужного сервиса. - Что пока не определено:
00-overview/roadmap.mdи00-overview/open-questions.md. - Проверить термины:
GLOSSARY.md.
Что уже есть в репозитории
Репозиторий на ранней стадии и содержит в первую очередь каркас проекта:
| Путь | Что там сейчас |
|---|---|
backend/ | минимальный Go backend: cmd/api-server и internal/httpserver |
docs/docs/ | канонический markdown-корпус для Quartz |
deploy/ | compose-окружение, local ingress, production blue/green, env-файлы |
deploy/docker/resources/docs-quartz/ | конфигурация Quartz |
CHANGELOG.md, VERSION | release-метаданные проекта |
Иными словами: код покрывает базовый scaffold, а документация описывает систему следующего масштаба.
Как устроена документация
| Раздел | Что это за знание | Тип |
|---|---|---|
00-overview/ | обзор, видение, roadmap, открытые вопросы | mixed |
10-business/ | доменная модель, правила, термины, сценарии | target |
20-architecture/ | архитектурные решения, схемы, ADR, target layout | target |
30-services/ | карта целевых сервисных границ и контрактов | target |
40-operations/ | текущее окружение, deployment, observability | current + runbooks |
50-processes/ | стандарты документации, тестирования, релизов | current |
Формальные требования к корпусу — в 50-processes/documentation-standard.md.
Как не ошибиться при чтении сервисных README
Каждый сервисный README должен отвечать на три вопроса прямо в начале:
- Это описание текущей реализации или целевой сервисной границы?
- Есть ли уже выделенный код сервиса в репозитории?
- Какие схемы, ADR или соседние сервисы читать после него?
Если в README этого нет, ориентируйтесь на 50-processes/documentation-standard.md и считайте такой документ кандидатом на доработку.
Web и публикация
- Канонический источник истины — markdown в
docs/docs/. - Локальный docs-site доступен через Quartz на
https://docs.tracium.dev:4444. - GitLab Pages публикует документацию из
mainтем же Quartz stack. - Production-like публикация runtime описана в
40-operations/deployment.md.
После make web-up доступны:
https://tracium.dev:4444— landing placeholder.https://docs.tracium.dev:4444— документация.https://api.tracium.dev:4444— текущий минимальный dev API.https://id.tracium.dev:4444— Tracium ID.
Быстрые маршруты по типовым вопросам
| Вопрос | Куда идти |
|---|---|
| Что за продукт и какую проблему он решает | 00-overview/vision.md |
| Какие сущности ключевые в домене | 10-business/domain-model.md |
| Как устроена целевая архитектура | 20-architecture/high-level-architecture.md |
| Какие сервисы вообще предполагаются | 30-services/index.md |
| Что реально можно запустить локально сейчас | 00-overview/quickstart.md |
| Как устроен текущий production host и что нельзя ломать | 40-operations/production-environment.md |
| Как устроен production deploy | 40-operations/deployment.md |
| Как устроен CI/CD | 50-processes/gitlab-cicd.md |
| Как поддерживать документацию в порядке | 50-processes/documentation-standard.md |
Принцип актуальности
- На одну тему — один актуальный документ.
- История решений хранится в ADR и git history, а не в файлах
*-v2.md/*-final.md. - При изменении подхода обновляется текущий канонический документ, а не создаётся параллельная версия.
Для AI-агентов
AI-навигация по уровням — в AGENTS.md. Каждая директория содержит собственный AGENTS.md с императивными инструкциями.