Архитектура · 0.8.1

Структура проекта

Модель, backend, admin и API-контракт.

На этой странице

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; файлы и изображения имеют отдельные хранилища.