Initial commit

docs/devtools/module-generator/troubleshooting.md

@@ -0,0 +1,122 @@
+# Module Generator Troubleshooting
+
+## Generated Files Exist but the Module Is Not Loaded
+
+Docker file watching does not always restart the backend or rebuild the admin module registry after the generator creates new directories. Existing file changes may be detected while newly generated module files are not.
+
+Restart both application services manually from the repository root:
+
+```bash
+docker compose restart
+```
+
+Then reload the admin app. If the module still is not loaded, inspect service logs:
+
+```bash
+docker compose logs --tail=200 backend admin
+```
+
+Check for TypeScript errors, invalid generated imports, route-loading failures, or module-manifest errors. If the containers are not running through Compose, restart the corresponding backend and admin development processes manually.
+
+The restart is necessary because:
+
+- the backend discovers generated route files under `backend/modules/` during startup;
+- the admin app discovers `apps/admin/src/modules/**/config/module.ts` through Vite's module registry;
+- adding an entirely new directory may not trigger the same reload behavior as editing an existing file.
+
+## Module Loads but Is Missing from the Menu
+
+If generation succeeded and both services restarted, a missing menu item usually indicates a permission mismatch or an invalid menu/module configuration.
+
+### 1. Compare permission slugs
+
+Check the generated backend permissions:
+
+```txt
+backend/modules/<ModuleName>/config/permissions.ts
+```
+
+Check the frontend permission constants:
+
+```txt
+apps/admin/src/modules/<name>/config/meta.ts
+```
+
+The view slug must match exactly. For example:
+
+```ts
+// backend permissions.ts
+{ slug: 'products.view', name: 'Product view' }
+
+// frontend meta.ts
+export const MODULE_PERMISSION_VIEW = 'products.view';
+```
+
+Also compare the create, update, and delete slugs. Module-name pluralization is generated heuristically, so names that are already plural or have irregular plurals require manual correction.
+
+### 2. Verify the current role owns the permission
+
+The menu filters items using `MODULE_PERMISSION_VIEW`. Confirm that:
+
+- the generated permission is available to the access-control system;
+- the current admin role has the generated view permission;
+- the role-to-permission assignment uses the same exact slug;
+- the session or permission data has been refreshed after changing the role.
+
+### 3. Check menu configuration
+
+Inspect:
+
+```txt
+apps/admin/src/modules/<name>/config/menu.ts
+```
+
+Confirm that:
+
+- the exported menu factory is valid;
+- `path` uses `MODULE_ROOT_PATH`;
+- `permissions` contains `MODULE_PERMISSION_VIEW`;
+- the file is not empty;
+- the configured route exists.
+
+The generator creates the menu content with the Datatable frontend asset. If Datatable was not selected, add a menu implementation manually or keep the module intentionally hidden from navigation.
+
+### 4. Check the module manifest
+
+Inspect:
+
+```txt
+apps/admin/src/modules/<name>/config/module.ts
+```
+
+The manifest must export a valid `AppModuleConfig`, must not set `enabled: false`, and must expose the intended `menu`, `routes`, and `messages` values. Its module ID should be unique.
+
+### 5. Check route configuration
+
+Inspect:
+
+```txt
+apps/admin/src/modules/<name>/config/routing.tsx
+```
+
+Confirm that `MODULE_ROOT_PATH`, the menu path, and the generated route all point to the same URL. A visible menu item with a broken route and an invisible menu item are separate problems; verify both configuration files.
+
+## Final Checks
+
+Run both builds to expose generated TypeScript or import errors:
+
+```bash
+npm run build:backend
+npm run build:admin
+```
+
+Then verify:
+
+1. `backend/modules/<ModuleName>/` exists and contains the selected backend assets.
+2. `apps/admin/src/modules/<name>/` exists and contains a valid module manifest.
+3. Docker services or local development processes were restarted.
+4. Backend and frontend permission slugs match.
+5. The current role owns the view permission.
+6. The menu path matches the frontend route.
+
+If all checks pass, review the backend and admin logs during startup. Module discovery errors are normally reported there.