79 lines
4.6 KiB
Markdown
79 lines
4.6 KiB
Markdown
# 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](./frontend.md) for the UI, payload builders, and generated frontend architecture. See [backend.md](./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](./troubleshooting.md).
|
|
|
|
## 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
|
|
|
|
```mermaid
|
|
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
|
|
|
|
```txt
|
|
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](./troubleshooting.md).
|
|
|
|
The generated frontend structure follows the [React frontend architecture](../../apps-architecture/react-frontend/Readme.md). Backend modules should be reviewed against the [backend architecture](../../apps-architecture/backend/Readme.md).
|