Архитектура

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

Архитектура существует благодаря трём основным элементам. Всё остальное на этой странице принадлежит одному из них:

• Робот-установщик — процесс, который запускает установку и запуск сервера на операционной системе Ubuntu, подключает авторизацию, базу данных, стартовый шаблон и прочее.
• Стартовый шаблон — обязательные архитектурные принципы: переиспользуемые образцы поведения и специальные инструкции для искусственного интеллекта. Это внутренний скелет, ДНК проекта.
• Инфраструктурная оболочка — всё, что вынесено за пределы самого приложения; в центре её лежат авторизация и память.

Робот-установщик Fractera

Сервер не настраивают руками. Установщик получает чистую машину с Ubuntu и оставляет после себя работающий контур. Он сообщает о ходе работы шаг за шагом, поэтому видно, где установка находится и где она остановилась, если остановилась.

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

Установка клонированием репозитория через MCP-сервер

Путь для тех, кто разворачивает сервер инструментом, а не руками: агент обращается к платформе по протоколу MCP и ставит проект сам.

Продолжение следует в ближайшее время.

Запуск через веб-интерфейс

Основной путь. В панели управления есть раздел запуска проекта: одиннадцать шагов от пустого репозитория на GitHub до первого изменения, которое вы увидели на собственном адресе.

Шаги двух родов, и разница содержательная. Одни закрывает машина — репозиторий ответил, ключ выдан, проект отправлен; такую отметку нельзя поставить из вежливости. Другие отмечаете вы: у панели нет глаз на вашем компьютере, и делать вид, что она видит созданную вами папку, было бы ложью. Вашу отметку можно снять — шаг снова открыт.

Миграция из любого другого фреймворка

Проект, который уже работает, переносится не переписыванием файлов. Его код читают как описание того, что он делает; из описания рождается очередь шагов, и первым строится скелет — адреса, таблицы, вход, права. Несовместимый стек поэтому не помеха: переезжает смысл способности, а не её файлы.

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

Данные переносятся последними и отдельным шагом, под отдельным доступом. Дефекты исходного проекта при этом называются вслух и в новый не повторяются.

Стартовый шаблон

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

Готовность к высокой нагрузке

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

Генерация статических страниц

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

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

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

Специальные архитектурные инструкции

Кодирующий агент начинает каждую сессию, не помня предыдущей. Переживает только записанное — внутри проекта, рядом с кодом. Этот корпус такая же часть архитектуры, как порты: он и делает вторую сессию не глупее первой.

Четыре режима разработки

Режим отвечает на один вопрос: откуда берётся задача. Выбирается в настройках проекта и меняется в любой момент.

• Классический — задача приходит от вас словами. Плана вперёд нет, учёта нет.
• Шаги — очередь пронумерованных шагов, каждый описан до того, как сделан. Это умолчание.
• Кейсы — работа начинается только с подтверждённого сценария продукта, и каждый шаг называет свой.
• Миграция — очередь рождается из чтения проекта, который уже работает.

Продукт — единица работы

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

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

Почему не «проект»

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

Не у каждого продукта есть страница

Продукт объявляет одну из трёх поверхностей, и умолчание всегда в сторону закрытого:

• публичная — у продукта есть адрес, и посетители до него доходят;
• закрытая — он живёт вкладкой в панели управления, снаружи входа нет;
• без экрана — у продукта нет страниц вовсе: он работает по расписанию и через каналы связи, и вы встречаете его в Telegram или в его отчёте.

Дизайн

Цвет, шрифт и размеры не выбираются на каждой странице. Шкала лежит в одном месте, палитра в другом, а заголовок, набранный руками, не проходит проверку и до сайта не доезжает. Правило под этим короткое: внешний вид страницы не зависит от того, кому она открыта. Витрина и рабочая таблица набраны одинаково; доступ решает, что человек увидит, и никогда — как это набрано.

Разделы дизайна

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

• Шрифты — какими семействами набраны заголовки и текст;
• Шкала текста — все размеры разом, одним множителем: набор становится крупнее или мельче, сохраняя пропорции;
• Формы — скругления, границы, плотность;
• Цвет — палитра ролями, а не значениями: светлая и тёмная темы это одни роли с разными величинами, а не два дизайна, которые надо держать в согласии руками;
• Блоки — каталог того, из чего собираются страницы;
• Верстак — служебные переключатели, например индикатор ширины экрана.

