@solidxai/core 0.1.10-beta.3 → 0.1.10-beta.4

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

@@ -0,0 +1,1317 @@
+# 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)`