ENTITY_NAME обозначает каталог или имя файла вашей сущности; EntityName — её сгенерированный тип или часть имени экспорта в коде. Подставляйте фактические имена из проекта. FIELD_NAME — имя поля. Это обозначения, а не обязательные сущности или файлы.
В .admingen/project.yaml описаны сущности и настройки приложения. Generator UI изменяет эту модель, а Generate обновляет по ней backend, систему администрирования, OpenAPI и миграции схемы.
В дереве показан проект с сущностью EntityName. У backend и admin отдельные зависимости и сборка. Публичный сайт разрабатывается отдельно и обращается к API как клиент.
Дерево показывает основные пути на примере EntityName, а не полный список файлов. Набор файлов зависит от модели и возможностей проекта.
Корень твоего проекта
project/
├── .admingen/
│ └── project.yaml # декларативная модель
├── backend/
│ ├── cmd/ # точки входа Go
│ │ ├── api/main.go
│ │ └── migrate/main.go
│ ├── internal/ # пакеты приложения
│ │ ├── domain/
│ │ │ └── ENTITY_NAME.go
│ │ ├── app/ENTITY_NAME/
│ │ │ ├── commands.go
│ │ │ ├── queries.go
│ │ │ └── service.go
│ │ ├── adapters/
│ │ │ ├── http/generated/ENTITY_NAME_handler.go
│ │ │ └── postgres/generated/ENTITY_NAME_repository.go
│ │ ├── infrastructure/
│ │ │ ├── database/database.go
│ │ │ └── migrations/migrations.go
│ │ ├── generated/
│ │ │ ├── bootstrap/app.go
│ │ │ └── customcontracts/composition.go
│ │ └── custom/
│ │ ├── app/composition.go
│ │ └── ENTITY_NAME/hooks.go
│ ├── migrations/ # история изменений схемы
│ │ ├── manifest.json
│ │ └── custom/
│ ├── openapi/ # HTTP-контракт
│ │ ├── openapi.yaml
│ │ └── entities/ENTITY_NAME.yaml
│ └── go.mod
└── admin/
├── src/ # React + TypeScript
│ ├── main.tsx
│ ├── app/
│ │ ├── router.tsx
│ │ └── providers.tsx
│ ├── features/ENTITY_NAME/
│ │ ├── generated/
│ │ │ ├── model.ts
│ │ │ ├── form.tsx
│ │ │ ├── list-page.tsx
│ │ │ └── ui-extension.tsx
│ │ └── custom/
│ │ ├── extension.tsx
│ │ └── ui-extension.tsx
│ └── shared/
│ ├── api/client.ts
│ └── forms/field-controls.tsx
├── custom/vite.ts # настройки сборки проекта
└── package.json
Твои доработки размещаются в custom-зонах. Набор остальных файлов зависит от включённых возможностей: например, media и Docker/deployment появляются по настройкам проекта. Сохранение модели, генерация файлов и применение миграций выполняются отдельно.
Декларативная модель
.admingen/project.yaml хранит описание сущностей, полей, связей, доступа и настроек генерации. В нём указано, что должно быть в приложении. Основной способ редактирования — Generator UI; те же изменения можно вносить через CLI. Generate читает модель и строит код. Обратного восстановления модели из исходников приложения нет.
Точки входа Go
В backend/cmd/ находятся исполняемые программы проекта. Например, cmd/api/main.go запускает сборку зависимостей и HTTP-сервер. Благодаря отдельным точкам входа API и служебные команды запускаются независимо.
Пакеты приложения
В backend/internal/ находятся типы сущностей, прикладные сервисы, HTTP/SQL-адаптеры и технические механизмы. Custom-расширения тоже размещены здесь. При этом назначение пакета и право изменять его файлы — разные вещи: направление зависимостей и правила генерации разобраны ниже.
История изменений схемы
В backend/migrations/ хранятся SQL-миграции и их реестр. Generate добавляет новые шаги изменения схемы. Чтобы выполнить их в БД, нужно отдельно запустить мигратор. Уже выпущенная история сохраняется: изменение модели не переписывает прежние миграции.
HTTP-контракт
В backend/openapi/ описаны маршруты API, параметры, тела запросов и ответы. Этот контракт позволяет разработчику сайта или другого клиента подключиться к приложению без изучения внутренних Go-пакетов.
React + TypeScript
В admin/src/ находится система администрирования: маршрутизация, списки, формы и общие элементы управления. Стандартные части обновляются из модели. Рядом с ними, в custom-зонах сущностей, находятся твои компоненты и расширения.
Настройки сборки проекта
Через admin/custom/vite.ts можно дополнить конфигурацию Vite под задачи приложения. Генератор создаёт стартовый файл, только если его ещё нет. После этого файл принадлежит вам, и дальнейший Generate сохраняет внесённые настройки.
Практические руководства
Описание папок в Demo
При включённом Demo генератор добавляет русские ADMINGEN.md в описываемые каталоги. Они объясняют назначение файлов и путь выполнения; это справочные файлы проекта. Общую модель меняйте через UI, а custom-логику — в принадлежащих вашей команде файлах. Собственный дашборд находится в admin/src/app/custom/dashboard.tsx; файлы и изображения имеют отдельные хранилища.