@appxdigital/appx-core 0.1.122 → 0.1.123

package/dist/config/generate-resolvers.js

@@ -23,10 +23,9 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-const fs = __importStar(require("fs"));
+exports.scaffoldResolver = void 0;
 const path = __importStar(require("path"));
 const utils_1 = require("./utils");
-const modelsPath = path.join(process.cwd(), 'src/generated');
 const outputPath = path.join(process.cwd(), 'src/modules');
 /**
  * Generic resolver template for a given model
@@ -68,20 +67,14 @@ export class ${model}Resolver extends ${model}GenericResolver {
 }
 `;
 /**
- * Generate resolvers for each model
+ * Scaffold the (read-only) GraphQL resolver file for a single model (once;
+ * never overwritten). Imports the prisma-nestjs-graphql artifacts under
+ * `src/generated/<folder>/`, so the deploy-safe pass (`prisma generate`) must
+ * have produced them first.
  */
-fs.readdirSync(modelsPath).forEach((folder) => {
-    if (utils_1.IGNORE_FOLDERS.includes(folder))
-        return;
-    const modelName = (0, utils_1.kebabToPascalCase)(folder);
-    const modelOutputPath = path.join(outputPath, folder);
-    if (!fs.existsSync(modelOutputPath)) {
-        fs.mkdirSync(modelOutputPath, { recursive: true });
-        console.log(`Folder for model ${modelName} created.`);
-    }
-    else {
-        console.log(`Folder for model ${modelName} already exists, skipping creation.`);
-    }
-    const resolverPath = path.join(modelOutputPath, `${folder}.resolver.ts`);
+function scaffoldResolver(modelName) {
+    const folder = (0, utils_1.modelFolder)(modelName);
+    const resolverPath = path.join(outputPath, folder, `${folder}.resolver.ts`);
     (0, utils_1.createFileIfNotExists)(resolverPath, genericResolverTemplate(modelName, folder));
-});
+}
+exports.scaffoldResolver = scaffoldResolver;

package/dist/config/generate-services.d.ts

@@ -1,2 +1,3 @@
-export {};
+/** Scaffold the service file for a single model (once; never overwritten). */
+export declare function scaffoldService(modelName: string): void;
 //# sourceMappingURL=generate-services.d.ts.map

package/dist/config/generate-services.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-services.d.ts","sourceRoot":"","sources":["../../src/config/generate-services.ts"],"names":[],"mappings":""}
+{"version":3,"file":"generate-services.d.ts","sourceRoot":"","sources":["../../src/config/generate-services.ts"],"names":[],"mappings":"AAwBA,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAIvD"}

package/dist/config/generate-services.js

@@ -23,10 +23,9 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-const fs = __importStar(require("fs"));
+exports.scaffoldService = void 0;
 const path = __importStar(require("path"));
 const utils_1 = require("./utils");
-const modelsPath = path.join(process.cwd(), 'src/generated');
 const servicesOutputPath = path.join(process.cwd(), 'src/modules');
 /**
  * Generic service template for a given model
@@ -45,18 +44,10 @@ export class ${model}Service extends CoreService<${model}> {
   // Override methods or add custom logic as needed
 }
 `;
-/**
- * Generate services for each model
- */
-fs.readdirSync(modelsPath).forEach((folder) => {
-    if (utils_1.IGNORE_FOLDERS.includes(folder))
-        return;
-    const modelName = (0, utils_1.kebabToPascalCase)(folder);
-    const modelOutputPath = path.join(servicesOutputPath, folder);
-    if (!fs.existsSync(modelOutputPath)) {
-        fs.mkdirSync(modelOutputPath, { recursive: true });
-        console.log(`Folder for model ${modelName} created.`);
-    }
-    const servicePath = path.join(modelOutputPath, `${folder}.service.ts`);
+/** Scaffold the service file for a single model (once; never overwritten). */
+function scaffoldService(modelName) {
+    const folder = (0, utils_1.modelFolder)(modelName);
+    const servicePath = path.join(servicesOutputPath, folder, `${folder}.service.ts`);
     (0, utils_1.createFileIfNotExists)(servicePath, genericServiceTemplate(modelName));
-});
+}
+exports.scaffoldService = scaffoldService;