Блоки

Страница — это список блоков, а не свёрстанный файл. Каталог закрытый: вид, не объявленный в нём, для приложения не существует, и сборка отказывает. Видов больше тридцати, и у каждого есть образец, который можно открыть и посмотреть, — вид, который негде увидеть, не «неиспользуемый», а непроверенный.

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

Типы блоков

Каталог отвечает «что бывает», и для выбора этого мало. Поэтому у блоков есть типы — по назначению, а не по устройству: сначала выбирают тип, и только внутри него вид.

• первый экран · преимущества и ценность · как это работает · демонстрация продукта · сценарии применения;
• сравнение · цены · отзывы · витрина работ · доверие;
• материал страницы — заголовки, абзацы, списки, таблицы, врезки: половина каталога это он.

Четыре файла конфигурации

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

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

Мультиязычность

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

• не делает ни одну страницу динамической: у каждого языка свои страницы, собранные заранее, — десять языков это десять наборов готовых страниц, а не одна страница, собираемая на лету;
• не размывает позиции в поиске: страница объявляет себя оригиналом на своём языке и называет переводы, поэтому поисковик видит одну страницу на десяти языках, а не десять почти-копий, конкурирующих между собой;
• не стоит скорости: отдать заранее собранную страницу — одинаковая работа независимо от того, сколько языков рядом.

Одноязычный сайт — отдельный законный случай, а не урезанный: язык исчезает из адресов вовсе, и сайт перестаёт объявлять переводы, которых у него нет.

Поиск и модели

На современный сайт приходят два читателя, и им нужно разное. Поисковик отправляет на страницу человека. Модель приходит сама, читает и пересказывает. Продукт устроен для обоих, и это две разные задачи.

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

Модели отдаётся тот же текст без разметки: карта в `/llms.txt`, весь корпус в `/llms-full.txt` и markdown-версия рядом с каждой страницей. Это важно потому, что разметка для модели наполовину шум — меню, подвал, баннер согласия, скрипты, — и она тратит на него своё внимание.

Пока семантическая структура проекта не готова, его рекомендуется закрыть от индексации: настройка живёт в настройках приложения, раздел «Поиск». Обе формы страницы при этом собираются из ОДНОГО содержания — отдельной «версии для ИИ», которая разойдётся с основной, не существует.

Ролевой доступ из коробки

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

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

Параллельная маршрутизация

Страница может состоять не из одного дерева, а из нескольких именованных областей, которые рисуются одновременно: шапка, подвал, левая и правая панели, центр со своей шапкой и подвалом, промо-экран, крошки, уведомления, модальное окно. Это способ собрать глубокий интерфейс для профессионала, не превращая сайт в приложение.

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

Продолжение следует в ближайшее время.

Инфраструктурная оболочка

Всё, что управляет проектом, вынесено за пределы самого проекта. В ваш репозиторий уезжает приложение; панель управления, авторизация и данные остаются на сервере. Причина не в закрытости: правка кода не должна уметь сломать то, чем этот код управляется. Сломать контур руками можно — это ваш сервер, — но тогда последствия остаются с вами, и мы говорим об этом прямо.

Как всё связано

На вашем сервере бок о бок работают несколько процессов. Четыре из них отвечают наружу, и у каждого ровно одна задача. Граница между ними проходит по порту, а не по папке — именно поэтому сбой в одном из них не утягивает за собой остальные.

Рядом работают ещё три сервиса, и ни один из них не является самостоятельной дверью:

• карта — маршруты, матрицы расстояний и поиск адресов, порт 3400;
• каналы — Telegram и всё, что за ним последует, порт 3500;
• граф знаний — агентное RAG-хранилище, порт 9621.

Ни один из этих портов недоступен из интернета: фаервол пропускает только веб-порты, и всё публичное поступает через них. Ваше приложение обращается к трём сервисам через слой данных — /service/geo, /service/channels, /service/rag — с тем же ключом, который открывает сам слой данных.

Каждый слой переживает остальные

Отдельные процессы — это не схема, а то, что происходит в плохой день. Любой из четырёх может остановиться, не утянув за собой остальные.

Работа с GitHub

Репозиторий ваш. Проект отправляется в него и забирается обратно кнопкой в панели; адрес репозитория и токен доступа живут на сервере, а не в коде, поэтому они не уезжают вместе с проектом и не попадают в чужие руки вместе с ним.

