@servicelabsco/nestjs-utility-services 2.0.6 → 2.0.7

package/CODEBASE_REFERENCE.md

@@ -0,0 +1,568 @@
+# CODEBASE_REFERENCE.md
+
+**Single-source reference for `@servicelabsco/nestjs-utility-services`. Read this before scanning the repo.**
+
+This file catalogs every service, controller, entity, DTO, job, subscriber, library, middleware, exception, config, and env var with its path. If you need to know what's in this codebase, read this. If a section is wrong or stale because of changes you just made, update it here as part of the change.
+
+For higher-level architecture and conventions, see `CLAUDE.md`.
+
+---
+
+## Repo orientation
+
+- **Type**: Publishable npm library (`main: dist/index.js`); also runnable as standalone NestJS app (`main.ts`) and worker (`worker.ts`).
+- **Public API barrel** (`dist/index.js`): re-exports `auth`, `common`, `platformUtility`, `security`, `system`, `worker.service`.
+- **DI registration**: every module folder has `es6.classes.ts` aggregating its classes — register here or DI ignores them. The `slnu syncClassess` step in `commit.sh` regenerates these.
+- **Three TypeORM connections**: `default` (postgres write), `read` (postgres read replica), `mongodb`. Entity globs include `node_modules/@servicelabsco/**` so sibling packages contribute entities and migrations.
+- **Filename suffix rules**: `*.entity.ts` (postgres), `*.mentity.ts` (mongo), `*.subscriber.ts` (postgres), `*.mongo.subscriber.ts` (mongo), `*.spec.ts` (jest), `*.dto.ts` (DTO), `*.job.ts` (BullMQ job).
+
+---
+
+## Top-level `src/` files
+
+- `src/main.ts` — HTTP entrypoint. Bootstraps `AppModule`, sets up `express.json()`, `httpContext.middleware`, `helmet`, CORS (`cors.config`), `rateLimit` (`rate.limiter.config`), `compression`, `trust proxy=1`. Optional graceful shutdown via `SERVER_COOL_DOWN_PERIOD`. Optional Sentry init via `SENTRY_DSN` + global `SentryInterceptor`. Global `ValidationPipe({ whitelist: true, transform: true })`. Listens on `SERVER_PORT` or 4000.
+- `src/worker.ts` — Worker entrypoint. Same `AppModule`, no `listen()`, just `init()` + `enableShutdownHooks()`. Requires `BULL_QUEUE_WORKER=true` for `JobConsumer` to register.
+- `src/worker.service.ts` — `WorkerService` (OnModuleInit). Calls `MaintenanceService.disableQueueIfRequired()` before processing starts.
+- `src/app.module.ts` — Root module. Imports `TypeOrmModule.forRoot` x3 (write+read+mongo), `BullModule.forRoot(queueConfig)`, `ConfigModule.forRoot({ isGlobal: true })`, `TerminusModule`, and the five module folders. Registers controllers `AppController`, `AdminAuthController`, `MenuController`, `HealthCheckController`. Middleware chain: `Maintenance → JWT → BasicAuth` for all routes; `Restricted` for `api/*`; `Internal` for `internal/*`.
+- `src/app.controller.ts` — `AppController`. Routes: `GET /` (hello), `GET api/auth` (current user), `GET api/test` (current user), `GET un-set` (placeholder), `GET queue` (queue data), `GET queue/:id` (job details), `POST sets` (zip-service test). Constructor injects most platform services for ad-hoc testing.
+- `src/app.service.ts` — `AppService` placeholder.
+- `src/health.check.controller.ts` — `HealthCheckController` at `/health`. Routes: `GET /health` (full check: pg-master + pg-read + redis + filesystem), `GET /health/detailed` (full + nodeVersion/platform/uptime), `GET /health/quick` (master + redis + fs only), `GET /health/runtime-check` (validates `cron-parser v5` next-fire + `CacheService` set/get/delete round-trip). Uses `tmpDir = process.env.TMP_DIR || '/tmp'`. The runtime-check is what `yarn runtime-check` curls.
+
+---
+
+## `src/config/`
+
+| File | Purpose | Env vars |
+|---|---|---|
+| `cors.config.ts` | CORS for `app.enableCors()`: methods POST/GET/PUT/PATCH/DELETE/HEAD, `credentials: true`, `maxAge: 3600`, `origin: true` | — |
+| `entity.constants.ts` | Maps `<EntityName> → EntityClass` for all entities across auth/security/system/platformUtility (used by `PlatformUtility.setEntities`) | — |
+| `jwt.config.ts` | `JwtModule.register(jwtConfig)`: `secret`, `signOptions.expiresIn` | `JWT_SECRET`, `JWT_EXPIRY` |
+| `mongo.config.ts` | TypeORM mongo connection (`name: 'mongodb'`); entities `*.mentity.{ts,js}`, subscribers `*.mongo.subscriber.{ts,js}`; `synchronize: false`, logging on | `MONGO_URL`, `MONGO_DATABASE` |
+| `orm.config.ts` | DataSource for typeorm-cli (used by `yarn m:*` commands). Same shape as `typeorm.config.ts` | `PG_DB_HOST`, `PG_DB_PORT`, `PG_DB_USERNAME`, `PG_DB_PASSWORD`, `PG_DB_DATABASE`, `PG_DB_LOGGING` |
+| `platform.constants.ts` | Default-export `{ queue, entities, jobs, services, mails, whoColumns }`. **`whoColumns = ['id','created_at','updated_at','deleted_at','created_by','updated_by']`** — used by class mapper to strip audit cols | `BULL_QUEUE_NAME` |
+| `queue.config.ts` | `BullModule.forRoot()` connection URL | `REDIS_HOST`, `REDIS_PORT`, `REDIS_USERNAME`, `REDIS_PASSWORD` |
+| `rate.limiter.config.ts` | `express-rate-limit` window+max | `THROTTLE_WINDOW` (default 60000), `THROTTLE_RATE` (default 10000) |
+| `read.typeorm.config.ts` | TypeORM read replica (`name: 'read'`); pg type parsers for bigint/decimal | `PG_DB_READ_HOST`, `PG_DB_PORT`, `PG_DB_USERNAME`, `PG_DB_PASSWORD`, `PG_DB_DATABASE`, `PG_DB_LOGGING` |
+| `redis.config.ts` | Redis URL for `RedisModule.forRoot` (used by `PlatformUtilityModule`) | `REDIS_HOST`, `REDIS_PORT`, `REDIS_USERNAME`, `REDIS_PASSWORD` |
+| `role.mapping.ts` | `{ super_admin: 1, public: 2, internal: 3 }`. **User id `2` is logged in by `InternalMiddleware`.** | — |
+| `sentry.config.ts` | `Sentry.init` config: `dsn`, `includeLocalVariables: true`, `attachStacktrace: true` | `SENTRY_DSN` |
+| `source.hash.ts` | Map of `<sourceName> → md5 hash` (e.g. `scheduledEvent: 'c2b08dc02f...'`). Used by source-type lookups | — |
+| `typeorm.config.ts` | TypeORM postgres write (`name: 'default'`); SnakeNamingStrategy; `migrationsTableName: 'sys_migrations'`; entity glob includes `node_modules/@servicelabsco/**`; pg type parsers cast bigint→int and decimal→float | `PG_DB_HOST`, `PG_DB_PORT`, `PG_DB_USERNAME`, `PG_DB_PASSWORD`, `PG_DB_DATABASE`, `PG_DB_LOGGING` |
+
+### All env vars referenced in `src/`
+
+```
+APP_KEY  AUDIT_DISABLED  BULL_LOG_DISABLE  BULL_MAX_METRIC_POINTS_WEEKS
+BULL_QUEUE_COMPLETE_LIMIT  BULL_QUEUE_FAILURE_LIMIT  BULL_QUEUE_NAME
+BULL_QUEUE_WORKER  ENABLE_SQL_LOG  JWT_EXPIRY  JWT_SECRET
+MONGO_DATABASE  MONGO_URL  NOTIFICATION_DISABLED  PG_DB_DATABASE
+PG_DB_HOST  PG_DB_LOGGING  PG_DB_PASSWORD  PG_DB_PORT  PG_DB_READ_HOST
+PG_DB_USERNAME  REDIS_HOST  REDIS_PASSWORD  REDIS_PORT  REDIS_PREFIX
+REDIS_SLUG  REDIS_USERNAME  SENTRY_DSN  SERVER_COOL_DOWN_PERIOD
+SERVER_ENV  SERVER_PORT  SHOW_CONSOLE_LOGS  STORAGE_ENGINE
+THROTTLE_RATE  THROTTLE_WINDOW  TMP_DIR
+```
+
+`SERVER_COOL_DOWN_PERIOD` (truthy) toggles `enableShutdownHooks`. `BULL_QUEUE_WORKER=true` registers consumers. `SHOW_CONSOLE_LOGS` (comma-separated levels: `log,info,warn,error,debug`) gates `CustomLogger`. `STORAGE_ENGINE` selects `s3` vs `r2` in `UploadService`.
+
+---
+
+## `src/auth/`
+
+### Services (`src/auth/services/`)
+
+| File | Class | Key methods |
+|---|---|---|
+| `auth.service.ts` | `AuthService` | `getUserLoginInfo`, `getUserInfo`, `getUserObject`, `generateAuthJwtToken`, `signJwtToken`, `verifyJwtToken` |
+| `user.service.ts` | `UserService` | `findUserByEmail`, `createUser`, `validateUser`, `findOrCreate`, `setRolesCache` |
+| `access.service.ts` | `AccessService` | `getUser`, `validateRoleId`, `validateRoleIdentifier`, `hasRoleId`, `hasRoleIds`, `hasRoleIdentifiers`, `hasRoleAssignments`, `hasPermissionAssignments` |
+| `refresh.token.service.ts` | `RefreshTokenService` | `setRefreshToken`, `generateRefreshToken` |
+| `device.token.service.ts` | `DeviceTokenService` | `setDeviceToken`, `attachUserDevice`, `getDeviceIdentifier` |
+| `social.service.ts` | `SocialService` | `fbLogin`, `googleLogin` |
+| `es6.service.ts` | `Es6Service` | `alignServices`, `setServices` (registry locator by hash) |
+| `es6.jobs.service.ts` | `Es6JobsService` | `alignJobs`, `setJobs` (registry locator by hash) |
+
+### Controllers (`src/auth/controllers/`)
+
+| File | Class | Routes |
+|---|---|---|
+| `admin.auth.controller.ts` | `AdminAuthController` | `GET /user-auth`, `POST /user-auth/login`, `POST /user-auth/verify-token`, `POST /user-auth/refresh-token`, `POST /user-auth/attach-device`, `POST /user-auth/set-device-token` |
+| `user.controller.ts` | `UserController` | `POST /user` |
+| `social.controller.ts` | `SocialController` | `POST /social/fb`, `POST /social/google` |
+
+### Middlewares (`src/auth/middlewares/`)
+
+| File | Class | What it does |
+|---|---|---|
+| `jwt.middleware.ts` | `JwtMiddleware` | Parses `Authorization: Bearer <token>`, decodes, sets `Auth.login()`. Skips if already logged in or no token |
+| `basic.auth.middleware.ts` | `BasicAuthMiddleware` | HTTP Basic; validates against `SERVER_PASSWORD` |
+| `restricted.middleware.ts` | `RestrictedMiddleware` | Throws `NoLoggedUserException` if `Auth.check()` is false. Mounted on `api/*` |
+| `internal.middleware.ts` | `InternalMiddleware` | Reads `x-internal-token` header, compares to `internal.server.key` property, calls `Auth.login(getUserObject(2))` (id 2 = `public` role from `role.mapping.ts`). Mounted on `internal/*` |
+| `client.connect.middleware.ts` | `ClientConnectMiddleware` | Validates `X-Client-ID`/`X-Client-Secret` via `ClientCredentialService.validate` |
+
+### Entities (`src/auth/entities/`)
+
+| File | Entity | Table |
+|---|---|---|
+| `user.entity.ts` | `UserEntity` | `sys_users` (name, email, password, mobile, dialing_code, attempts, image_url, mobile_verified_at, roles, permissions) |
+| `creator.entity.ts` | `CreatorEntity` | `sys_users` (audit lookup mirror) |
+| `refresh.token.entity.ts` | `RefreshTokenEntity` | `sys_refresh_tokens` |
+| `device.token.entity.ts` | `DeviceTokenEntity` | `sys_device_tokens` |
+| `country.entity.ts` | `CountryEntity` | `sys_countries` |
+| `session.identifier.entity.ts` | `SessionIdentifierEntity` | `sys_session_identifiers` |
+| `user.referral.entity.ts` | `UserReferralEntity` | `sys_user_referrals` |
+
+### DTOs (`src/auth/dtos/`)
+
+`create.user.dto.ts`, `offline.user.dto.ts`, `update.user.dto.ts`, `user.access.dto.ts` (current user shape with roles/permissions/access_token/refresh_token), `user.login.dto.ts`, `user.roles.access.object.dto.ts`, `permission.assignment.dto.ts`, `role.assignment.dto.ts`, `session.identifier.attributes.dto.ts`.
+
+### Jobs / Subscribers
+
+- `src/auth/jobs/session.identifier.job.ts` — `SessionIdentifierJob` extends `CommonJob`. Handles SessionIdentifier insert/update.
+- `src/auth/subscribers/session.identifier.subscriber.ts` — `SessionIdentifierSubscriber` listens to `SessionIdentifierEntity` events, dispatches to `SessionIdentifierJob`.
+
+### Module file
+
+- `src/auth/auth.module.ts` — Imports `TypeOrmModule.forFeature(es6Classes.entities)`, `JwtModule.register(jwtConfig)`, `forwardRef(() => PlatformUtilityModule)`. Provides+exports services and jobs (no controllers — those are mounted via `app.module.ts`).
+- `src/auth/es6.classes.ts` — Aggregates all auth classes for DI registration.
+
+---
+
+## `src/common/`
+
+The module is empty (`@Module({})`); its exports are pure helpers and base classes consumed throughout the codebase and by sibling packages.
+
+### Libraries (`src/common/libraries/`)
+
+| File | Class | Purpose / key methods |
+|---|---|---|
+| `auth.ts` | `Auth` | Static-only request user accessor over `express-http-context2`. `Auth.user()` → `UserAccessDto`, `Auth.check()`, `Auth.id()`, `Auth.login(user)` |
+| `common.entity.ts` | `CommonEntity` | Postgres base. Adds id/uuid/created_at/updated_at/deleted_at/created_by/updated_by + `firstOrNew`, `firstOrCreate`, `first`, `softDelete`, `destroy` (static). All postgres entities extend this |
+| `common.mongo.entity.ts` | `CommonMongoEntity` | Mongo equivalent of `CommonEntity` with same static API |
+| `common.service.ts` | `CommonService` | Base for services; `protected publicExposed = false` |
+| `common.subscriber.ts` | `CommonSubscriber<T>` | Generic base subscriber with `afterInsert`/`afterUpdate`/`afterRemove` that dispatch to an `entityJob` (BullMQ). All subscribers extend this |
+| `common.job.ts` | `CommonJob` | Base BullMQ job: `dispatch(data?)`, `delayedDispatch(data, ms)`, `handle(data)` |
+| `common.consumer.ts` | `CommonConsumer` | Base BullMQ consumer (used by `JobConsumer`) |
+| `common.mapper.job.ts` | `CommonMapperJob` | Mapping job pattern: `handle`, `addMapping`, `removeMapping` |
+| `base.job.interface.ts` | (interface) | Two-method contract for jobs |
+| `base.migration.utility.ts` | `BaseMigrationUtility` | Migration DSL: `primary()`, `uuid()`, `boolean()`, `string()`, `bigString()`, `text()`, `float()`, `column()`, `number()`, `bigNumber()`, `renameColumn()`, `foreign()`, `dropForeign()`. Subclassed by `MigrationUtility` |
+| `migration.utility.ts` | `MigrationUtility` | Wraps `BaseMigrationUtility` to flip up/down on `reverseMigration` flag |
+| `reverse.migration.utility.ts` | `ReverseMigrationUtility` | Migration that runs in reverse direction by default |
+| `seeder.utility.ts` | `SeederUtility` | Seeder migration with `addRecord()` |
+| `class.mapper.ts` | `ClassMapper` | Static plain-object/dto helpers: `extract`, `extractNumber`, `removeWhoColumns`, `removeArrayWhoColumns`, `getUniqueEntities`, `castToDto` |
+| `custom.crypt.ts` | `CustomCrypt` | AES via `crypto`. `encrypt(data)`, `decrypt(cipherText)` |
+| `custom.logger.ts` | `CustomLogger` | Console wrapper gated by `SHOW_CONSOLE_LOGS`. Static `log/info/warn/error/debug` |
+| `data.manager.ts` | `DataManager` | Generic single-record fetch/build pipeline: `handle`, `setBaseModelObjects`, `setBase`, `setReadDictionary`, `setQueryRestrictions`, `setupColumnJoins`, `setRequestCache`, `loadFromCache`, `checkForCache` |
+| `database.event.evaluator.ts` | `DatabaseEventEvaluator<Entity>` | extends `EntityEvaluator`. Evaluates DB event payloads against rules |
+| `entity.evaluator.ts` | `EntityEvaluator` | Base entity evaluator; column null/undefined checks |
+| `date.util.ts` | `DateUtil` | `getDateTime`, `getDateTimeInFormat`, `getDateInFormat`, `getMonthInFormat`, `getFutureDateTime(min)`, `getPastDateTime(min)`, `getMonday`, `getDateFromDateString`, `getDateFromDatetimeString`, `now`, `getTimezoneDate`, `getUtcDate`, `addMonths`, `subMonths`, `subDays` |
+| `generic.index.parser.ts` | `GenericIndexParser` | Parses raw query → `GenericIndexParamDto` (filters/sort/pagination) |
+| `generic.show.parser.ts` | `GenericShowParser` | Parses raw query for show endpoints |
+| `hash.ts` | `Hash` | `hash(str)` (bcrypt), `compare(str, hash)`, `hashMD5`, `generateSalt`, `easyHash` (xxhash-wasm async) |
+| `json.evaluator.ts` | `JsonEvaluator` | Evaluates `JsonConditionSettingsDto` against reference data |
+| `list.manager.ts` | `ListManager` | List endpoint pipeline: `process`, `handleRequest`, `listData`, `aggregationData`, `processIncludes`, `getAggregationData`, `loadListData` |
+| `record.manager.ts` | `RecordManager` | Single-record build pipeline: `process(id)`, `segregateIncludes` |
+| `report.body.parser.ts` | `ReportBodyParser` | Parses raw report body → `ReportBodyDto` |
+| `report.data.manager.ts` | `ReportDataManager` | Report-specific equivalent of `DataManager` |
+| `report.list.manager.ts` | `ReportListManager` | Report-specific equivalent of `ListManager` |
+| `platform.utility.ts` | `PlatformUtility` | `getConstantInstance`, `ucwords`, `generateRandomNumber/Alpha/AlphaNumeric/Base32/Chars`, `getEntity(hash)`, `setEntity`, `setEntities`, `initObject(data)`, `getService(hash)`, `setService`, `setServices`, `getJob(hash)`, `getIpFromRequest`, `isValidUrl` |
+
+### Exceptions (`src/common/exceptions/`)
+
+All extend `HttpException`. Throw these instead of raw `Error`/`HttpException`.
+
+| Class | HTTP status | Default message / shape |
+|---|---|---|
+| `OperationException` | 401 | `string \| any`; falls back to `'Invalid Operation'`. Generic operation failure |
+| `AccessException` | 403 | `'You donot have access for this operation'` |
+| `FormException` | 403 | `{ column, err }` → wraps as `{ columns: { [column]: err } }` |
+| `MaintenanceException` | 410 | `'System is down for maintenance'` |
+| `NoLoggedUserException` | 401 | `'No logged user record'` |
+| `SubscriptionException` | 409 | `'No active Subscription!'` |
+
+### DTOs (`src/common/dtos/`)
+
+`aggregation.param.dto.ts`, `capture.record.index.dto.ts`, `capture.record.show.dto.ts`, `database.event.dto.ts`, `foreign.migration.dto.ts`, `generic.index.param.dto.ts`, `generic.show.param.dto.ts`, `group.param.dto.ts`, `index.column.dto.ts`, `index.params.dto.ts`, `json.condition.settings.dto.ts`, `json.field.condition.dto.ts`, `json.field.rule.dto.ts`, `key.value.param.dto.ts`, `layout.column.db.dto.ts`, `meta.data.dto.ts`, `record.data.manager.dto.ts`, `record.tab.dto.ts`, `rename.column.dto.ts`, `report.body.dto.ts`, `report.data.manager.dto.ts`.
+
+### Adapters
+
+- `src/common/adapters/redis.io.adapter.ts` — `RedisIoAdapter` extends `IoAdapter`. Wires socket.io to `@socket.io/redis-adapter` for multi-instance pub/sub.
+
+### Module file
+
+- `src/common/common.module.ts` — `@Module({})` (empty; exports are direct imports).
+- `src/common/es6.classes.ts` — Aggregator (adapters/dtos/exceptions/libraries) but unused by `CommonModule` itself; provided for downstream consumption.
+
+---
+
+## `src/security/`
+
+Tiny module that registers role/permission entities for TypeORM `forFeature`. No services, controllers, or jobs.
+
+### Entities (`src/security/entities/`)
+
+| File | Entity | Table |
+|---|---|---|
+| `role.entity.ts` | `RoleEntity` | `sys_roles` |
+| `permission.entity.ts` | `PermissionEntity` | `sys_permissions` |
+| `user.role.entity.ts` | `UserRoleEntity` | `sys_user_roles` |
+| `user.permission.entity.ts` | `UserPermissionEntity` | `sys_user_permissions` |
+
+### Module file
+
+- `src/security/security.module.ts` — `imports: [TypeOrmModule.forFeature(es6Classes.entities)]`. Nothing else.
+- `src/security/es6.classes.ts` — Aggregates the four entities.
+
+---
+
+## `src/platformUtility/`
+
+Infrastructure-adjacent module: queue, AWS, Redis, mail, sms, FCM, HTTP, file storage, audit, maintenance.
+
+Module-specific behavior: `platform.utility.module.ts` reads `BULL_QUEUE_WORKER`; if not `'true'`, sets `es6Classes.consumers = []` so the worker `JobConsumer` does NOT register on API instances. Imports `RedisModule.forRoot({ type: 'single', ...redisConfig })`, `BullModule.registerQueue({ name: BULL_QUEUE_NAME })`, `forwardRef(() => AuthModule)`, `forwardRef(() => SystemModule)`.
+
+### Services (`src/platformUtility/services/`)
+
+| File | Class | Key methods |
+|---|---|---|
+| `queue.service.ts` | `QueueService` | `addJob`, `getCompletedJobs`, `getFailedJobs`, `getStats`, `getWorkers`, `pauseQueue`, `resumeQueue`, `getJobDetails`, `data` (queue instance) |
+| `mail.service.ts` | `MailService` | `send` (single-gateway), `processMail`, `getBody` (handlebars), `setRecipients`. Multi-gateway via SMTP/SES libraries below |
+| `sms.service.ts` | `SmsService` | `sendWithoutMessage`, `setAndSendMessage`, `sendMessage`, `handleTestEnvironment`. Uses Kaleyra |
+| `cache.service.ts` | `CacheService` | `set`, `get`, `delete`, `remember(key, ttl, fn)`, `forget`. Redis-backed |
+| `redis.service.ts` | `RedisService` | `lpush`, `lrange`, `del`, `get`, `set`, `hset`, `hget`, `sadd`, `smembers`, `exists`, `expire` |
+| `s3.service.ts` | `S3Service` | `uploadFile`, `uploadContent`, `getFile`, `deleteFile`, `getSignedUrl` |
+| `sqs.service.ts` | `SqsService` | `sendMessage`, `sendMessageBatch`, `receiveMessage`, `deleteMessage` |
+| `dynamo.service.ts` | `DynamoService` | `createTable`, `describeTable`, `getItem`, `setItem`, `queryItems`, `listTables` |
+| `audit.service.ts` | `AuditService` | `setAuditRecord`, `getAuditHistory`, `getAuditTable` (DynamoDB-backed, gated by `AUDIT_DISABLED`) |
+| `fcm.notification.service.ts` | `FcmNotificationService` | `sendNotification`, `sendNotificationToDevices`, `deactivateInactiveDevices`. Gated by `NOTIFICATION_DISABLED` |
+| `sql.service.ts` | `SqlService` | `sql(...)` (write connection), `read(...)` (read replica). Gated logging by `ENABLE_SQL_LOG` |
+| `remote.request.service.ts` | `RemoteRequestService` | `sendThroughAxios`, `getRawResponse`, `getProxyResponse`, `saveLog` |
+| `maintenance.service.ts` | `MaintenanceService` | `isInMaintenance`, `putOnMaintenance`, `removeFromMaintenance`, `setRuntimeLock`, `disableQueueIfRequired` |
+| `zip.service.ts` | `ZipService` | `zip(files)`, `unzip`, `getZipToken`, `getUnzipToken`. Lambda-backed |
+| `startup.service.ts` | `StartupService` | `onModuleInit`, `checkForWorkerQueue` |
+| `shutdown.service.ts` | `ShutdownService` | `onModuleDestroy`, `closeAllRunningQueues` |
+| `local.property.service.ts` | `LocalPropertyService` | In-memory store: `set`, `get`, `setEntities`, `setServices`, `setJobs` |
+| `aws.config.service.ts` | `AwsConfigService` | `getConfig`, `validateConfig` |
+| `aws.secret.service.ts` | `AwsSecretService` | `getSecret`, `getSecretValue`, `cacheSecret` |
+| `ses.mail.notification.service.ts` | `SesMailNotificationService` | `getNotificationPayload`, `processSesDeliveryData`, `processSesBouncedData`, `processSesBounceData` |
+
+### Controllers (`src/platformUtility/controllers/`)
+
+| File | Class | Routes |
+|---|---|---|
+| `bull.job.controller.ts` | `BullJobController` | `GET /api/admin/bull-job/completed`, `GET /api/admin/bull-job/failed`, `GET /api/admin/bull-job/waiting`, `GET /api/admin/bull-job/delayed`, `DELETE /api/admin/bull-job/:id` |
+| `queue.controller.ts` | `QueueController` | `GET /api/admin/queue` (stats), `GET /api/admin/queue/workers` |
+
+### Consumer
+
+- `src/platformUtility/consumers/job.consumer.ts` — `JobConsumer` (BullMQ). Generic processor for all job types; failure tracking, draining logic, metrics. **Only registered when `BULL_QUEUE_WORKER=true`**.
+
+### Middlewares
+
+- `src/platformUtility/middlewares/maintenance.middleware.ts` — `MaintenanceMiddleware`. Throws `MaintenanceException` if system in maintenance mode (checked via `MaintenanceService`).
+- `src/platformUtility/middlewares/trim.pipe.ts` — `TrimPipe` validation pipe. Trims whitespace from request body strings (excludes `password` field).
+
+### Entities
+
+| File | Entity | Table |
+|---|---|---|
+| `failed.bull.job.entity.ts` | `FailedBullJobEntity` | `sys_failed_bull_jobs` |
+| `pending.bull.job.entity.ts` | `PendingBullJobEntity` | `sys_pending_bull_jobs` |
+| `remote.request.log.entity.ts` | `RemoteRequestLogEntity` | `utl_remote_request_logs` |
+
+### Jobs
+
+| File | Class | Purpose |
+|---|---|---|
+| `test.job.ts` | `TestJob` | Dummy queue test |
+| `remote.request.log.job.ts` | `RemoteRequestLogJob` | Persist remote request log on insert/update |
+| `reload.pending.bull.job.ts` | `ReloadPendingBullJob` | Reprocess pending jobs in batches of 500 |
+| `load.failed.bull.job.ts` | `LoadFailedBullJob` | Requeue failed jobs from DB |
+| `process.ses.delivery.webhook.job.ts` | `ProcessSesDeliveryWebhookJob` | Handle SES Delivery/Bounce/Complaint notifications |
+| `process.tracking.webhook.job.ts` | `ProcessTrackingWebhookJob` | Email open/click tracking events |
+| `record.watcher.job.ts` | `RecordWatcherJob` | **Hub for all DB change events** — triggers audit logging + observers |
+
+### Subscribers
+
+- `src/platformUtility/subscribers/base.subscriber.ts` — `BaseSubscriber`. Listens to all entities; injects `created_at`/`updated_at`/`created_by`/`updated_by`; dispatches `RecordWatcherJob` for audit + observers.
+- `src/platformUtility/subscribers/remote.request.log.subscriber.ts` — Listens to `RemoteRequestLogEntity` insert; dispatches `RemoteRequestLogJob`.
+
+### Libraries (`src/platformUtility/libraries/`)
+
+| File | Class | Purpose |
+|---|---|---|
+| `file.system.utility.ts` | `FileSystemUtility` | FS scanning: `getModules`, `getAllDirectories`, `getAllFiles`, `getClassName`, `isPackage` |
+| `process.common.mail.ts` | `ProcessCommonMail` | Shared mail send pipeline |
+| `process.common.ses.mail.ts` | `ProcessCommonSesMail` | SES mail processing |
+| `process.common.smtp.mail.ts` | `ProcessCommonSmtpMail` | SMTP mail processing |
+| `process.ses.mail.ts` | `ProcessSesMail` | SES `SendEmailCommand` send |
+| `process.ses.raw.mail.ts` | `ProcessSesRawMail` | SES `SendRawEmailCommand` (with attachments) |
+| `process.smtp.mail.ts` | `ProcessSmtpMail` | Nodemailer SMTP send |
+| `process.kaleyra.sms.ts` | `ProcessKaleyraSms` | Kaleyra SMS API send |
+| `process.kaleyra.callback.response.ts` | `ProcessKaleyraCallbackResponse` | Kaleyra webhook parser |
+| `set.sms.message.ts` | `SetSmsMessage` | SMS entity creation/validation |
+| `process.audit.log.data.ts` | `ProcessAuditLogData` | DynamoDB audit record formatter |
+| `common.sqs.polling.ts` | `CommonSqsPolling` | SQS polling base loop with maintenance checks |
+| `create.es6.classes.file.ts` | `CreateEs6ClassesFile` | Generates module `es6.classes.ts` files |
+| `create.es6.service.file.ts` | `CreateEs6ServiceFile` | Generates service registry file |
+| `create.es6.jobs.file.ts` | `CreateEs6JobsFile` | Generates job registry file |
+| `create.entity.constants.file.ts` | `CreateEntityConstantsFile` | Generates entity constants mappings |
+| `create.index.file.ts` | `CreateIndexFile` | Generates barrel `index.ts` files |
+
+### DTOs (`src/platformUtility/dtos/`)
+
+`aws.config.dto.ts`, `common.attributes.dto.ts`, `failed.bull.job.attributes.dto.ts`, `pending.bull.job.attributes.dto.ts`, `fcm.response.dto.ts`, `job.payload.dto.ts`, `kaleyra.callback.payload.dto.ts`, `lambda.zip.dto.ts`, `mail.options.dto.ts` (to/cc/bcc/subject/html/text/attachments/gateway/track_pairs), `push.notification.response.dto.ts`, `push.notification.template.dto.ts`, `queue.options.dto.ts` (delay/priority/attempts/backoff/removeOnComplete), `remote.raw.response.dto.ts`, `remote.request.config.dto.ts`, `remote.request.log.attributes.dto.ts`, `set.sms.payload.dto.ts`, `sms.payload.dto.ts`, `smtp.config.dto.ts`, `source.column.dto.ts`, `string.search.dto.ts`.
+
+---
+
+## `src/system/`
+
+The largest module: ~70 entities for menus, roles, models, columns, relationships, properties, lookups, forms, reports, charts, scripts, scheduled events, mail/sms/whatsapp templates, document storage. Imports `forwardRef(() => AuthModule)`, `forwardRef(() => PlatformUtilityModule)`, `TypeOrmModule.forFeature(es6Classes.entities)`. Provides+exports services and jobs; controllers from this module are mounted via the controllers array.
+
+### Services (`src/system/services/`)
+
+| File | Class | Key methods |
+|---|---|---|
+| `aws.s3.service.ts` | `AwsS3Service` | `getBucket`, `getS3BucketKeyFromUrl`, `upload`. **Different from `platformUtility/s3.service.ts`** — this is the upload-engine impl chosen by `UploadService` |
+| `cloudflare.r2.service.ts` | `CloudflareR2Service` | Same shape as AwsS3Service for R2 |
+| `base.service.ts` | `BaseService` | `checkOrSetRecord(hash)`, `getServiceInstance(identifier)`, `getEntityInstance(identifier)` |
+| `business.rule.service.ts` | `BusinessRuleService` | `getQueryRestrictions(modelId, action)`, `validateRoleCheck(role)`. Restricts list queries based on rules |
+| `client.credential.service.ts` | `ClientCredentialService` | `validate(payload)` (client_id/secret + IP allowlist), `setCredentialCache(key)` |
+| `client.script.service.ts` | `ClientScriptService` | `getClientScripts(identifier)` |
+| `column.service.ts` | `ColumnService` | `getModelColumns(id)` |
+| `comment.service.ts` | `CommentService` | `getComments(query)`, `setComment(body)` (handles attachments) |
+| `document.service.ts` | `DocumentService` | `getDocuments(query)`, `setDocument(source)`, `setDocuments(source)` |
+| `event.detail.service.ts` | `EventDetailService` | `checkOrSetRecord(identifier)` |
+| `event.queue.service.ts` | `EventQueueService` | `getActiveEvents`, `setEvent(identifier)`, `trigger(event)`, `triggerById(id)` |
+| `executable.script.service.ts` | `ExecutableScriptService` | `execute(data)` — runs stored scripts via `ProcessScriptExecution` |
+| `form.service.ts` | `FormService` | `getDictionary(form)` |
+| `internal.server.connect.service.ts` | `InternalServerConnectService` | `post(type, ...)`, `get(type, ...)`. Handles outbound calls to other internal servers using `internal.server.key` and credential expiry |
+| `list.service.ts` | `ListService` | `index(param)`, `show(id)`, `getLayoutDefinition(layoutId)`, `getBaseFromModel(model)` |
+| `logger.service.ts` | `LoggerService` | `set(message)`, `log`, `info`, `warn`, `error`. Persists to `SystemLogEntity` (writes via `SystemLogJob`) |
+| `mail.validation.service.ts` | `MailValidationService` | `generate(email)` (OTP), `validate(payload)` |
+| `mobile.validation.service.ts` | `MobileValidationService` | `generate(mobile)`, `validate(payload)` |
+| `menu.service.ts` | `MenuService` | `getMenus`, `getMenuDetails(id)` |
+| `model.service.ts` | `ModelService` | `getUiActions(model)`, `validateHashAccess(hash)`, `validateModelAccess(model, action)`, `getModelFromHash` |
+| `preference.service.ts` | `PreferenceService` | `getMenuListPreferences`, `getTabListPreferences`, `getTabFormPreferences`, `getListPreferences`, `getFormPreferences`, `getModelFormPreferences` |
+| `property.service.ts` | `PropertyService` | `get(key, default?)`, `getFromDb(key, default?)`. Handles encryption via `CustomCrypt` and caching. **Use this to read `internal.server.key` and other system properties** |
+| `report.service.ts` | `ReportService` | `hasAccess(id)`, `getReportDetails(id)` |
+| `scheduled.event.service.ts` | `ScheduledEventService` | `getActiveEventsSummary(source)`, `deleteActiveEvents(source)`, `getSchedules(source)` (cron-parser based; respects `inQueueCount`/`maxCount`) |
+| `security.rule.service.ts` | `SecurityRuleService` | `getModelSecurityRules(model)`, `getFormSecurityRules(form)`, `getSecurityObjectNotation(identifier)`, `getScript(id)`, `getSecurityRules(id)` |
+| `ui.action.service.ts` | `UiActionService` | `getUiActions(source_type)`, role/permission gate via `accessService.hasRoleAssignments`/`hasPermissionAssignments` |
+| `upload.service.ts` | `UploadService` | `upload(file, options)`, `uploadWithStats`, `uploadFile(param)`, `saveLocalFileOnS3(option)`. Selects engine via `STORAGE_ENGINE` env (`s3`/`r2`) |
+| `user.preference.service.ts` | `UserPreferenceService` | `getUserPreferences`, `getUserPreference(key)`, `setUserPreference(name)`, `setGlobalPreference(key)`, `revokeUserSpecificPreferences(name)` |
+| `es6.service.ts` | `Es6Service` | Service registry locator |
+| `es6.jobs.service.ts` | `Es6JobsService` | Job registry locator |
+
+### Controllers (`src/system/controllers/`)
+
+| File | Class | Routes |
+|---|---|---|
+| `base.controller.ts` | `BaseController` (`api/record/:hash`) | `GET /` (list), `GET /create` (form metadata), `GET /:id` (show), `POST /` (create), `GET /:id/edit` (edit form), `GET /:id/audit-log`, `PUT /:id` (update), `DELETE /:id` |
+| `data.controller.ts` | `DataController` (`api/data/:hash`) | `GET /` (data list), `GET /:id` |
+| `form.controller.ts` | `FormController` (`api/admin/form`) | `GET /:id` |
+| `menu.controller.ts` | `MenuController` (`api/admin/menu`) | `GET /`, `GET /:id`, `POST /` |
+| `preference.controller.ts` | `PreferenceController` (`api/admin/`) | `GET preferences`, `POST list-preference`, `POST menu-list-preference/:id`, `POST model-form-preference/:id`, `POST form-preference`, `DELETE list-preference/:id`, `DELETE form-preference/:id` |
+| `report.controller.ts` | `ReportController` (`api/admin`) | `POST report/:id/sync`, `GET report/:id`, `POST get-chart-data/:id`, `POST get-report-data/:id` |
+| `upload.controller.ts` | `UploadController` (no prefix) | `POST uploads`, `POST api/admin/uploads` |
+| `user.preference.controller.ts` | `UserPreferenceController` (`api/admin/user-preference`) | `GET /`, `POST /` |
+
+### Entities (`src/system/entities/`)
+
+All extend `CommonEntity`. Tables:
+
+| Domain | Entity → Table |
+|---|---|
+| Models | `model` → `sys_model_details`, `model.column` → `sys_model_columns`, `model.relationship` → `sys_model_relationships`, `model.role` → `sys_model_roles`, `column` → `sys_column_details`, `column.definition` → `sys_column_definitions`, `relationship` → `sys_relationship_details` |
+| Menus | `menu` → `sys_menu_details`, `menu.role` → `sys_menu_roles`, `module` → `sys_module_details`, `module.menu` → `sys_module_menus`, `parent.menu` → `sys_parent_menus` |
+| Forms | `form` → `sys_form_details`, `form.column` → `sys_form_columns`, `form.preference` → `sys_form_preferences`, `list.preference` → `sys_list_preferences` |
+| Reports | `report` → `sys_report_details`, `report.column` → `sys_report_columns`, `report.filter` → `sys_report_filters`, `report.param` → `sys_report_params`, `report.relationship` → `sys_report_relationships`, `report.role` → `sys_report_roles`, `report.sheet` → `sys_report_sheets` |
+| Charts | `chart` → `sys_chart_details`, `primary.axis` → `sys_chart_primary_axis`, `secondary.axis` → `sys_chart_secondary_axis` |
+| Properties | `property` → `sys_properties`, `open.property` → `sys_open_properties`, `lookup.type` → `sys_lookup_types`, `lookup.value` → `sys_lookup_values` |
+| Mail | `mail.event` → `sys_mail_events`, `mail.recipient` → `sys_mail_recipients`, `mail.log` → `sys_mail_logs`, `mail.validation` → `sys_mail_validations`, `email.template` → `sys_email_templates` |
+| SMS | `sms.message` → `sys_sms_messages`, `sms.template` → `sys_sms_templates`, `mobile.validation` → `sys_mobile_validations`, `whatsapp.template` → `sys_whatsapp_templates` |
+| Scripts | `system.script` → `sys_system_scripts`, `executable.script` → `sys_executable_scripts`, `client.script` → `sys_client_scripts`, `code.fix.script` → `sys_codefix_scripts`, `code.fix.log` → `sys_codefix_logs` |
+| Events | `event.detail` → `sys_event_details`, `event.log` → `sys_event_logs`, `event.queue` → `sys_event_queues`, `scheduled.event` → `sys_scheduled_events`, `recurring.query` → `sys_recurring_queries` |
+| Clients | `client` → `sys_client_details`, `client.credential` → `sys_client_credentials`, `credential.ip` → `sys_credential_ips`, `service` → `sys_service_details` |
+| Users/Groups | `user.group` → `sys_user_groups`, `user.group.member` → `sys_user_group_members`, `user.group.permission` → `sys_user_group_permissions`, `user.group.role` → `sys_user_group_roles`, `user.preference` → `sys_user_preferences` |
+| Misc | `business.rule` → `sys_business_rules`, `business.rule.role` → `sys_business_rule_roles`, `security.rule` → `sys_security_rules`, `ui.action` → `sys_ui_actions`, `ui.action.permission` → `sys_ui_action_permissions`, `ui.action.role` → `sys_ui_action_roles`, `comment` → `sys_comments`, `document` → `sys_documents`, `data.log` → `sys_data_logs`, `system.log` → `sys_system_logs`, `dynamo.table` → `sys_dynamo_tables`, `material.view` → `sys_material_views`, `page.definition` → `sys_page_definitions` |
+
+### Mongo entities (`src/system/mentities/`)
+
+- `test.mentity.ts` — `TestMentity` (mongo collection, used by `TestMongoJob`).
+
+### DTOs (`src/system/dtos/`)
+
+`add.comment.dto.ts`, `add.direct.menu.dto.ts`, `client.attributes.dto.ts`, `client.credential.attributes.dto.ts`, `client.credential.dto.ts`, `code.fix.log.attributes.dto.ts`, `code.fix.script.attributes.dto.ts`, `comment.attributes.dto.ts`, `credential.ip.attributes.dto.ts`, `data.log.attributes.dto.ts`, `document.attributes.dto.ts`, `event.log.attributes.dto.ts`, `executable.script.attributes.dto.ts`, `executable.script.payload.dto.ts`, `file.upload.dto.ts`, `file.upload.spec.dto.ts`, `job.record.param.dto.ts`, `local.file.s3.upload.dto.ts`, `mail.event.attributes.dto.ts`, `mail.recipient.attributes.dto.ts`, `mail.validation.dto.ts`, `material.view.attributes.dto.ts`, `menu.list.preference.creation.dto.ts`, `mobile.validation.dto.ts`, `model.allowed.column.dto.ts`, `model.form.preference.creation.dto.ts`, `otp.generation.dto.ts`, `recurring.query.attributes.dto.ts`, `report.sheet.attributes.dto.ts`, `s3.object.info.dto.ts`, `s3.upload.options.dto.ts`, `sms.message.attributes.dto.ts`, `system.log.attributes.dto.ts`, `user.preference.creation.dto.ts`, `validation.options.dto.ts`.
+
+### Jobs (`src/system/jobs/`)
+
+39 BullMQ jobs. All extend `CommonJob`. Naming convention `<entity>.job.ts` for entity-event jobs, `set.<thing>.job.ts` for event-queue scheduling jobs, `execute.<thing>.job.ts` / `refresh.<thing>.job.ts` for direct execution jobs.
+
+| File | Class | What it does |
+|---|---|---|
+| `client.credential.job.ts` | `ClientCredentialJob` | ClientCredential entity insert/update side effects |
+| `client.job.ts` | `ClientJob` | Client entity changes |
+| `code.fix.log.job.ts` | `CodeFixLogJob` | CodeFixLog persist |
+| `code.fix.script.job.ts` | `CodeFixScriptJob` | CodeFixScript changes |
+| `column.mapper.job.ts` | `ColumnMapperJob` | Map column metadata to ModelColumn rows |
+| `comment.job.ts` | `CommentJob` | Comment persist + notifications |
+| `credential.ip.job.ts` | `CredentialIpJob` | CredentialIp changes |
+| `data.log.job.ts` | `DataLogJob` | DataLog persist |
+| `document.job.ts` | `DocumentJob` | Document persist + S3 hash |
+| `event.log.job.ts` | `EventLogJob` | EventLog persist |
+| `executable.script.job.ts` | `ExecutableScriptJob` | ExecutableScript changes |
+| `execute.code.fix.job.ts` | `ExecuteCodeFixJob` | Run a code fix script via `ExecuteCodeFix` library |
+| `execute.material.view.job.ts` | `ExecuteMaterialViewJob` | Refresh material view query |
+| `execute.recurring.query.job.ts` | `ExecuteRecurringQueryJob` | Run recurring query |
+| `mail.event.job.ts` | `MailEventJob` | Mail event creation → recipients |
+| `mail.recipient.job.ts` | `MailRecipientJob` | Per-recipient mail send |
+| `mail.validation.job.ts` | `MailValidationJob` | Email OTP validation event |
+| `material.view.job.ts` | `MaterialViewJob` | MaterialView changes |
+| `mobile.validation.job.ts` | `MobileValidationJob` | Mobile OTP validation event |
+| `model.scanner.job.ts` | `ModelScannerJob` | Sync TypeORM entity metadata to Model rows |
+| `property.job.ts` | `PropertyJob` | Property entity → cache refresh |
+| `recurring.query.job.ts` | `RecurringQueryJob` | RecurringQuery changes |
+| `refresh.material.view.job.ts` | `RefreshMaterialViewJob` | Trigger material view refresh schedule |
+| `refresh.property.cache.job.ts` | `RefreshPropertyCacheJob` | Reload property cache |
+| `relationship.mapper.job.ts` | `RelationshipMapperJob` | Map ModelRelationships from typeorm metadata |
+| `report.column.sync.job.ts` | `ReportColumnSyncJob` | Sync ReportColumn rows |
+| `report.sheet.job.ts` | `ReportSheetJob` | ReportSheet changes |
+| `scheduled.event.job.ts` | `ScheduledEventJob` | ScheduledEvent persist + queue scheduling |
+| `set.codefix.script.event.job.ts` | `SetCodefixScriptEventJob` | Schedule code fix execution event |
+| `set.event.queue.job.ts` | `SetEventQueueJob` | Insert into EventQueue |
+| `set.recurring.query.event.job.ts` | `SetRecurringQueryEventJob` | Schedule recurring query event |
+| `set.scheduled.event.job.ts` | `SetScheduledEventJob` | Persist scheduled event metadata |
+| `sms.message.job.ts` | `SmsMessageJob` | SmsMessage persist + send |
+| `sqs.polling.job.ts` | `SqsPollingJob` | Drives `CommonSqsPolling` polling loop |
+| `sync.all.code.job.ts` | `SyncAllCodeJob` | Full code sync (models, columns, relationships, menus...) |
+| `system.log.job.ts` | `SystemLogJob` | Persist SystemLog |
+| `test.mongo.job.ts` | `TestMongoJob` | Mongo connectivity test |
+| `user.group.member.job.ts` | `UserGroupMemberJob` | Group membership change |
+| `user.group.permission.job.ts` | `UserGroupPermissionJob` | Group permission change |
+| `user.group.role.job.ts` | `UserGroupRoleJob` | Group role change |
+
+### Subscribers (`src/system/subscribers/`)
+
+All 27 subscribers follow the same pattern:
+
+```ts
+@EventSubscriber()
+export class XSubscriber extends CommonSubscriber<XEntity> {
+    constructor(private readonly dataSource: DataSource, protected readonly entityJob: XJob) {
+        super();
+        dataSource.subscribers.push(this);
+    }
+    listenTo() { return XEntity; }
+}
+```
+
+Mappings (subscriber file → entity → triggered job): `client.credential` → `ClientCredentialEntity` → `ClientCredentialJob`; `client` → `ClientEntity` → `ClientJob`; `code.fix.log` → `CodeFixLogEntity` → `CodeFixLogJob`; `code.fix.script` → `CodeFixScriptEntity` → `CodeFixScriptJob`; `column` → `ColumnEntity` → `ColumnMapperJob`; `comment` → `CommentEntity` → `CommentJob`; `credential.ip` → `CredentialIpEntity` → `CredentialIpJob`; `data.log` → `DataLogEntity` → `DataLogJob`; `document` → `DocumentEntity` → `DocumentJob`; `event.log` → `EventLogEntity` → `EventLogJob`; `executable.script` → `ExecutableScriptEntity` → `ExecutableScriptJob`; `mail.event` → `MailEventEntity` → `MailEventJob`; `mail.recipient` → `MailRecipientEntity` → `MailRecipientJob`; `mail.validation` → `MailValidationEntity` → `MailValidationJob`; `material.view` → `MaterialViewEntity` → `MaterialViewJob`; `mobile.validation` → `MobileValidationEntity` → `MobileValidationJob`; `property` → `PropertyEntity` → `PropertyJob`; `recurring.query` → `RecurringQueryEntity` → `RecurringQueryJob`; `relationship` → `RelationshipEntity` → `RelationshipMapperJob`; `report.sheet` → `ReportSheetEntity` → `ReportSheetJob`; `scheduled.event` → `ScheduledEventEntity` → `ScheduledEventJob`; `sms.message` → `SmsMessageEntity` → `SmsMessageJob`; `system.log` → `SystemLogEntity` → `SystemLogJob`; `user.group.member` → `UserGroupMemberEntity` → `UserGroupMemberJob`; `user.group.permission` → `UserGroupPermissionEntity` → `UserGroupPermissionJob`; `user.group.role` → `UserGroupRoleEntity` → `UserGroupRoleJob`; `test.mongo.subscriber.ts` is the only mongo subscriber (listens to `TestMentity`).
+
+### Libraries (`src/system/libraries/`)
+
+| File | Class | Purpose |
+|---|---|---|
+| `business.rule.filter.validator.ts` | `BusinessRuleFilterValidator` | Validates business rule filter conditions in an isolated script context |
+| `business.rule.query.evaluator.ts` | `BusinessRuleQueryEvaluator` | Evaluates business rule query scripts in isolated execution |
+| `code.evaluator.ts` | `CodeEvaluator` | Executes arbitrary code-fix scripts within a controlled context |
+| `column.manager.ts` | `ColumnManager` | Column dictionary with security rule filtering |
+| `common.storage.service.ts` | `CommonStorageService` | S3 upload param interface |
+| `execute.code.fix.ts` | `ExecuteCodeFix` | Executes stored code fix scripts and records execution logs |
+| `generate.downloadable.report.file.ts` | `GenerateDownloadableReportFile` | Builds report file (xlsx via `exceljs`) |
+| `get.report.query.ts` | `GetReportQuery` | Builds report SQL query with parameter substitutions and filter restrictions |
+| `model.sync.ts` | `ModelSync` | Syncs TypeORM entity metadata with model+column definitions |
+| `process.menu.creation.ts` | `ProcessMenuCreation` | Creates menu structures (list/detail) and links to modules |
+| `process.script.execution.ts` | `ProcessScriptExecution` | Processes/executes scripts dynamically |
+| `security.rule.evaluator.ts` | `SecurityRuleEvaluator` | Evaluates security rule scripts for access validation |
+| `sync.dynamo.tables.ts` | `SyncDynamoTables` | Syncs DynamoDB metadata between remote tables and local definitions |
+
+### Modifiers (`src/system/modifiers/`)
+
+- `menu.list.modifier.ts` — `MenuListModifier`. `class-transformer` shape applied via `plainToClass` in `MenuService.getMenuDetails`.
+- `module.list.modifier.ts` — `ModuleListModifier`. Shape for module list responses.
+
+### Interceptors
+
+- `src/system/interceptors/sentry.interceptor.ts` — `SentryInterceptor`. Captures unhandled exceptions to Sentry. Applied globally in `main.ts` when `SENTRY_DSN` is set.
+
+---
+
+## `src/migrations/`
+
+136 TypeORM migrations + a `seeders/` subdirectory. Filename convention: `<unix-millis-timestamp>-<PascalCaseDescription>.ts`. Migrations from sibling `@servicelabsco/*` packages also run against this DB (via the glob in `typeorm.config.ts`). Migrations table: `sys_migrations`.
+
+Migration files use `MigrationUtility` / `BaseMigrationUtility` / `ReverseMigrationUtility` / `SeederUtility` from `common/libraries/`. The `up`/`down` semantics flip when the `reverseMigration` flag is set so a single class can run forward or backward depending on context.
+
+The `seeders/` directory contains data-only migrations (e.g. `sys_user_roles.json` is gitignored and seeded from there).
+
+---
+
+## `src/views/`
+
+Handlebars (`hbs`) templates for emails. Used by `MailService.getBody()` via `handlebars` package.
+
+---
+
+## Patterns / how-to recipes
+
+**Add a new postgres entity:**
+1. Create `src/<module>/entities/<name>.entity.ts`, extend `CommonEntity`, decorate with `@Entity('<table>')`. Use snake_case is auto-applied — write camelCase fields.
+2. Add the import + array entry to `src/<module>/es6.classes.ts` under `entities`.
+3. Generate migration: `yarn m:g <Name>`. Inside, instantiate `MigrationUtility` so `reverseMigration` works.
+4. If you want change events, add a subscriber + job (next recipe).
+
+**Add a subscriber + job for an entity:**
+1. Create `src/<module>/jobs/<name>.job.ts` extending `CommonJob` with a `handle(data)` method.
+2. Create `src/<module>/subscribers/<name>.subscriber.ts` matching the template above.
+3. Register both in `es6.classes.ts` (`jobs`, `subscribers`).
+
+**Add a new service:**
+1. Create `src/<module>/services/<name>.service.ts`, `@Injectable()`, extend `CommonService`.
+2. Register in `es6.classes.ts` under `services`.
+
+**Read a system property:**
+- `await propertyService.get('property.key', defaultValue)` — handles caching + decryption.
+
+**Throw a domain error:** use one of the six exception classes in `common/exceptions/` (see table above) — never bare `HttpException`.
+
+**Get current user:** `Auth.user()` (or `Auth.id()`, `Auth.check()`) from `common/libraries/auth.ts`. Never read `req.user` directly.
+
+**Add a queue job at runtime:** `queueService.addJob(jobName, payload, options?)`. The `JobConsumer` (worker only) processes it.
+
+**Internal-server-to-internal-server call:** `internalServerConnectService.post(type, payload)` / `.get(...)` — handles credential lookup/expiry.
+
+**Generate `es6.classes.ts` files automatically:** `slnu syncClassess` (the `commit.sh` integration). Otherwise update by hand.
+
+---
+
+## Top-level files
+
+- `package.json` — `main: dist/index.js`, scripts (build/start/test/lint/m:*/console/runtime-check/save). Jest config rootDir=src. Dependencies pinned to NestJS 11.
+- `tsconfig.json` — target ES2021, commonjs, decorators on, strict off (no `strict: true`; types: `["node","jest"]`).
+- `tsconfig.build.json` — build excludes (extends base).
+- `nest-cli.json` — `sourceRoot: src`, `deleteOutDir: true`.
+- `.eslintrc.js` — `@typescript-eslint/recommended` + `plugin:prettier/recommended`. Disables `interface-name-prefix`, `explicit-function-return-type`, `no-explicit-any`, `camelcase`.
+- `.prettierrc` — `singleQuote`, `trailingComma: es5`, `tabWidth: 4`, `printWidth: 150`.
+- `commit.sh` — `yarn save` flow: pull, optional build, optional `slnu syncClassess`, prettier, git add, JIRA-prefixed commit, push.
+- `Procfile` — `web: npm run start:prod` (Heroku).
+- `.circleci/config.yml` — entirely commented out (CI not active).
+- `tslint.json` — legacy, ignored (eslint is the linter).
+
+---
+
+## Tests (`*.spec.ts` under `src/`)
+
+Jest config inline in `package.json` (`rootDir: src`, `testRegex: .*\.spec\.ts$`, `ts-jest`). Run a single: `yarn test -- path/to/file.spec.ts` or `yarn test -- -t "name"`.
+
+Test files present:
+- `src/config/source.hash.spec.ts`
+- `src/auth/middlewares/jwt.middleware.spec.ts`, `basic.auth.middleware.spec.ts`
+- `src/auth/services/auth.service.spec.ts`
+- `src/system/services/scheduled.event.service.spec.ts`
+- `src/common/libraries/{auth,class.mapper,custom.crypt,custom.logger,database.event.evaluator,date.util,entity.evaluator,generic.index.parser,generic.show.parser,hash,json.evaluator,platform.utility,report.body.parser}.spec.ts`
+- `src/common/exceptions/*.spec.ts` (every exception)
+- `src/platformUtility/middlewares/{maintenance.middleware,trim.pipe}.spec.ts`
+- `src/platformUtility/services/{cache.service,zip.service}.spec.ts`
+
+E2E config in `test/jest-e2e.json` (no `*.e2e-spec.ts` files present yet).

package/dist/app.controller.d.ts

@@ -1,4 +1,3 @@
-import { Request } from 'express';
 import { TestJob } from './platformUtility/jobs/test.job';
 import { AuditService } from './platformUtility/services/audit.service';
 import { CacheService } from './platformUtility/services/cache.service';
@@ -34,10 +33,6 @@ export declare class AppController {
     }>;
     getUserAuthObject(): Promise<any>;
     testOne(): Promise<any>;
-    unset(query: any): Promise<any>;
     getQueueInstance(): Promise<any>;
     queue(id: string): Promise<any>;
-    set(req: Request): Promise<{
-        url: any;
-    }>;
 }