package/dist/config/utils.d.ts

@@ -14,5 +14,42 @@ export declare const GENERATED_BANNER: string;
  * directories as needed.
  */
 export declare const writeGeneratedFile: (filePath: string, content: string) => void;
-export declare const IGNORE_FOLDERS: string[];
+/**
+ * Framework-owned models. Excluded from model discovery: no generic CRUD module,
+ * controller, service, resolver, or DTO is scaffolded for them. `Session` /
+ * `UserRefreshToken` are framework plumbing; `User` is owned by the auth module
+ * (generic User CRUD would be a mass-assignment surface, and `/auth/*` already
+ * covers user endpoints), so it is hidden from the module wizard entirely.
+ */
+export declare const FRAMEWORK_MODELS: string[];
+/**
+ * The kebab-case folder / file basename for a model. Matches the folder naming
+ * of the prisma-nestjs-graphql generator output under `src/generated/`, so the
+ * scaffolded resolver's imports (`../../generated/<folder>/<folder>.model`)
+ * resolve. E.g. `ProjectMember` -> `project-member`, `TypeSample` -> `type-sample`.
+ */
+export declare const modelFolder: (modelName: string) => string;
+/**
+ * Loads the datamodel from the consumer project's generated Prisma client and
+ * returns the discoverable (non-framework-owned) models. This is the single
+ * source of truth for "what models exist" — independent of whatever folders the
+ * GraphQL plugin happened to emit. Requires `@prisma/client` lazily so callers
+ * can run `prisma generate` first and pick up a fresh schema in the same process.
+ */
+export declare const loadAllModels: () => any[];
+export declare const loadModels: () => any[];
+/** True if a module exists at the model's canonical folder under src/modules. */
+export declare const moduleExists: (modelName: string) => boolean;
+/**
+ * The set of model names already served by existing module source — detected by
+ * the `CoreController<Model>` / `CoreService<Model>` type argument. Pure (takes
+ * file contents) so it is unit-testable. This catches a module that serves a
+ * model under a NON-canonical folder name (e.g. a hand-written pluralised
+ * `wearable-connections/` module owning the `WearableConnection` model), which a
+ * folder-name check (`moduleExists`) would miss — preventing the wizard from
+ * scaffolding a duplicate module + controller on a second route.
+ */
+export declare const modelsServedBySource: (contents: string[]) => Set<string>;
+/** Scans src/modules for the models already served by an existing module. */
+export declare const ownedModels: () => Set<string>;
 //# sourceMappingURL=utils.d.ts.map

package/dist/config/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/config/utils.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,iBAAiB,QAAS,MAAM,WAK5C,CAAC;AAEF,eAAO,MAAM,iBAAiB,QAAS,MAAM,WAK5C,CAAC;AAEF,eAAO,MAAM,qBAAqB,aAAc,MAAM,WAAW,MAAM,SAStE,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,QAGoD,CAAC;AAElF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,aAAc,MAAM,WAAW,MAAM,SAInE,CAAC;AAEF,eAAO,MAAM,cAAc,UAS1B,CAAC"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/config/utils.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,iBAAiB,QAAS,MAAM,WAK5C,CAAC;AAEF,eAAO,MAAM,iBAAiB,QAAS,MAAM,WAK5C,CAAC;AAEF,eAAO,MAAM,qBAAqB,aAAc,MAAM,WAAW,MAAM,SAStE,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,QAGoD,CAAC;AAElF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,aAAc,MAAM,WAAW,MAAM,SAInE,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,UAA0C,CAAC;AAExE;;;;;GAKG;AACH,eAAO,MAAM,WAAW,cAAe,MAAM,KAAG,MAAsC,CAAC;AAEvF;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,QAAO,GAAG,EAInC,CAAC;AAEF,eAAO,MAAM,UAAU,QAAO,GAAG,EAAuE,CAAC;AAEzG,iFAAiF;AACjF,eAAO,MAAM,YAAY,cAAe,MAAM,KAAG,OAGhD,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,aAAc,MAAM,EAAE,KAAG,IAAI,MAAM,CAQnE,CAAC;AAEF,6EAA6E;AAC7E,eAAO,MAAM,WAAW,QAAO,IAAI,MAAM,CAYxC,CAAC"}

