@solidxai/core 0.1.10-beta.0 → 0.1.10-beta.2

package/docs/java-spring/solid-core-module-deep-dive-report.md

@@ -1,1317 +0,0 @@
-# solid-core-module Deep Dive Report
-
-## Purpose
-
-This document reviews `solid-core-module` as the backend runtime kernel used by SolidX applications, with special attention to how it is consumed by a real project such as `~/Code/javascript/mswipe-erp-solidx/solid-api`.
-
-The goal is not just to describe the NestJS/TypeORM implementation, but to make the architecture legible enough to guide a future Java Spring Boot version of the backend while keeping the existing `solid-core-ui` frontend model intact.
-
-## Executive Summary
-
-`solid-core-module` is not a narrow utility package. It is the platform backend runtime for SolidX. It provides:
-
-- the shared persistence model for platform metadata and IAM
-- the generic metadata-driven CRUD engine
-- repository and security rule enforcement
-- authentication and token lifecycle management
-- notifications and queue-backed integrations
-- file/media storage abstractions
-- dashboards, import/export, scheduled jobs, chatter, AI ingestion, and CLI support
-- extension contracts that consuming projects plug into via generated Nest modules
-
-In a consuming project such as `mswipe-erp-solidx`, the pattern is:
-
-- `SolidCoreModule` is imported once at the app root
-- core entities are included in one or more datasource registrations
-- business modules such as `cpm`, `reports`, `onboarding`, and `mswipe-masters` are generated or hand-extended under `solid-api/src/<module>`
-- generated services usually extend core `CRUDService<T>`
-- generated repositories usually extend core `SolidBaseRepository<T>`
-- module metadata JSON under `solid-api/module-metadata/<module>/<module>-metadata.json` drives scaffolding, runtime behavior, and admin UI wiring
-
-This is the most important architectural conclusion for a Spring Boot port:
-
-`solid-core-module` is effectively the reusable application platform layer, while each consuming app contributes domain modules, entities, repositories, services, controllers, metadata JSON, and datasource definitions around it.
-
-## Consumer Project Context
-
-### How `mswipe-erp-solidx` uses the core
-
-From `[/Users/harishpatel/Code/javascript/mswipe-erp-solidx/solid-api/src/app.module.ts](/Users/harishpatel/Code/javascript/mswipe-erp-solidx/solid-api/src/app.module.ts)`:
-
-- `SolidCoreModule` is imported at the root beside several datasource modules.
-- The app also enables `ConfigModule`, `WinstonModule`, `EventEmitterModule`, and `ClsModule`.
-- Dynamic module loading is done through `AppService.forRoot()` using `getDynamicModuleNames()`.
-
-From `[/Users/harishpatel/Code/javascript/mswipe-erp-solidx/solid-api/src/app.service.ts](/Users/harishpatel/Code/javascript/mswipe-erp-solidx/solid-api/src/app.service.ts)`:
-
-- the app scans `solid-api/src/*`
-- any folder containing `<module>/<module>.module.ts` is treated as a dynamic business module
-- those modules are imported at runtime
-
-From `[/Users/harishpatel/Code/javascript/mswipe-erp-solidx/solid-api/src/cpm/cpm.module.ts](/Users/harishpatel/Code/javascript/mswipe-erp-solidx/solid-api/src/cpm/cpm.module.ts)` and `[/Users/harishpatel/Code/javascript/mswipe-erp-solidx/solid-api/src/reports/reports.module.ts](/Users/harishpatel/Code/javascript/mswipe-erp-solidx/solid-api/src/reports/reports.module.ts)`:
-
-- a generated domain module is a conventional Nest module
-- it registers entities via `TypeOrmModule.forFeature(...)`
-- it exposes generated controllers, services, repositories, and optional custom providers
-- cross-module dependencies are handled through normal Nest imports
-
-From `[/Users/harishpatel/Code/javascript/mswipe-erp-solidx/solid-api/src/cpm/services/customer-master.service.ts](/Users/harishpatel/Code/javascript/mswipe-erp-solidx/solid-api/src/cpm/services/customer-master.service.ts)`:
-
-- domain services often extend `CRUDService<T>`
-- they add custom business methods on top of generic CRUD
-- they can use core services like `ChatterMessageService`, `RequestContextService`, and settings access inherited through the module graph
-
-From `[/Users/harishpatel/Code/javascript/mswipe-erp-solidx/solid-api/src/cpm/repositories/customer-master.repository.ts](/Users/harishpatel/Code/javascript/mswipe-erp-solidx/solid-api/src/cpm/repositories/customer-master.repository.ts)`:
-
-- generated repositories extend `SolidBaseRepository<T>`
-- security rule enforcement and request-aware behavior come from the base class
-
-From `[/Users/harishpatel/Code/javascript/mswipe-erp-solidx/solid-api/src/app-default-database.module.ts](/Users/harishpatel/Code/javascript/mswipe-erp-solidx/solid-api/src/app-default-database.module.ts)`:
-
-- consuming apps include all core entities in datasource registration
-- they also register their own business entities
-- they decorate datasource modules with `@SolidDatabaseModule()`
-- this matters because SolidX relies on discovering active datasources and their types
-
-From `[/Users/harishpatel/Code/javascript/mswipe-erp-solidx/solid-api/module-metadata/cpm/cpm-metadata.json](/Users/harishpatel/Code/javascript/mswipe-erp-solidx/solid-api/module-metadata/cpm/cpm-metadata.json)`:
-
-- module metadata is not incidental
-- it defines module identity, datasource binding, model structure, field semantics, layout inputs, and runtime behavior
-- business modules in consuming projects are therefore both code-driven and metadata-driven
-
-### Structural takeaway
-
-A consuming `solid-api` project is best understood as:
-
-1. `solid-core-module` supplies the platform kernel.
-2. The app supplies datasource modules, business modules, metadata JSON, and custom business integrations.
-3. Generated code bridges metadata into ordinary NestJS/TypeORM artifacts.
-4. Runtime behavior is a combination of:
-   - generic core services
-   - discovered providers and decorators
-   - generated entities/controllers/services/repositories
-   - module metadata stored both in the database and on disk
-
-## Core Architectural Shape
-
-### Package identity
-
-From `package.json` and `README.md`:
-
-- package name: `@solidxai/core`
-- role: global NestJS module and backend engine for SolidX apps
-- technology base: NestJS 10, TypeORM, TypeScript
-- runtime concerns included: IAM, CRUD, queues, storage, scheduler, import/export, dashboards, testing, CLI, AI ingestion
-
-### Central module
-
-From `[/Users/harishpatel/Code/javascript/solid-core-module/src/solid-core.module.ts](/Users/harishpatel/Code/javascript/solid-core-module/src/solid-core.module.ts)`:
-
-- `SolidCoreModule` is marked `@Global()`
-- it imports a very large set of entities into TypeORM
-- it wires global infrastructure such as cache, scheduling, static media serving, multer uploads, JWT, CLS, HTTP
-- it registers global guards, interceptors, and exception filters
-- it exposes a wide provider surface that consuming apps can reuse directly
-
-This file is effectively the runtime composition root of the platform.
-
-### CLI module
-
-From `[/Users/harishpatel/Code/javascript/solid-core-module/src/solid-core-cli.module.ts](/Users/harishpatel/Code/javascript/solid-core-module/src/solid-core-cli.module.ts)`:
-
-- a separate CLI composition root exists
-- it reuses the main module but adds CLI-oriented database and config setup
-- this is how metadata generation, seeding, test running, and ingestion workflows execute outside the HTTP server
-
-## Folder-by-Folder Review
-
-The `src` tree is broad. File counts are approximate indicators of emphasis:
-
-- `services`: 121 files
-- `dtos`: 118 files
-- `jobs`: 108 files
-- `controllers`: 45 files
-- `entities`: 43 files
-- `testing`: 42 files
-- `helpers`: 40 files
-- `repository`: 40 files
-
-That distribution tells us the codebase is primarily a platform runtime with a large behavior surface, not just a small domain model.
-
-### Top-level non-`src` folders
-
-#### `sql/`
-
-- database-specific SQL assets exist for `postgres`, `mysql`, `mariadb`, and `mssql`
-- examples include metadata cleanup procedures
-- this is evidence that SolidX already thinks in terms of backend-database portability, even if the application framework layer is currently NestJS/TypeORM
-
-#### `docs/`
-
-- contains internal workflow and design notes
-- topics include test data workflow, seed changes, grouping enhancements, and type declaration issues
-- these are useful supporting materials but are not the main runtime itself
-
-#### `dev-grooming-docs/`
-
-- appears to hold internal notes or prompt material
-- not part of the runtime contract
-
-### `src/commands`
-
-Purpose:
-
-- CLI entrypoints for platform operations
-
-Notable responsibilities:
-
-- seed metadata and system data
-- refresh generated module/model code
-- remove fields
-- load test data
-- run metadata-driven tests
-- ingest metadata into AI/RAG systems
-- print environment/app info
-- manage fixture setup and teardown
-
-Why it matters:
-
-- this folder is the operational shell around the platform
-- it is one of the strongest signals that the framework is not just a runtime; it also owns scaffolding, maintenance, and developer workflows
-
-Spring Boot implication:
-
-- this likely maps to a combination of:
-  - CLI commands via Spring Shell, Picocli, or standalone tooling
-  - Gradle/Maven plugins or generators
-  - operational admin commands
-
-### `src/config`
-
-Purpose:
-
-- configuration assembly
-
-Current contents:
-
-- cache configuration (`cache.options.ts`)
-
-Why it matters:
-
-- small folder, but it centralizes how infrastructure components are registered
-
-### `src/constants`
-
-Purpose:
-
-- shared constant definitions for errors, success messages, and chatter message semantics
-
-Why it matters:
-
-- gives the core consistent platform-wide language for API behavior and event semantics
-
-### `src/controllers`
-
-Purpose:
-
-- platform-owned HTTP endpoints for metadata, IAM, runtime operations, dashboarding, imports/exports, chatter, settings, and supporting entities
-
-Representative controller groups:
-
-- metadata: `module-metadata`, `model-metadata`, `field-metadata`, `view-metadata`, `action-metadata`, `menu-item-metadata`, `permission-metadata`, `role-metadata`, `security-rule`
-- IAM: `authentication`, `otp-authentication`, `google-authentication`, `user`, `user-view-metadata`, `user-activity-history`, `agent-session`, `agent-event`, `api-key` related flows through services
-- runtime/admin: `setting`, `info`, `test`, `test-queue`, `service`
-- integration/content: `media`, `sms-template`, `email-template`, `mq-message`, `mq-message-queue`
-- analytics: `dashboard`, `dashboard-question`, `dashboard-variable`, `dashboard-layout`, `dashboard-question-sql-dataset-config`
-- data movement: `import-transaction`, `import-transaction-error-log`, `export-template`, `export-transaction`
-- collaboration: `chatter-message`, `chatter-message-details`
-
-Observations:
-
-- many controllers expose a direct CRUD-style contract over platform entities
-- some route names still carry `FIXME` comments about naming consistency
-- the core package exposes a lot of “admin runtime APIs,” not just reusable service classes
-
-Spring Boot implication:
-
-- these map naturally to `@RestController` classes
-- but the bigger question is which of these remain part of a reusable core starter versus which should become generated per project
-
-### `src/decorators`
-
-Purpose:
-
-- discovery and extension annotations
-
-Important categories:
-
-- auth/request decorators: `public`, `auth`, `active-user`, `solid-request-context`, `roles`
-- provider registration decorators:
-  - `selection-provider`
-  - `computed-field-provider`
-  - `scheduled-job-provider`
-  - `mail-provider`
-  - `sms-provider`
-  - `whatsapp-provider`
-  - `dashboard-question-data-provider`
-  - `dashboard-selection-provider`
-  - `security-rule-config-provider`
-  - `settings-provider`
-  - `extension-user-creation-provider`
-  - `solid-database-module`
-- validation/guardrails decorators:
-  - `disallow-in-production`
-  - `solid-password`
-  - `is-not-in-enum`
-
-Why it matters:
-
-- this folder is one of the key extension seams of the framework
-- decorators are how consuming projects advertise custom providers back to the core runtime
-
-Spring Boot implication:
-
-- this becomes annotations plus bean discovery, often backed by:
-  - custom `@Qualifier` patterns
-  - `BeanPostProcessor` / classpath scanning
-  - Spring stereotypes and registries
-
-### `src/dtos`
-
-Purpose:
-
-- request/response shape definitions for the entire platform
-
-Coverage includes:
-
-- metadata creation and update
-- CRUD query/filter/grouping DTOs
-- IAM and OTP flows
-- import/export payloads
-- dashboard configuration
-- saved filters, templates, transactions, settings, chatter, sequences, agent events, and more
-
-Why it matters:
-
-- the DTO set describes the public API surface of the platform almost as much as the controllers do
-- a Spring Boot rewrite will need a substantial equivalent model in request/response classes and validators
-
-### `src/entities`
-
-Purpose:
-
-- core persistence model for the platform itself
-
-Representative entity groups:
-
-- metadata and navigation: `ModuleMetadata`, `ModelMetadata`, `FieldMetadata`, `ViewMetadata`, `ActionMetadata`, `MenuItemMetadata`
-- security/IAM: `User`, `RoleMetadata`, `PermissionMetadata`, `SecurityRule`, `UserApiKey`, `UserViewMetadata`, `UserActivityHistory`
-- platform runtime: `Setting`, `Locale`, `ModelSequence`
-- communications: `EmailTemplate`, `SmsTemplate`, `Media`, `MediaStorageProviderMetadata`, `EmailAttachment`
-- queues and async operations: `MqMessage`, `MqMessageQueue`, `ScheduledJob`, `ImportTransaction`, `ImportTransactionErrorLog`, `ExportTransaction`
-- dashboards and analytics: `Dashboard`, `DashboardQuestion`, `DashboardVariable`, `DashboardLayout`, `DashboardQuestionSqlDatasetConfig`
-- collaboration and AI: `ChatterMessage`, `ChatterMessageDetails`, `AiInteraction`, `AgentSession`, `AgentEvent`
-
-Base entity model:
-
-- `CommonEntity`
-- `LegacyCommonEntity`
-- `LegacyCommonWithIdEntity`
-
-Why it matters:
-
-- these entities define the shared schema every SolidX backend expects around the business modules
-- this is part of the durable “platform contract” and should likely survive a Java port almost one-for-one conceptually
-
-### `src/enums`
-
-Purpose:
-
-- small enum support surface
-
-Current visible usage:
-
-- authentication mode / auth type support
-
-### `src/factories`
-
-Purpose:
-
-- runtime provider resolution for email, SMS, and WhatsApp
-
-Why it matters:
-
-- this is the indirection layer between settings/registry state and concrete transport implementation
-
-Spring Boot implication:
-
-- likely maps to strategy factories over beans selected by configuration or provider name
-
-### `src/filters`
-
-Purpose:
-
-- exception normalization for HTTP
-
-Current visible item:
-
-- `http-exception.filter.ts`
-
-Why it matters:
-
-- core owns platform-wide API error behavior
-
-### `src/guards`
-
-Purpose:
-
-- request authorization and authentication policy enforcement
-
-Current guards:
-
-- `authentication.guard`
-- `access-token.guard`
-- `api-key.guard`
-- `permissions.guard`
-- `roles.guard`
-
-Key behavior:
-
-- `AuthenticationGuard` combines bearer/API-key auth and supports public routes
-- it also checks whether a permission is available to the `Public` role
-- it populates CLS request context with IP and user-agent
-
-Why it matters:
-
-- this is one of the cross-cutting runtime pillars of the platform
-
-### `src/helpers`
-
-Purpose:
-
-- internal platform mechanics and generation helpers
-
-Important sub-areas:
-
-- code generation and shelling: `command.service`, `schematic.service`
-- metadata support: `module-metadata-helper.service`, `model-metadata-helper.service`
-- runtime registry: `solid-registry.ts`
-- field behavior: `field-crud-managers/*`
-- mapping/error/date/media helpers
-- microservice adapter helpers
-- module discovery helpers
-
-Important detail:
-
-- the field CRUD managers are central to the metadata-driven engine
-- each field type has logic for validation and transformation
-- relation, media, computed, selection, numeric, text, password, and JSON handling are all delegated through this layer
-
-Spring Boot implication:
-
-- this becomes a major subsystem, likely implemented with:
-  - field-type strategy interfaces
-  - validation/transform pipelines
-  - registry-driven dispatch
-
-### `src/interceptors`
-
-Purpose:
-
-- cross-cutting request/response behavior
-
-Current items:
-
-- logging interceptor
-- response wrapper interceptor
-
-Why it matters:
-
-- these shape consistent API behavior across the platform
-
-### `src/interfaces`
-
-Purpose:
-
-- core runtime contracts
-
-Visible examples:
-
-- active user context
-- queue/message interfaces
-
-Broader use:
-
-- the package also exports many interfaces from `src/interfaces.ts` that define provider contracts for scheduled jobs, selection providers, dashboard providers, security rule config providers, and more
-
-### `src/jobs`
-
-Purpose:
-
-- concrete queue publishers, subscribers, and queue option definitions
-
-Subfolders:
-
-- `database/`
-- `rabbitmq/`
-- `redis/`
-
-Coverage:
-
-- email delivery
-- SMS delivery
-- OTP
-- WhatsApp
-- chatter
-- code generation
-- computed field evaluation
-- MCP trigger handling
-- test queue flows
-
-Why it matters:
-
-- the platform abstracts logical jobs from physical transport
-- the same business intention can be backed by DB, Redis, or RabbitMQ implementations
-
-Spring Boot implication:
-
-- this is a major area that needs conscious redesign
-- Java equivalents might involve:
-  - Spring events for local async
-  - RabbitMQ/Kafka integrations
-  - Redis streams or lists
-  - DB-backed outbox/job tables
-
-### `src/listeners`
-
-Purpose:
-
-- application event listeners
-
-Current visible item:
-
-- user registration listener
-
-Why it matters:
-
-- the pattern exists, but this is a relatively small surface compared with subscribers and jobs
-
-### `src/mappers`
-
-Purpose:
-
-- mapping between persistence objects and response DTOs/view models
-
-Current visible items:
-
-- dashboard mapper
-- list-of-values mapper
-
-### `src/passport-strategies`
-
-Purpose:
-
-- Passport-based auth strategy integration
-
-Current visible item:
-
-- Google OAuth strategy
-
-Spring Boot implication:
-
-- this becomes Spring Security OAuth2 client/resource-server configuration
-
-### `src/repository`
-
-Purpose:
-
-- repository layer over core entities plus shared repository behavior
-
-Most important class:
-
-- `SolidBaseRepository<T>`
-
-Key behavior from `solid-base.repository.ts`:
-
-- repositories are request-context aware
-- security rules are applied automatically to query builders
-- plain `createQueryBuilder()` is intentionally disabled
-- `find`, `findOne`, `count`, `sum`, `average`, `minimum`, `maximum`, and other methods are routed through security-aware query construction
-
-Why it matters:
-
-- this is one of the defining architectural choices of the framework
-- row-level security is enforced in the repository abstraction, not left to each service/controller
-
-Spring Boot implication:
-
-- a JPA repository layer alone is not enough
-- you need a security-aware query abstraction or specification builder that guarantees rule enforcement centrally
-
-### `src/seeders`
-
-Purpose:
-
-- bootstrapping platform metadata and standard data
-
-Current visible responsibilities:
-
-- core metadata seed
-- system fields seed
-- permission metadata seed
-- module test data support
-- seeded email/SMS templates
-
-Why it matters:
-
-- the framework assumes some platform entities are initialized by seeding
-- this is part of environment bootstrapping, not an optional extra
-
-### `src/services`
-
-Purpose:
-
-- the main behavior layer of the platform
-
-This is the single most important folder in the package.
-
-Major groups inside `services/`:
-
-#### CRUD and metadata services
-
-- `crud.service.ts`
-- `crud-helper.service.ts`
-- `module-metadata.service.ts`
-- `model-metadata.service.ts`
-- `field-metadata.service.ts`
-- `view-metadata.service.ts`
-- `action-metadata.service.ts`
-- `menu-item-metadata.service.ts`
-- `permission-metadata.service.ts`
-- `role-metadata.service.ts`
-- `security-rule.service.ts`
-
-Responsibilities:
-
-- generic CRUD engine
-- filter parsing and query construction
-- metadata create/update/read flows
-- synchronization between DB metadata and JSON files
-- code refresh/generation triggers
-
-Important behavior:
-
-- `CRUDService<T>` is the generic business CRUD base used by generated app services
-- it loads model metadata, validates permissions, dispatches per-field managers, stores media, and handles generic read/update/delete logic
-- `ModuleMetadataService` and `ModelMetadataService` are dual-mode services: they update the database and also maintain metadata JSON files on disk
-
-This DB + filesystem duality is a defining SolidX behavior.
-
-#### IAM and security services
-
-- `authentication.service.ts`
-- `api-key.service.ts`
-- `user.service.ts`
-- `request-context.service.ts`
-- `refresh-token-ids-storage.service.ts`
-- `sso-code-storage.service.ts`
-- `hashing.service.ts`
-- `bcrypt.service.ts`
-- `encryption.service.ts`
-
-Responsibilities:
-
-- sign-up, sign-in, forgot/reset password
-- OTP and passwordless patterns
-- refresh token invalidation
-- user lifecycle and account lockout behavior
-- request identity propagation
-- hashing and encryption
-- extension-user creation through registry-discovered providers
-
-Notable design point:
-
-- authentication is highly settings-driven and provider-driven rather than hard-coded to one flow
-
-#### Communication providers
-
-- `mail/*`
-- `sms/*`
-- `whatsapp/*`
-- `short-url/*`
-
-Responsibilities:
-
-- email via SMTP or Elastic Email
-- SMS via Twilio and MSG91
-- WhatsApp via MSG91 and 3Sixty
-- URL shortening
-
-These are transport integrations behind factories and decorators.
-
-#### Storage and media services
-
-- `file/*`
-- `media.service.ts`
-- `mediaStorageProviders/*`
-- `textract.service.ts`
-
-Responsibilities:
-
-- local disk and S3 file storage
-- media persistence
-- storage path building
-- OCR via AWS Textract
-
-#### Import/export and documents
-
-- `import-transaction.service.ts`
-- `import-transaction-error-log.service.ts`
-- `export-transaction.service.ts`
-- `export-template.service.ts`
-- `excel.service.ts`
-- `csv.service.ts`
-- `pdf.service.ts`
-
-Responsibilities:
-
-- create import templates
-- infer mapping and instructions
-- process CSV/XLSX import transactions
-- generate exports and documents
-
-This is a strong enterprise feature area.
-
-#### Dashboard and analytics
-
-- `dashboard.service.ts`
-- `dashboard-question.service.ts`
-- `dashboard-variable.service.ts`
-- `dashboard-layout.service.ts`
-- `dashboard-question-sql-dataset-config.service.ts`
-- `dashboard-selection-providers/*`
-- `question-data-providers/*`
-- `sql-expression-resolver.service.ts`
-
-Responsibilities:
-
-- dashboard metadata management
-- SQL-backed question datasets
-- runtime variable substitution
-- data shaping for chart/table widgets
-
-Important behavior:
-
-- dashboards are SQL-driven, not an ORM-only abstraction
-- data providers translate SQL results into frontend-oriented visualization payloads
-
-Spring Boot implication:
-
-- preserve this as a first-class analytics subsystem, probably using `JdbcTemplate`, jOOQ, or a carefully controlled SQL execution layer
-
-#### Queues and asynchronous orchestration
-
-- `queues/*`
-- `poller.service.ts`
-- queue publisher factory
-
-Responsibilities:
-
-- abstract queue implementations
-- standardize publisher/subscriber contracts
-- allow different queue backends without rewriting business logic
-
-#### Scheduled jobs
-
-- `scheduled-jobs/scheduler.service.ts`
-- `scheduled-job.service.ts`
-- scheduled job selection providers
-
-Responsibilities:
-
-- persist job definitions
-- compute next run time
-- run registry-discovered job handlers
-- support custom cron expressions and filters via environment controls
-
-Important behavior:
-
-- jobs are runtime-configurable data, not only code
-
-#### Computed fields and dynamic selections
-
-- `computed-fields/*`
-- `selection-providers/*`
-
-Responsibilities:
-
-- compute values during persistence or subscriber flows
-- supply runtime options for dynamic selection fields
-- enable dashboard variable/provider selection
-
-Why it matters:
-
-- this is part of the metadata execution engine, not just UI support
-
-#### AI and generation support
-
-- `genai/*`
-- `solid-ts-morph.service.ts`
-- `solid-introspect.service.ts`
-- `database/database-bootstrap.service.ts`
-
-Responsibilities:
-
-- metadata ingestion into RAG systems
-- MCP-style dashboard generation handlers
-- AST/code introspection support
-- platform code generation and introspection support
-
-Why it matters:
-
-- SolidX is positioning itself as AI-native, and these services are the beginning of that runtime/tooling bridge
-
-### `src/subscribers`
-
-Purpose:
-
-- TypeORM subscribers for platform-side side effects and metadata synchronization
-
-Key areas:
-
-- audit stamping
-- created/updated by tracking
-- computed field evaluation
-- soft delete handling
-- metadata and dashboard related reactions
-- security rule and scheduled job synchronization
-
-Why it matters:
-
-- a lot of platform behavior is evented off ORM lifecycle hooks
-- this will be one of the most delicate migration areas for Spring Boot
-
-Spring Boot implication:
-
-- likely split across:
-  - JPA entity listeners
-  - domain events
-  - application services
-  - async jobs
-
-### `src/testing`
-
-Purpose:
-
-- metadata-driven testing framework
-
-Structure suggests:
-
-- adapters for API and Playwright UI
-- a scenario/spec registry
-- runtime context, interpolation, timeout handling, steps, reporter
-- example specs and metadata
-
-Important point:
-
-- testing is treated as a first-class platform capability
-- this is unusual for a framework core and should be considered a genuine product feature
-
-Spring Boot implication:
-
-- this may remain external tooling rather than live inside the Java backend
-- but the contracts for metadata-driven test specs probably should remain stable
-
-### `src/transformers`
-
-Purpose:
-
-- TypeORM/data conversion helpers
-
-Examples:
-
-- booleans
-- arrays
-- integers
-- datetimes
-- local date-time transformer
-
-Why it matters:
-
-- these encapsulate database quirks and value normalization
-
-### `src/validators`
-
-Purpose:
-
-- custom validation helpers
-
-Current visible item:
-
-- parsable integer validation
-
-## Functionality Grouped by Classification
-
-This section reorganizes the code by platform capability rather than folder.
-
-### 1. Platform Kernel and Runtime Composition
-
-Primary locations:
-
-- `solid-core.module.ts`
-- `solid-core-cli.module.ts`
-- `config/`
-- `interceptors/`
-- `filters/`
-
-Functionality:
-
-- global runtime wiring
-- HTTP concerns
-- cache/JWT/CLS/static media/bootstrap setup
-- CLI composition
-
-### 2. Metadata and Code Generation System
-
-Primary locations:
-
-- `services/module-metadata.service.ts`
-- `services/model-metadata.service.ts`
-- `services/field-metadata.service.ts`
-- `helpers/schematic.service.ts`
-- `helpers/module-metadata-helper.service.ts`
-- `helpers/model-metadata-helper.service.ts`
-- `commands/refresh-*`
-- `commands/remove-fields.command.ts`
-
-Functionality:
-
-- manage module/model/field metadata
-- keep metadata persisted both in DB and JSON files
-- scaffold or refresh generated code
-- maintain inverse relation metadata
-- create default menus/actions/views
-
-This is the heart of the metadata-first framework story.
-
-### 3. Generic Data Access and CRUD Engine
-
-Primary locations:
-
-- `services/crud.service.ts`
-- `services/crud-helper.service.ts`
-- `helpers/field-crud-managers/*`
-- `repository/solid-base.repository.ts`
-
-Functionality:
-
-- generic create/read/update/delete
-- permission checks
-- metadata-aware validation and transformation
-- relation/media/computed/dynamic selection handling
-- filtering, sorting, pagination, grouping
-- security-aware repository access
-
-This is the single most important subsystem to preserve in any Java rewrite.
-
-### 4. Identity, Authentication, and Security
-
-Primary locations:
-
-- `services/authentication.service.ts`
-- `services/user.service.ts`
-- `services/api-key.service.ts`
-- `services/request-context.service.ts`
-- `guards/*`
-- `decorators/public.decorator.ts`
-- `decorators/auth.decorator.ts`
-- `repository/security-rule.repository.ts`
-- `services/security-rule.service.ts`
-
-Functionality:
-
-- login/signup/password reset
-- bearer and API-key auth
-- OTP/passwordless support
-- Google OAuth
-- request identity propagation
-- RBAC and row-level security rules
-- security rule provider extension points
-
-### 5. Platform Metadata for Admin UX and Navigation
-
-Primary locations:
-
-- `entities/*Metadata*.entity.ts`
-- `services/view-metadata.service.ts`
-- `services/action-metadata.service.ts`
-- `services/menu-item-metadata.service.ts`
-- `services/permission-metadata.service.ts`
-- `services/role-metadata.service.ts`
-
-Functionality:
-
-- describes module structure for the admin UI
-- defines views, actions, menus, permissions, and roles
-- acts as the backend source of truth that `solid-core-ui` consumes
-
-### 6. Storage, Media, and Document Processing
-
-Primary locations:
-
-- `services/file/*`
-- `services/media.service.ts`
-- `services/mediaStorageProviders/*`
-- `services/textract.service.ts`
-
-Functionality:
-
-- store and serve files
-- abstract local vs S3 storage
-- manage media entity references
-- OCR/document extraction support
-
-### 7. Communications and External Messaging
-
-Primary locations:
-
-- `services/mail/*`
-- `services/sms/*`
-- `services/whatsapp/*`
-- `factories/*`
-- `jobs/*` for delivery backends
-
-Functionality:
-
-- template-backed email
-- SMS and OTP delivery
-- WhatsApp delivery
-- provider-swappable transport resolution
-
-### 8. Import, Export, and Operational Data Movement
-
-Primary locations:
-
-- `services/import-transaction.service.ts`
-- `services/export-transaction.service.ts`
-- `services/export-template.service.ts`
-- `services/excel.service.ts`
-- `services/csv.service.ts`
-
-Functionality:
-
-- import templates
-- import mappings and validation instructions
-- background import/export workflows
-- transaction logging and error tracking
-
-### 9. Dashboards and Analytics
-
-Primary locations:
-
-- `services/dashboard*.service.ts`
-- `services/question-data-providers/*`
-- `services/dashboard-selection-providers/*`
-- `services/sql-expression-resolver.service.ts`
-- dashboard entities/controllers/repositories
-
-Functionality:
-
-- metadata-driven dashboards
-- SQL-backed widgets
-- variable substitution
-- chart/table/meter payload shaping
-
-### 10. Scheduling and Background Automation
-
-Primary locations:
-
-- `services/scheduled-jobs/*`
-- `services/scheduled-job.service.ts`
-- `jobs/*`
-- `decorators/scheduled-job-provider.decorator.ts`
-
-Functionality:
-
-- runtime-managed scheduled jobs
-- multiple async transports
-- pluggable job handler discovery
-
-### 11. Collaboration, Activity, and Audit
-
-Primary locations:
-
-- `services/chatter-message*.service.ts`
-- `entities/chatter-*`
-- `services/user-activity-history.service.ts`
-- `subscribers/audit.subscriber.ts`
-- `subscribers/created-by-updated-by.subscriber.ts`
-
-Functionality:
-
-- per-record collaboration streams
-- activity tracking
-- audit behavior
-- event-driven change capture
-
-### 12. AI, MCP, and Introspection Tooling
-
-Primary locations:
-
-- `services/genai/*`
-- `commands/ingest.command.ts`
-- `services/solid-introspect.service.ts`
-- `services/solid-ts-morph.service.ts`
-
-Functionality:
-
-- ingest module metadata into RAG/search systems
-- AI-assisted dashboard generation handlers
-- source introspection and code-awareness support
-
-### 13. Testing and Quality Tooling
-
-Primary locations:
-
-- `testing/*`
-- `commands/run-tests.command.ts`
-- `commands/test-data.command.ts`
-- `commands/fixtures/*`
-
-Functionality:
-
-- metadata-driven API/UI testing
-- reusable test steps and reporters
-- fixture lifecycle support
-
-## What Seems Most Core vs Most Replaceable
-
-### Most core to preserve in a Spring Boot version
-
-- metadata model and JSON structure
-- generic CRUD behavior driven by field metadata
-- row-level security model and repository enforcement
-- request context propagation
-- extension registry/provider model
-- import/export transaction model
-- dashboard model and SQL dataset execution pattern
-- scheduled job model
-- communications abstraction model
-
-### More implementation-specific to NestJS/TypeORM
-
-- Passport strategy plumbing
-- global guard/interceptor wiring style
-- TypeORM subscribers exactly as written
-- Angular schematics-based code generation hooks
-- some CLI composition details
-- CLS and Nest module discovery specifics
-
-## Spring Boot Translation Lens
-
-The cleanest way to think about the Java version is not “rewrite NestJS classes in Java.” It is:
-
-1. Preserve the platform contracts.
-2. Re-implement the runtime mechanisms in Spring-native ways.
-
-### Likely Spring Boot equivalents
-
-#### Module composition
-
-Current:
-
-- global Nest module with exported providers
-
-Java analogue:
-
-- Spring Boot starter or platform library
-- auto-configuration modules
-- conditional beans for optional features
-
-#### Entity/repository model
-
-Current:
-
-- TypeORM entities
-- custom repositories extending `SolidBaseRepository`
-
-Java analogue:
-
-- JPA entities
-- Spring Data repositories plus a custom base repository layer
-- central security-aware query/specification abstraction
-
-#### Request context
-
-Current:
-
-- `nestjs-cls`
-
-Java analogue:
-
-- request-scoped beans
-- `SecurityContextHolder`
-- servlet filter/interceptor backed context holder
-
-#### CRUD engine
-
-Current:
-
-- generic `CRUDService<T>` plus field-type managers
-
-Java analogue:
-
-- generic application service layer
-- field handler strategy registry
-- validation/transform pipeline
-
-#### Provider discovery
-
-Current:
-
-- decorators + `SolidRegistry`
-
-Java analogue:
-
-- annotations + bean scanning + registry beans
-
-#### Subscribers and lifecycle hooks
-
-Current:
-
-- TypeORM subscribers
-
-Java analogue:
-
-- JPA entity listeners
-- domain events
-- application services
-- async workers where hooks become too heavy
-
-#### Queues
-
-Current:
-
-- database, Redis, RabbitMQ implementations
-
-Java analogue:
-
-- Spring AMQP / Redis / DB-backed job table or outbox
-
-#### CLI and code generation
-
-Current:
-
-- `nest-commander` + schematics
-
-Java analogue:
-
-- Spring Shell or standalone generator tooling
-- possibly keep generation as an external multi-language tool if that is simpler
-
-### Recommended boundary for the Java effort
-
-Treat these as separate workstreams:
-
-1. Platform contract preservation
-   - metadata JSON shape
-   - REST semantics expected by `solid-core-ui`
-   - security rule model
-   - dashboard payloads
-   - import/export transaction model
-
-2. Spring runtime kernel
-   - bootstrapping
-   - request context
-   - auth/security
-   - CRUD engine
-   - repository base layer
-   - provider registry
-
-3. Operational subsystem ports
-   - scheduling
-   - queues
-   - notifications
-   - file/media storage
-   - AI tooling
-
-4. Tooling story
-   - metadata generation
-   - CLI replacement
-   - test runner compatibility
-
-## Suggested Decomposition for the Java Backend
-
-If SolidX moves to Spring Boot, a close structural equivalent might look like:
-
-- `solidx-core-boot-starter`
-  - auto-configuration
-  - security setup
-  - request context
-  - shared controllers if still desired
-
-- `solidx-core-domain`
-  - core entities
-  - DTOs
-  - provider interfaces
-  - metadata contracts
-
-- `solidx-core-runtime`
-  - CRUD engine
-  - metadata services
-  - dashboard engine
-  - import/export
-  - scheduler
-  - registry
-
-- `solidx-core-integrations`
-  - email/SMS/WhatsApp providers
-  - file storage providers
-  - OCR integrations
-  - queue implementations
-
-- `solidx-core-cli` or external generator
-  - scaffolding
-  - seed/test/import tools
-
-This would mirror the conceptual layering already present in the TypeScript package, but with clearer packaging boundaries.
-
-## Key Conclusions
-
-1. `solid-core-module` is the backend platform kernel of SolidX, not just a shared utility library.
-2. The framework is deeply metadata-driven, but not metadata-only. It always combines metadata with generated Nest code.
-3. The most valuable reusable concepts are the metadata model, CRUD engine, repository security enforcement, provider registry, and operational platform services.
-4. The strongest coupling to NestJS/TypeORM exists in module wiring, guards/interceptors, subscribers, decorators, and generation tooling.
-5. A Spring Boot version should preserve behavior and contracts first, and only then choose Java-native mechanisms for implementing them.
-
-## Appendix: Representative Files Reviewed
-
-- Core composition:
-  - `[/Users/harishpatel/Code/javascript/solid-core-module/src/solid-core.module.ts](/Users/harishpatel/Code/javascript/solid-core-module/src/solid-core.module.ts)`
-  - `[/Users/harishpatel/Code/javascript/solid-core-module/src/solid-core-cli.module.ts](/Users/harishpatel/Code/javascript/solid-core-module/src/solid-core-cli.module.ts)`
-
-- Core runtime:
-  - `[/Users/harishpatel/Code/javascript/solid-core-module/src/services/crud.service.ts](/Users/harishpatel/Code/javascript/solid-core-module/src/services/crud.service.ts)`
-  - `[/Users/harishpatel/Code/javascript/solid-core-module/src/repository/solid-base.repository.ts](/Users/harishpatel/Code/javascript/solid-core-module/src/repository/solid-base.repository.ts)`
-  - `[/Users/harishpatel/Code/javascript/solid-core-module/src/repository/security-rule.repository.ts](/Users/harishpatel/Code/javascript/solid-core-module/src/repository/security-rule.repository.ts)`
-  - `[/Users/harishpatel/Code/javascript/solid-core-module/src/services/authentication.service.ts](/Users/harishpatel/Code/javascript/solid-core-module/src/services/authentication.service.ts)`
-  - `[/Users/harishpatel/Code/javascript/solid-core-module/src/services/module-metadata.service.ts](/Users/harishpatel/Code/javascript/solid-core-module/src/services/module-metadata.service.ts)`
-  - `[/Users/harishpatel/Code/javascript/solid-core-module/src/services/model-metadata.service.ts](/Users/harishpatel/Code/javascript/solid-core-module/src/services/model-metadata.service.ts)`
-  - `[/Users/harishpatel/Code/javascript/solid-core-module/src/helpers/solid-registry.ts](/Users/harishpatel/Code/javascript/solid-core-module/src/helpers/solid-registry.ts)`
-  - `[/Users/harishpatel/Code/javascript/solid-core-module/src/helpers/schematic.service.ts](/Users/harishpatel/Code/javascript/solid-core-module/src/helpers/schematic.service.ts)`
-
-- Analytics and AI:
-  - `[/Users/harishpatel/Code/javascript/solid-core-module/src/services/question-data-providers/chartjs-sql-data-provider.service.ts](/Users/harishpatel/Code/javascript/solid-core-module/src/services/question-data-providers/chartjs-sql-data-provider.service.ts)`
-  - `[/Users/harishpatel/Code/javascript/solid-core-module/src/services/genai/ingest-metadata.service.ts](/Users/harishpatel/Code/javascript/solid-core-module/src/services/genai/ingest-metadata.service.ts)`
-
-- Scheduling:
-  - `[/Users/harishpatel/Code/javascript/solid-core-module/src/services/scheduled-jobs/scheduler.service.ts](/Users/harishpatel/Code/javascript/solid-core-module/src/services/scheduled-jobs/scheduler.service.ts)`
-
-- Consumer project examples:
-  - `[/Users/harishpatel/Code/javascript/mswipe-erp-solidx/solid-api/src/app.module.ts](/Users/harishpatel/Code/javascript/mswipe-erp-solidx/solid-api/src/app.module.ts)`
-  - `[/Users/harishpatel/Code/javascript/mswipe-erp-solidx/solid-api/src/app.service.ts](/Users/harishpatel/Code/javascript/mswipe-erp-solidx/solid-api/src/app.service.ts)`
-  - `[/Users/harishpatel/Code/javascript/mswipe-erp-solidx/solid-api/src/app-default-database.module.ts](/Users/harishpatel/Code/javascript/mswipe-erp-solidx/solid-api/src/app-default-database.module.ts)`
-  - `[/Users/harishpatel/Code/javascript/mswipe-erp-solidx/solid-api/src/cpm/cpm.module.ts](/Users/harishpatel/Code/javascript/mswipe-erp-solidx/solid-api/src/cpm/cpm.module.ts)`
-  - `[/Users/harishpatel/Code/javascript/mswipe-erp-solidx/solid-api/src/cpm/services/customer-master.service.ts](/Users/harishpatel/Code/javascript/mswipe-erp-solidx/solid-api/src/cpm/services/customer-master.service.ts)`
-  - `[/Users/harishpatel/Code/javascript/mswipe-erp-solidx/solid-api/src/cpm/repositories/customer-master.repository.ts](/Users/harishpatel/Code/javascript/mswipe-erp-solidx/solid-api/src/cpm/repositories/customer-master.repository.ts)`
-  - `[/Users/harishpatel/Code/javascript/mswipe-erp-solidx/solid-api/module-metadata/cpm/cpm-metadata.json](/Users/harishpatel/Code/javascript/mswipe-erp-solidx/solid-api/module-metadata/cpm/cpm-metadata.json)`