# 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](./frontend.md) (UI, payload builders, generated frontend), [backend.md](./backend.md) (endpoints, inspection, templates, generated backend), [troubleshooting.md](./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

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

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](../../../architecture/react-frontend/Readme.md); review backend modules against the [backend architecture](../../../architecture/backend/Readme.md).