admin/docs/core/devtools/module-generator/Readme.md

Module Generator

Creates a backend module and a matching admin frontend module from an existing PostgreSQL table, combining database metadata with frontend code builders and Handlebars templates. The output is a maintainable starting point — generated authorization, validation, relationships, API behavior, labels, and translations must still be reviewed for the product domain.

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

Details: frontend.md (UI, payload builders, generated frontend), backend.md (endpoints, inspection, templates, generated backend), troubleshooting.md (module not loaded / missing from menu).

Prerequisites

1. Backend running from apps/backend/ (destinations resolve relative to process.cwd()); admin app in dev mode; authenticated session (all endpoints use auth middleware).
2. The source table created and migrated — the form reads PostgreSQL information_schema.
3. A module name valid as a TypeScript identifier, route segment, permission slug, and folder name.

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"]

Output goes to apps/backend/modules/<ModuleName>/, apps/backend/tests/modules/<ModuleName>/, and apps/admin/src/modules/<name>/. Frontend modules are discovered through their config/module.ts manifest; backend routes load from apps/backend/modules/ at startup.

Operational Behavior

• Generation writes directly into both workspaces — no preview, transaction, or rollback; existing files may be overwritten. Generate into a clean name and inspect the Git diff.
• Select model whenever you select api — API generation imports the model for its Swagger schema.
• The frontend template is always copied; form and datatable files are populated only when selected.
• Generated code is not formatted or committed automatically.

Verification Checklist

1. Inspect the Git diff; confirm route paths, API prefixes, permission slugs, and naming.
2. Review nullable fields, dates, passwords, foreign keys, validation, relationship names; replace generic labels and translations.
3. Verify list/create/update/delete, authorization, and validation-error behavior.
4. Run npm run build:backend and npm run build:admin; run the generated backend tests and add domain coverage.

Generated frontend follows the React frontend architecture; review backend modules against the backend architecture.