Initial commit

2026-06-25 15:53:49 +03:00
commit 1bb0b7e68a
1517 changed files with 218469 additions and 0 deletions
@@ -0,0 +1,78 @@
+# 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).