Как создавался Amitable: архитектура и инженерные принципы

Создание Amitable — это работа одновременно над моделью продукта и над инфраструктурой, которая помогает эту модель понимать. В репозитории уже есть NestJS GraphQL API, хранение в PostgreSQL, обновления через Socket.IO и статический сайт на Astro вокруг этого ядра.

Границы должны быть видны

Рабочее пространство — основная граница для записей, участников, разрешений и обновлений в реальном времени. Коллекция принадлежит рабочему пространству, а связи между полями проверяются в рамках той же границы. Так правило продукта остаётся рядом с кодом, который его обеспечивает: связанные данные не должны случайно стать данными между разными пространствами.

API разделён на функциональные модули. Резолверы описывают GraphQL-поверхность, сервисы содержат операции предметной области, а репозитории делают выбор способа хранения явным. Благодаря этому процесс можно тестировать без запуска всего приложения в каждом тесте.

Используйте типы там, где у данных есть смысл

Системные метаданные записей документов хранятся в типизированных колонках PostgreSQL. Пользовательские значения живут в JSONB, поскольку их форма задаётся коллекцией. Эти два слоя намеренно разделены:

type DocumentRecord = {
  id: string
  workspaceId: string
  documentCollectionId: string
  values: Record<string, unknown>
  version: number
}

GraphQL-валидация не позволяет клиентам записывать системные метаданные как значения бизнеса. Описание поля указывает, является ли значение строкой, числом, логическим значением или ссылкой, а правила ссылок проверяются до сохранения.

Делайте изменения наблюдаемыми

Изменения записей получают версии и распространяются через аутентифицированное пространство реального времени. Клиент может продолжить работу с известного курсора, а не начинать с нуля при каждом подключении. Это важно, когда несколько людей редактируют одну коллекцию, импортируют данные или проверяют записи.

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

Выбирайте простые и явные операции

Проект отдаёт предпочтение API репозиториев и entity manager для сохранения. У функциональности должны быть легко обнаружимы транзакция, граница авторизации и внешние побочные эффекты. Когда процесс пересекает PostgreSQL, real-time-доставку или интеграцию, явные шаги проще повторить и проверить, чем скрытую цепочку колбэков.

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