Право уйти

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

Собственный домен и сертификаты

Проект работает в одном из двух режимов. На старте это адрес по IP и незащищённый протокол — так удобно знакомиться с проектом, и так честно сказано, что часть возможностей браузера в нём недоступна. Второй режим — собственный домен, HTTPS и строгая проверка ролей; в него переходят, как только решили развивать проект всерьёз.

Подключение домена описано в панели: мастер из пяти шагов и пять записей у вашего регистратора — сам домен, `www` и три служебных имени для входа, панели и данных. Сертификат при этом выпускается автоматически.

Сертификаты безопасности

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

Автоматический сертификат

Бесплатный, от Let’s Encrypt. Срок жизни — 90 дней, и продлевается он заранее, а не в последний день. Важно понимать, что именно он подтверждает: контроль над доменом, а не вашу организацию. Проверки компании такой сертификат не содержит — Let’s Encrypt не выдаёт сертификатов с проверкой организации.

Собственный сертификат

Загружается парой «сертификат и ключ» и заменяет автоматический. Нужен, когда этого требует ваша компания или внешний регулятор: например, когда сертификат обязан быть выпущен определённым центром или содержать проверку организации. Срок годности и покрытые имена панель показывает так же.

Авторизация

Учётные записи, сессии и роли живут отдельной службой, а не внутри приложения. Интерфейс входа переведён на 82 языка: покупатель приходит из страны, которую вы не выбирали, и на языке, которого вы не планировали.

Вход по электронной почте

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

Вход через Google

Включается парой «идентификатор и секрет» из консоли Google; адрес возврата панель выдаёт готовым — его остаётся скопировать. Сверх этих двух способов доступно более восьмидесяти готовых провайдеров входа: подключение любого из них — заявка в поддержку, а не разработка.

И главное: вход существует не сам по себе. Он возвращает роль — ту самую, на которой стоят слои маршрутов и замки на дверях к данным. Способ входа меняется; то, что человек получает после него, — нет.

Память

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

База данных

Строки приложения: пользователи, заказы, записи, журнал сборок. Новая таблица объявляется в одном месте и появляется одинаково и на вашей машине, и на сервере — отдельных миграций, которые надо помнить и запускать, здесь нет.

Объектное хранилище

Файлы и то, что о них известно: картинки, видео, документы, наборы значков. Файл адресуется по имени, а не по номеру, поэтому ссылка на него читается человеком и переживает переезд. Видео обрезается на сервере, и длительность после обрезки проверяется, а не предполагается.

Векторное хранилище

Поиск по смыслу, а не по совпадению слов. Он живёт рядом со строками, которые описывает: одна резервная копия, один контур доступа, одна семантика удаления. Разнеси их по разным службам — и однажды удалённая запись останется в поиске.

Агентный RAG

Граф связей: хранит не куски текста, а то, как сущности связаны между собой. Отвечает на вопросы, у которых нет одного источника ответа. Включается переключателем, собственного интерфейса не имеет намеренно — с ним разговаривают не глазами, а вопросами.

Проверить память можно, ничего не программируя: Telegram-бот отвечает вопросами к графу знаний — вы пишете вопрос, он отвечает из загруженных документов, а если база пуста, честно говорит, что отвечать ему не из чего. Голосовое сообщение он расшифровывает сам.

Каналы связи

Глубоко встроен пока один канал — Telegram. «Глубоко» здесь значит не «умеет отправлять сообщения», а двустороннюю связь с проектом: входящие складываются в общий ящик, файлы принимаются, голос расшифровывается, ответ приходит из памяти проекта. Служба одна и читает бота одна: у Telegram сообщение достаётся ровно одному читателю, и второй опрашивающий молча съедал бы половину переписки.

Следующий канал — почта, мессенджер, виджет на сайте — добавляется разработчиком как ещё одна запись в той же службе, а не как вторая служба. При этом собственные каналы связи внутри самого приложения архитектор строит сам: платформа нужна там, где канал обязан быть общим для всего сервера.

Карта

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

Особенность в том, где это считается: картографические движки работают на вашем же сервере, а не в чужом облаке. Отсюда два следствия — у запросов нет поштучного счёта, и адреса ваших клиентов не уезжают на сторону, чтобы вернуться расстоянием.

Панель управления

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

Резервное копирование

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

Развёртывание и ошибки

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

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