package/dist/config/utils.js

@@ -23,7 +23,7 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.IGNORE_FOLDERS = exports.writeGeneratedFile = exports.GENERATED_BANNER = exports.createFileIfNotExists = exports.pascalToKebabCase = exports.kebabToPascalCase = void 0;
+exports.ownedModels = exports.modelsServedBySource = exports.moduleExists = exports.loadModels = exports.loadAllModels = exports.modelFolder = exports.FRAMEWORK_MODELS = exports.writeGeneratedFile = exports.GENERATED_BANNER = exports.createFileIfNotExists = exports.pascalToKebabCase = exports.kebabToPascalCase = void 0;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const kebabToPascalCase = (str) => {
@@ -72,13 +72,78 @@ const writeGeneratedFile = (filePath, content) => {
     console.log(`Generated ${filePath}`);
 };
 exports.writeGeneratedFile = writeGeneratedFile;
-exports.IGNORE_FOLDERS = [
-    'prisma',
-    'schema.gql',
-    'session',
-    'user-refresh-token',
-    // Generated DTOs live under src/generated/dto/. The model generators scan
-    // src/generated's top-level dirs as model names, so this must be skipped or
-    // they emit a bogus `dto` module.
-    'dto',
-];
+/**
+ * Framework-owned models. Excluded from model discovery: no generic CRUD module,
+ * controller, service, resolver, or DTO is scaffolded for them. `Session` /
+ * `UserRefreshToken` are framework plumbing; `User` is owned by the auth module
+ * (generic User CRUD would be a mass-assignment surface, and `/auth/*` already
+ * covers user endpoints), so it is hidden from the module wizard entirely.
+ */
+exports.FRAMEWORK_MODELS = ['Session', 'UserRefreshToken', 'User'];
+/**
+ * The kebab-case folder / file basename for a model. Matches the folder naming
+ * of the prisma-nestjs-graphql generator output under `src/generated/`, so the
+ * scaffolded resolver's imports (`../../generated/<folder>/<folder>.model`)
+ * resolve. E.g. `ProjectMember` -> `project-member`, `TypeSample` -> `type-sample`.
+ */
+const modelFolder = (modelName) => (0, exports.pascalToKebabCase)(modelName);
+exports.modelFolder = modelFolder;
+/**
+ * Loads the datamodel from the consumer project's generated Prisma client and
+ * returns the discoverable (non-framework-owned) models. This is the single
+ * source of truth for "what models exist" — independent of whatever folders the
+ * GraphQL plugin happened to emit. Requires `@prisma/client` lazily so callers
+ * can run `prisma generate` first and pick up a fresh schema in the same process.
+ */
+const loadAllModels = () => {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { Prisma } = require(path.join(process.cwd(), 'node_modules', '@prisma/client'));
+    return Prisma.dmmf.datamodel.models;
+};
+exports.loadAllModels = loadAllModels;
+const loadModels = () => (0, exports.loadAllModels)().filter((m) => !exports.FRAMEWORK_MODELS.includes(m.name));
+exports.loadModels = loadModels;
+/** True if a module exists at the model's canonical folder under src/modules. */
+const moduleExists = (modelName) => {
+    const folder = (0, exports.modelFolder)(modelName);
+    return fs.existsSync(path.join(process.cwd(), 'src/modules', folder, `${folder}.module.ts`));
+};
+exports.moduleExists = moduleExists;
+/**
+ * The set of model names already served by existing module source — detected by
+ * the `CoreController<Model>` / `CoreService<Model>` type argument. Pure (takes
+ * file contents) so it is unit-testable. This catches a module that serves a
+ * model under a NON-canonical folder name (e.g. a hand-written pluralised
+ * `wearable-connections/` module owning the `WearableConnection` model), which a
+ * folder-name check (`moduleExists`) would miss — preventing the wizard from
+ * scaffolding a duplicate module + controller on a second route.
+ */
+const modelsServedBySource = (contents) => {
+    const owned = new Set();
+    const re = /Core(?:Controller|Service)<\s*([A-Za-z0-9_]+)\s*>/g;
+    for (const content of contents) {
+        let m;
+        while ((m = re.exec(content)) !== null)
+            owned.add(m[1]);
+    }
+    return owned;
+};
+exports.modelsServedBySource = modelsServedBySource;
+/** Scans src/modules for the models already served by an existing module. */
+const ownedModels = () => {
+    const root = path.join(process.cwd(), 'src/modules');
+    if (!fs.existsSync(root))
+        return new Set();
+    const contents = [];
+    for (const dir of fs.readdirSync(root)) {
+        const dirPath = path.join(root, dir);
+        if (!fs.statSync(dirPath).isDirectory())
+            continue;
+        for (const file of fs.readdirSync(dirPath)) {
+            if (file.endsWith('.ts'))
+                contents.push(fs.readFileSync(path.join(dirPath, file), 'utf8'));
+        }
+    }
+    return (0, exports.modelsServedBySource)(contents);
+};
+exports.ownedModels = ownedModels;

package/dist/index.d.ts

@@ -23,6 +23,7 @@ export * from './common/guards/rbac.guard';
 export * from './common/guards/user-population.guard';
 export * from './modules/common.module';
 export * from './common/interceptors/prisma.interceptor';
+export * from './common/decorators/scalar-field.decorator';
 export * from './common/config/permissionsConfigTypes';
 export * from './common/config/adminConfigType';
 export * from './common/config/permissions.config.provider';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iCAAiC,CAAC;AAChD,cAAc,4BAA4B,CAAC;AAI3C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,qCAAqC,CAAC;AACpD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,iCAAiC,CAAC;AAChD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uCAAuC,CAAC;AACtD,cAAc,oCAAoC,CAAC;AACnD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,2CAA2C,CAAC;AAC1D,cAAc,sCAAsC,CAAC;AACrD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uCAAuC,CAAC;AACtD,cAAc,yBAAyB,CAAC;AACxC,cAAc,0CAA0C,CAAC;AACzD,cAAc,wCAAwC,CAAC;AACvD,cAAc,iCAAiC,CAAC;AAChD,cAAc,6CAA6C,CAAC;AAC5D,cAAc,oBAAoB,CAAC;AACnC,cAAc,mCAAmC,CAAC;AAClD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,wCAAwC,CAAC;AACvD,cAAc,+CAA+C,CAAC;AAC9D,cAAc,uCAAuC,CAAC;AACtD,cAAc,oCAAoC,CAAC;AACnD,cAAc,0CAA0C,CAAC;AACzD,cAAc,oCAAoC,CAAC;AACnD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wCAAwC,CAAC;AACvD,cAAc,oCAAoC,CAAC;AACnD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qCAAqC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iCAAiC,CAAC;AAChD,cAAc,4BAA4B,CAAC;AAI3C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,qCAAqC,CAAC;AACpD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,iCAAiC,CAAC;AAChD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uCAAuC,CAAC;AACtD,cAAc,oCAAoC,CAAC;AACnD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,2CAA2C,CAAC;AAC1D,cAAc,sCAAsC,CAAC;AACrD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uCAAuC,CAAC;AACtD,cAAc,yBAAyB,CAAC;AACxC,cAAc,0CAA0C,CAAC;AACzD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,wCAAwC,CAAC;AACvD,cAAc,iCAAiC,CAAC;AAChD,cAAc,6CAA6C,CAAC;AAC5D,cAAc,oBAAoB,CAAC;AACnC,cAAc,mCAAmC,CAAC;AAClD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,wCAAwC,CAAC;AACvD,cAAc,+CAA+C,CAAC;AAC9D,cAAc,uCAAuC,CAAC;AACtD,cAAc,oCAAoC,CAAC;AACnD,cAAc,0CAA0C,CAAC;AACzD,cAAc,oCAAoC,CAAC;AACnD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wCAAwC,CAAC;AACvD,cAAc,oCAAoC,CAAC;AACnD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qCAAqC,CAAC"}

package/dist/index.js

@@ -42,6 +42,7 @@ __exportStar(require("./common/guards/rbac.guard"), exports);
 __exportStar(require("./common/guards/user-population.guard"), exports);
 __exportStar(require("./modules/common.module"), exports);
 __exportStar(require("./common/interceptors/prisma.interceptor"), exports);
+__exportStar(require("./common/decorators/scalar-field.decorator"), exports);
 __exportStar(require("./common/config/permissionsConfigTypes"), exports);
 __exportStar(require("./common/config/adminConfigType"), exports);
 __exportStar(require("./common/config/permissions.config.provider"), exports);

package/docs/README.md

@@ -4,6 +4,7 @@ Authoritative usage documentation for `@appxdigital/appx-core`. **This folder is
 
 ## Contents
 
+- **[generate.md](./generate.md)** — the two code-generation commands: `generate` (deploy-safe — regenerates `src/generated/**` only, no code mutation) and `generate models` (the wizard that scaffolds + registers CRUD modules for chosen models). When to use each, and why not every table needs a module.
 - **[permissions.md](./permissions.md)** — the authorization model: the `@Permission` and `@ExposeModels` decorators, the `permissions.config.ts` shape, roles/actions, row-level `conditions`, field-level control, action fallbacks, and the `GUEST` (unauthenticated) flow.
 - **[dtos.md](./dtos.md)** — the generated CRUD validation DTOs: their two-file structure, **how to remove a field** (`OmitType` / `@NoWrite`), how to add validation, and why nested relation writes don't belong on generic CRUD.
 - **[data-access.md](./data-access.md)** — how you talk to the database: the Prisma proxy (`prisma.model.*`), how ABAC filtering and field omission are enforced on every call, the redirected single-record methods, relation behaviour, bypass hatches, and transactions.

package/docs/dtos.md

@@ -34,7 +34,19 @@ A scalar field is **included** unless it is:
 - annotated `/// @NoWrite`,
 - annotated `/// @Role(none)`.
 
-**Relation navigation fields are excluded**; their scalar foreign keys are kept. Types map to validators: enums → `@IsEnum`, scalars → `@IsString`/`@IsInt`/`@IsBoolean`/`@IsNumber`/`@IsDateString`, `Json`/`Bytes` → `@Allow()`.
+**Relation navigation fields are excluded**; their scalar foreign keys are kept. Each field is typed to match its **Prisma model type** so a controller override type-checks, and validated accordingly:
+
+| Prisma type | DTO type | Decorator | Wire input |
+|---|---|---|---|
+| `String` / enum | `string` / enum | `@IsString` / `@IsEnum` | string |
+| `Int` / `Float` | `number` | `@IsInt` / `@IsNumber` | number |
+| `Boolean` | `boolean` | `@IsBoolean` | boolean |
+| `DateTime` | `Date` | `@Type(() => Date)` | ISO-8601 string |
+| `Decimal` | `Prisma.Decimal` | `@DecimalField()` | string **or** number |
+| `BigInt` | `bigint` | `@BigIntField()` | string **or** number |
+| `Json` / `Bytes` | `any` | `@Allow()` | any |
+
+`@DecimalField()` / `@BigIntField()` accept a string or number and coerce/validate it (invalid → `400`); prefer strings for `Decimal` (money) and large `BigInt` values to avoid JSON float-precision loss. A `BigInt` column serialises as a **string** in JSON responses (JSON has no bigint). A `Decimal` column with the GraphQL generator requires the `prisma-graphql-type-decimal` peer dependency (npm auto-installs it).
 
 > Because relations are excluded, generic CRUD endpoints accept **flat** writes (scalars + FK ids), not nested relation writes. See [Relations & nested writes](#relations--nested-writes) below.
 

package/docs/generate.md

@@ -0,0 +1,57 @@
+# Code generation — `generate` and `generate models`
+
+AppX Core generates code from your Prisma schema through **two commands with different responsibilities**. The split exists so that keeping generated types in sync (safe to automate) is separate from scaffolding CRUD modules (which writes code you own and edits `app.module.ts`).
+
+| Command | What it does | Writes | Safe in CI? |
+|---|---|---|---|
+| `appx-core generate` | Regenerate the Prisma client, GraphQL types, and DTO **base** classes | `src/generated/**` only (gitignored) | **Yes** — idempotent, no code mutation |
+| `appx-core generate models` | Scaffold + register CRUD modules for chosen models | `src/modules/**` and `src/app.module.ts` | No — run during development |
+
+## `appx-core generate` — the deploy-safe pass
+
+```bash
+appx-core generate
+```
+
+Runs `prisma generate` (which emits both the Prisma client and the prisma-nestjs-graphql artifacts) and regenerates the DTO base classes under `src/generated/dto/**`. It **never** writes `src/modules/**` and **never** edits `src/app.module.ts`, so it is safe to run in CI, a `postinstall`, or a predeploy step, and safe to re-run any number of times.
+
+Run it **every time you change the Prisma schema** — it refreshes the client, GraphQL types, and DTO bases in one step (no separate `prisma generate` needed). Because everything it writes lives under the gitignored `src/generated/`, it never produces a diff in your committed code.
+
+## `appx-core generate models` — the module wizard
+
+```bash
+appx-core generate models            # interactive picker
+appx-core generate models Habit Log  # named models (Pascal or kebab)
+appx-core generate models --all      # every generatable model
+```
+
+For each selected model it scaffolds the hand-owned files — module, service, controller, resolver, and the DTO subclass — **once** (never overwriting your edits), registers the module in `app.module.ts`, and then runs the deploy-safe pass so the new imports resolve.
+
+The interactive picker lists **only models that don't already have a module**. If there are none, it prints `No modules available to generate`.
+
+### You don't need a module for every table
+
+Generated CRUD supports **permission-gated nested writes** (`create` / `connect`), so you can expose a parent resource and write related rows through it. Scaffold modules only for the resources you actually serve over HTTP/GraphQL — not mechanically for every table.
+
+### `User` is framework-owned
+
+The `User` model is never scaffolded. Authentication already serves user endpoints under `/auth/*`, and a generic `POST/PUT /users` CRUD is a mass-assignment surface. If you genuinely need generic user CRUD, write it by hand — but prefer a dedicated, permission-scoped endpoint.
+
+### Ownership is by model, not folder name
+
+Whether a model "already has a module" is determined by the model it serves (`CoreController<Model>` / `CoreService<Model>`), not by a folder-name convention. So a hand-written module under a non-canonical folder (e.g. a pluralised `wearable-connections/` serving `WearableConnection`) is recognised, and the wizard will **not** scaffold a duplicate.
+
+## Typical workflow
+
+```bash
+# 1. Edit prisma/schema.prisma, then:
+npx prisma migrate dev        # apply the schema change
+appx-core generate            # refresh client / GraphQL / DTO bases (safe)
+appx-core generate models     # expose the new table(s) as CRUD (pick them)
+```
+
+In CI / deploy, run **only** `appx-core generate` — it will never touch your committed code.
+
+## GraphQL
+
+Scaffolded modules include a **read-only** GraphQL resolver (query + aggregate; no mutations). See [graphql.md](./graphql.md). Per-module GraphQL toggling is planned for a later release.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@appxdigital/appx-core",
-    "version": "0.1.122",
+    "version": "0.1.123",
     "description": "Appx Core is a library that provides a set of tools to help you build your application faster.",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
@@ -46,6 +46,7 @@
         "helmet": "^8.3.0",
         "jest": "^29.7.0",
         "prettier": "^3.8.3",
+        "prisma-graphql-type-decimal": "^3.0.0",
         "rimraf": "^6.1.2",
         "supertest": "^7.2.2",
         "testcontainers": "^10.28.0",
@@ -94,6 +95,7 @@
         "passport-local": "~1.0.0",
         "prisma": "~6.5.0",
         "prisma-case-format": "~2.2.1",
+        "prisma-graphql-type-decimal": "^3.0.0",
         "prisma-nestjs-graphql": "21.1.1",
         "reflect-metadata": "~0.2.0",
         "rxjs": "~7.8.1"