Введение в FDA

FDA (Fractal Domain Architecture) — архитектурный подход для приложений на мета-фреймворках (SvelteKit, Next.js, Nuxt), который организует код вокруг бизнес-доменов, а не вокруг технических типов файлов. Внутри каждого домена — одинаковый набор слоёв и файлов с предсказуемыми ролями, и эта структура повторяется от компонента до всего приложения.

🏗️ Зачем нужна ещё одна архитектура

Почти каждый проект начинается одинаково: пара страниц, общая папка components/, utils/, hooks/. Пока страниц пять — это удобно. А когда их пятьдесят, начинается знакомая многим история:

• «Где живёт логика корзины?» — везде: компонент в components/, запрос в api/, валидация в utils/, типы в types/. Изменение одной фичи требует правок в шести папках.
• Новый разработчик не может найти код: структура не подсказывает, корзина — это CartWidget.svelte? useCart.ts? cart.service.ts?
• Переиспользуемое смешалось с доменным: Button.svelte лежит рядом с CheckoutForm.svelte, и непонятно, что можно трогать, а что сломает корзину.

Корень проблемы — организация вокруг технических типов. FDA разворачивает её вокруг бизнеса: код живёт в доменах — auth, cart, dashboard — и у каждого домена одинаковая внутренняя структура. Вопрос «где лежит логика корзины» получает ответ из одного слова: src/routes/cart/.

Заметка

FDA не придумывает новые концепции — domain-driven design, слоистая архитектура и явные границы модулей существуют давно. Она собирает их в конкретный набор правил для файловой структуры, который можно применить в проекте за вечер и передать новому разработчику за час.

🧱 Четыре принципа

1. Фрактальность. Одинаковая структура повторяется на всех уровнях: компонент → субдомен → домен → приложение. Открыв любой модуль FDA-проекта, вы уже знаете, где искать модель, а где — разметку. Навигация по проекту перестаёт быть навыком и становится рефлексом.

2. Разделение на слои. Внутри домена данные проходят один и тот же путь: репозиторий → модель → RPC → контроллер → UI. Каждый слой знает только о соседних нижних. Это защищает от двух классических бед: серверного кода в клиентском бандле (да, NextJS?🤭) и бизнес-логики в разметке.

3. Явные контракты. Каждый файл имеет одну роль и один набор экспортов: model.server.ts — только операции с данными, types.ts — только типы. Ревью ускоряется, потому что нарушение бросается в глаза, а агентам-ассистентам проще генерировать корректный код в изолированной среде.

4. Framework-agnostic. Правила не привязаны к конкретному метафреймворку: SvelteKit, Next.js и Nuxt отличаются именами файлов роутинга, а слои и контракты остаются теми же. Опыт и код доменов переносимы между фреймворками.

🚀 Для каких проектов подходит

FDA рассчитана на приложения среднего и большого размера: дашборды, e-commerce, SaaS-панели, внутренние системы — всё, где бизнес-домены различимы и проект живёт дольше одного спринта.

Осторожно

Когда FDA избыточна. Для лендинга из трёх страниц, прототипа на выходные или библиотеки компонентов накладные расходы на структуру не окупятся. Признак, что FDA пора использовать: вы не можете с ходу сказать, в каких файлах живёт конкретная фича, или новый разработчик тратит день на «просто разобраться, где что».

📚 Как читать документацию

Документация построена от принципов к практике:

1. Основные концепции — фрактальность, слои и контракты: фундамент, на котором держится всё остальное.
2. Структура проекта — как выглядит дерево каталогов FDA-проекта и куда кладётся новый код.
3. Домены и субдомены — как выделять домены и вкладывать субдомены друг в друга.
4. Контракты файлов — роль и экспорты каждого файла в домене, с примерами кода.
5. Кросс-доменное взаимодействие — родитель и потомок, соседние домены и правила связей между ними.
6. FAQ и Checklist — ответы на частые вопросы и чеклист проверки модуля перед мержем.
7. Скилл для AI-агентов — как передать все эти правила агенту: Qwen Code, Claude Code и другим.

🧪 Рабочие примеры

Примеры FDA реализованы на разных фреймворках, чтобы показать переносимость подхода:

Пример	Фреймворк	Статус	Ссылка
example-sveltekit	SvelteKit	✅ Готов	код
example-next	Next.js	🚧 Скоро	код
example-nuxt	Nuxt	🚧 Скоро	код

В примере SvelteKit реализован домен cart — корзина товаров с полным набором слоёв. Его код используется в документации как сквозной пример: вы всегда можете открыть репозиторий и увидеть, как это работает целиком.

🔗 Следующие шаги

→ Основные концепции — фрактальность, слои и контракты подробнее

→ Скилл для AI-агентов — если хотите, чтобы агент собирал домены за вас