Архитектурные решения и ADR

Архитектурные решения (Architectural Decisions) — это решения, которые определяют структуру системы и имеют долгосрочные последствия.

Мы завершаем модуль Понимание (Understanding), и теперь пришло время поговорить о том, как фиксировать и объяснять те архитектурные решения, которые определяют направление развития проекта.

Что такое архитектурные решения

Архитектурные решения находятся на архитектурной стороне спектра между архитектурой и дизайном.

Обычно они:

• влияют на структуру приложения;
• трудно изменить после внедрения;
• имеют долговременные последствия.

🧩 Примеры архитектурных решений:

• выбор frontend-фреймворка (React, Next.js, Vue, Astro и др.)
• структура репозитория (monorepo или многорепозитная стратегия)
• подход к организации кода (Domain-Driven Design, Clean Architecture, Feature-Based Structure)
• выбор real-time инфраструктуры (свой WebSocket-сервер или сторонний сервис вроде Pusher)
• инструменты для логирования, мониторинга, observability.

Когда принимать архитектурные решения

На ранних стадиях проекта большинство решений будут архитектурными, так как у нас ещё нет кода, чтобы принимать решения о дизайне.

🕒 Применяем принцип “Last Responsible Moment”:

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

Слишком ранние решения могут привести к параличу анализа и мешают команде двигаться вперёд.

Что важнее — “что” или “почему”

⚠️ В архитектуре важнее “почему”, чем “что”.

Что мы выбрали — вторично.
Почему мы сделали этот выбор — вот настоящая ценность для документации.

Именно поэтому нам нужно использовать инструмент, который позволяет документировать не только решение, но и контекст, альтернативы и последствия.

Что такое ADR (Architecture Decision Record)

ADR — это короткий документ, фиксирующий одно архитектурное решение. Каждый ADR описывает:

1. 📌 Контекст — в какой ситуации принималось решение.
2. 💡 Решение — что именно выбрано.
3. ⚖️ Последствия — положительные и отрицательные эффекты.
4. 📄 Статус — черновик, принято, отменено и т.д.

Со временем ADR-файлы образуют архитектурный журнал решений (Decision Log) — живую историю развития системы.

Пример ADR: Использование Next.js для FoodFleet

# ADR 1: Использование Next.js для клиентского веб-приложения FoodFleet
**Статус:** Accepted (или на русском — «принят»)
**Дата:** 2025-11-08  
**Автор:** Архитектор проекта FoodFleet

---

### Контекст
Для разработки нового клиентского веб-приложения FoodFleet нам нужен современный UI-фреймворк, обеспечивающий:
- высокую производительность и SSR (Server-Side Rendering);
- быстрый старт для опытной команды React-разработчиков;
- поддержку SEO и адаптивности;
- возможность развертывания в AWS (в соответствии с проектным ограничением);
- готовность к росту функциональности и команды.

Срок вывода MVP — 4 месяца.

---

### Решение
Использовать **Next.js** как основной frontend-фреймворк  
и размещать приложение в **AWS** с использованием **SST** для деплоя.

---

### Положительные последствия
- ⚡ Быстрое развитие проекта благодаря знакомому стеку (React/Next.js).  
- 📦 Возможность SSR и статической генерации контента.  
- 🌐 Широкая экосистема и комьюнити.  
- 🧩 Поддержка гибкой архитектуры (монорепо, API routes, middleware).  
- ⏱ Снижение рисков, связанных с изучением новых технологий.

---

### Отрицательные последствия
- 🚧 Некоторая зависимость от экосистемы Vercel и релизного цикла Next.js.  
- 🧠 Необходимость адаптировать существующие внутренние UI-библиотеки.  
- ⚙️ Возможные сложности при тонкой настройке SSR и кэширования.  

---

### Альтернативы
- **Remix** — схожая философия, но менее зрелая инфраструктура.  
- **Nuxt** — ориентирован на Vue, не подходит команде React.  
- **Custom Setup (Vite + React)** — требует больше времени и DevOps-настроек.

---

### Вывод
Next.js позволяет быстро стартовать, оставаясь в рамках ограничений проекта и опыта команды.  
Решение оптимально по скорости, стабильности и поддержке производительности.
markdown