# Module Generator Troubleshooting

## Generated Files Exist but the Module Is Not Loaded

Docker file watching does not reliably pick up entirely new directories: the backend discovers `apps/backend/modules/` routes at startup, and the admin app discovers `apps/admin/src/modules/**/config/module.ts` through Vite's module registry. Restart both services and reload the admin app:

```bash
docker compose restart
```

Still not loaded? Check logs for TypeScript errors, invalid generated imports, route-loading or manifest errors:

```bash
docker compose logs --tail=200 backend admin
```

(Outside Compose, restart the backend and admin dev processes manually.)

## Module Loads but Is Missing from the Menu

Usually a permission mismatch or invalid menu/module configuration. Check in order:

1. **Permission slugs match exactly** — backend `apps/backend/modules/<ModuleName>/config/permissions.ts` (e.g. `{ slug: 'products.view' }`) vs frontend `apps/admin/src/modules/<name>/config/meta.ts` (`MODULE_PERMISSION_VIEW = 'products.view'`), for view/create/update/delete. Pluralization is heuristic — already-plural or irregular names need manual correction.
2. **The current role owns the view permission** — the menu filters on `MODULE_PERMISSION_VIEW`: the permission exists in access control, the role has it with the exact slug, and the session was refreshed after role changes.
3. **`config/menu.ts`** — valid exported menu factory, `path` uses `MODULE_ROOT_PATH`, `permissions` contains `MODULE_PERMISSION_VIEW`, the route exists. The menu is generated with the Datatable asset — without it, add a menu manually or keep the module hidden.
4. **`config/module.ts`** — exports a valid `AppModuleConfig`, unique module ID, not `enabled: false`, exposes `menu`, `routes`, `messages`.
5. **`config/routing.tsx`** — `MODULE_ROOT_PATH`, the menu path, and the generated route all point to the same URL (a broken route and an invisible menu item are separate problems).

## Final Checks

Run `npm run build:backend` and `npm run build:admin` to expose generated TypeScript or import errors, then verify: both module directories exist with the selected assets, services were restarted, slugs match, the role has the view permission, and the menu path matches the route. Module discovery errors are reported in backend and admin startup logs.