admin/docs/devtools/module-generator

Module Generator

The module generator creates a backend module and a matching admin frontend module from an existing PostgreSQL table. It combines database metadata with frontend code builders and Handlebars templates.

The generator is intended to produce a maintainable starting point. Generated authorization rules, validation, relationships, API behavior, labels, translations, and field controls must still be reviewed for the product domain.

Source Ownership

Part	Source
Generator page and form	apps/admin/src/devtools/
Copied frontend module template	apps/admin/src/modules/_template/
Generator HTTP endpoints	backend/start/routes.ts
Generator controller	backend/app/controllers/module_controller.ts
Database inspection	backend/app/services/database_inspector.ts
Backend Handlebars templates	backend/app/templates/backend/
Frontend Handlebars templates	backend/app/templates/frontend/

See frontend.md for the UI, payload builders, and generated frontend architecture. See backend.md for endpoints, database inspection, templates, and generated backend files. If generated files are not loaded or the module is missing from the menu, use the troubleshooting guide.

Prerequisites

1. Run the backend from the backend/ workspace. The controller resolves backend and frontend destinations relative to process.cwd().
2. Run the admin app with dev mode enabled so the devtools module is registered.
3. Authenticate in the admin app. All generator endpoints use authentication middleware.
4. Create and migrate the source database table before opening the generator. The form reads tables and columns from PostgreSQL information_schema.
5. Use a module name compatible with TypeScript identifiers, route segments, permission slugs, and folder names.

Generation Flow

flowchart LR
  A["Select table and assets"] --> B["Configure form and table"]
  B --> C["Frontend builders create source strings"]
  C --> D["POST /makeModule/generate"]
  D --> E["Inspect database metadata"]
  E --> F["Copy frontend _template"]
  E --> G["Render backend templates"]
  F --> H["Write configured frontend files"]
  G --> I["Write backend module and tests"]

The generator first copies the complete frontend template, then overwrites generated frontend files with the payload content and database-derived entity metadata. Backend files are rendered according to the selected assets.

Generated Locations

backend/modules/<ModuleName>/
backend/tests/modules/<ModuleName>/
apps/admin/src/modules/<name>/

Frontend modules are discovered automatically through their config/module.ts manifest. Backend module routes and API routes are loaded automatically from backend/modules/ during application startup.

Important Operational Behavior

• Generation writes directly into both workspaces; it does not provide a preview, transaction, or rollback.
• Existing destination files may be overwritten. Generate into a clean name and inspect the Git diff before keeping the result.
• File writes are synchronous, but schema inspection and Swagger model generation are asynchronous.
• API generation imports the generated model to build its Swagger schema. Select model when selecting api.
• The frontend module template is always copied. Frontend form and datatable files are populated only when those assets are selected.
• Generated code is not automatically formatted or committed.

Verification Checklist

After generating a module:

1. Inspect all generated files and the Git diff.
2. Confirm route paths, API prefixes, permission slugs, and module naming.
3. Review nullable fields, dates, passwords, foreign keys, validation, and relationship names.
4. Replace generic labels and translation values.
5. Verify list, create, update, delete, authorization, and validation-error behavior.
6. Run npm run build:backend and npm run build:admin from the repository root.
7. Run the generated backend tests and add domain-specific coverage.

For restart, module-discovery, permission, and menu problems, see Troubleshooting.

The generated frontend structure follows the React frontend architecture. Backend modules should be reviewed against the backend architecture.