@atlashub/smartstack-cli 3.22.0 → 3.24.0

package/dist/mcp-entry.mjs

@@ -26901,12 +26901,16 @@ async function validateNamespaces(structure, config2, result) {
       if (namespaceMatch) {
         const namespace = namespaceMatch[1];
         if (!namespace.startsWith(layer.expected)) {
+          const lastDot = namespace.lastIndexOf(".");
+          const namespaceSuffix = lastDot > 0 ? namespace.substring(lastDot + 1) : "";
+          const isValidLayerPattern = ["Domain", "Application", "Infrastructure", "Api"].some((l) => namespace.includes(`.${l}`) || namespace.endsWith(`.${l}`));
+          const severity = isValidLayerPattern ? "warning" : "error";
           result.errors.push({
-            type: "error",
+            type: severity,
             category: "namespaces",
-            message: `${layer.name} file has incorrect namespace "${namespace}"`,
+            message: `${layer.name} file has namespace "${namespace}" (expected prefix: "${layer.expected}")`,
             file: path8.relative(structure.root, file),
-            suggestion: `Should start with "${layer.expected}"`
+            suggestion: severity === "warning" ? `Client extension project detected. Namespace "${namespace}" follows Clean Architecture pattern but differs from config.` : `Should start with "${layer.expected}"`
           });
         }
       }
@@ -34496,19 +34500,32 @@ public interface I{{name}}Service
   const implementationTemplate = `using System.Threading;
 using System.Threading.Tasks;
 using System.Collections.Generic;
+using System.Linq;
+using Microsoft.EntityFrameworkCore;
 using Microsoft.Extensions.Logging;
+using SmartStack.Application.Common.Interfaces.Identity;
+using SmartStack.Application.Common.Interfaces.Persistence;
 
 namespace {{implNamespace}};
 
 /// <summary>
-/// Service implementation for {{name}} operations
+/// Service implementation for {{name}} operations.
+/// IMPORTANT: All queries MUST filter by _currentUser.TenantId for multi-tenant isolation.
+/// IMPORTANT: GetAllAsync MUST support search parameter for frontend EntityLookup component.
 /// </summary>
 public class {{name}}Service : I{{name}}Service
 {
+    private readonly IExtensionsDbContext _db;
+    private readonly ICurrentUser _currentUser;
     private readonly ILogger<{{name}}Service> _logger;
 
-    public {{name}}Service(ILogger<{{name}}Service> logger)
+    public {{name}}Service(
+        IExtensionsDbContext db,
+        ICurrentUser currentUser,
+        ILogger<{{name}}Service> logger)
     {
+        _db = db;
+        _currentUser = currentUser;
         _logger = logger;
     }
 
@@ -34516,8 +34533,12 @@ public class {{name}}Service : I{{name}}Service
     /// <inheritdoc />
     public async Task<object> {{this}}(CancellationToken cancellationToken = default)
     {
-        _logger.LogInformation("Executing {{this}}");
-        // TODO: Implement {{this}}
+        _logger.LogInformation("Executing {{this}} for tenant {TenantId}", _currentUser.TenantId);
+        // TODO: Implement {{this}} \u2014 ALL queries must filter by _currentUser.TenantId
+        // IMPORTANT: GetAllAsync MUST accept (string? search, int page, int pageSize) parameters
+        // to enable EntityLookup search on the frontend. Example:
+        //   if (!string.IsNullOrWhiteSpace(search))
+        //       query = query.Where(x => x.Name.Contains(search) || x.Code.Contains(search));
         await Task.CompletedTask;
         throw new NotImplementedException();
     }
@@ -34561,7 +34582,6 @@ async function scaffoldEntity(name, options, structure, config2, result, dryRun
   const schema = options?.schema || config2.conventions.schemas.platform;
   const entityTemplate = `using System;
 using SmartStack.Domain.Common;
-using SmartStack.Domain.Common.Interfaces;
 
 namespace {{namespace}};
 
@@ -34570,14 +34590,10 @@ namespace {{namespace}};
 {{#unless isSystemEntity}}
 /// Tenant-scoped: data is isolated per tenant
 {{else}}
-/// System entity: platform-level, no tenant isolation
+/// Platform-level entity: no tenant isolation
 {{/unless}}
 /// </summary>
-{{#if isSystemEntity}}
-public class {{name}} : SystemEntity
-{{else}}
-public class {{name}} : BaseEntity, ITenantEntity
-{{/if}}
+public class {{name}} : BaseEntity{{#unless isSystemEntity}}, ITenantEntity, IAuditableEntity{{else}}, IAuditableEntity{{/unless}}
 {
 {{#unless isSystemEntity}}
     // === MULTI-TENANT ===
@@ -34588,6 +34604,14 @@ public class {{name}} : BaseEntity, ITenantEntity
     public Guid TenantId { get; private set; }
 
 {{/unless}}
+    // === AUDIT ===
+
+    /// <summary>User who created this entity</summary>
+    public string? CreatedBy { get; set; }
+
+    /// <summary>User who last updated this entity</summary>
+    public string? UpdatedBy { get; set; }
+
 {{#if baseEntity}}
     // === RELATIONSHIPS ===
 
@@ -34599,7 +34623,7 @@ public class {{name}} : BaseEntity, ITenantEntity
     /// <summary>
     /// Navigation property to {{baseEntity}}
     /// </summary>
-    public virtual {{baseEntity}}? {{baseEntity}} { get; private set; }
+    public {{baseEntity}}? {{baseEntity}} { get; private set; }
 
 {{/if}}
     // === BUSINESS PROPERTIES ===
@@ -34613,71 +34637,38 @@ public class {{name}} : BaseEntity, ITenantEntity
     /// <summary>
     /// Factory method to create a new {{name}}
     /// </summary>
-{{#if isSystemEntity}}
+{{#unless isSystemEntity}}
+    /// <param name="tenantId">Required tenant identifier</param>
     public static {{name}} Create(
-        string code,
-        string? createdBy = null)
+        Guid tenantId)
     {
+        if (tenantId == Guid.Empty)
+            throw new ArgumentException("TenantId is required", nameof(tenantId));
+
         return new {{name}}
         {
             Id = Guid.NewGuid(),
-            Code = code.ToLowerInvariant(),
-            CreatedAt = DateTime.UtcNow,
-            CreatedBy = createdBy
+            TenantId = tenantId,
+            CreatedAt = DateTime.UtcNow
         };
     }
 {{else}}
-    /// <param name="tenantId">Required tenant identifier</param>
-    /// <param name="code">Unique code within tenant (will be lowercased)</param>
-    /// <param name="createdBy">User who created this entity</param>
-    public static {{name}} Create(
-        Guid tenantId,
-        string code,
-        string? createdBy = null)
+    public static {{name}} Create()
     {
-        if (tenantId == Guid.Empty)
-            throw new ArgumentException("TenantId is required", nameof(tenantId));
-
         return new {{name}}
         {
             Id = Guid.NewGuid(),
-            TenantId = tenantId,
-            Code = code.ToLowerInvariant(),
-            CreatedAt = DateTime.UtcNow,
-            CreatedBy = createdBy
+            CreatedAt = DateTime.UtcNow
         };
     }
-{{/if}}
+{{/unless}}
 
     /// <summary>
     /// Update the entity
     /// </summary>
-    public void Update(string? updatedBy = null)
+    public void Update()
     {
         UpdatedAt = DateTime.UtcNow;
-        UpdatedBy = updatedBy;
-    }
-
-    /// <summary>
-    /// Soft delete the entity
-    /// </summary>
-    public void SoftDelete(string? deletedBy = null)
-    {
-        IsDeleted = true;
-        DeletedAt = DateTime.UtcNow;
-        DeletedBy = deletedBy;
-    }
-
-    /// <summary>
-    /// Restore a soft-deleted entity
-    /// </summary>
-    public void Restore(string? restoredBy = null)
-    {
-        IsDeleted = false;
-        DeletedAt = null;
-        DeletedBy = null;
-        UpdatedAt = DateTime.UtcNow;
-        UpdatedBy = restoredBy;
     }
 }
 `;
@@ -34689,85 +34680,38 @@ namespace {{infrastructureNamespace}}.Persistence.Configurations{{#if configName
 
 /// <summary>
 /// EF Core configuration for {{name}}
-{{#unless isSystemEntity}}
-/// Tenant-aware: includes tenant isolation query filter
-{{else}}
-/// System entity: no tenant isolation
-{{/unless}}
 /// </summary>
 public class {{name}}Configuration : IEntityTypeConfiguration<{{name}}>
 {
     public void Configure(EntityTypeBuilder<{{name}}> builder)
     {
-        // Table name with schema and domain prefix
         builder.ToTable("{{tablePrefix}}{{name}}s", "{{schema}}");
 
-        // Primary key
         builder.HasKey(e => e.Id);
 
 {{#unless isSystemEntity}}
-        // ============================================
-        // MULTI-TENANT CONFIGURATION
-        // ============================================
-
-        // TenantId is required for tenant isolation
+        // Multi-tenant
         builder.Property(e => e.TenantId).IsRequired();
         builder.HasIndex(e => e.TenantId)
             .HasDatabaseName("IX_{{tablePrefix}}{{name}}s_TenantId");
 
-        // Tenant relationship (configured in Tenant configuration)
-        // builder.HasOne<Tenant>().WithMany().HasForeignKey(e => e.TenantId);
-
-        // Code: lowercase, unique per tenant (filtered for soft delete)
-        builder.Property(e => e.Code).HasMaxLength(100).IsRequired();
-        builder.HasIndex(e => new { e.TenantId, e.Code })
-            .IsUnique()
-            .HasFilter("[IsDeleted] = 0")
-            .HasDatabaseName("IX_{{tablePrefix}}{{name}}s_Tenant_Code_Unique");
-{{else}}
-        // Code: lowercase, unique globally (filtered for soft delete)
-        builder.Property(e => e.Code).HasMaxLength(100).IsRequired();
-        builder.HasIndex(e => e.Code)
-            .IsUnique()
-            .HasFilter("[IsDeleted] = 0")
-            .HasDatabaseName("IX_{{tablePrefix}}{{name}}s_Code_Unique");
 {{/unless}}
-
-        // Concurrency token
-        builder.Property(e => e.RowVersion).IsRowVersion();
-
-        // Audit fields
+        // Audit fields (from IAuditableEntity)
         builder.Property(e => e.CreatedBy).HasMaxLength(256);
         builder.Property(e => e.UpdatedBy).HasMaxLength(256);
-        builder.Property(e => e.DeletedBy).HasMaxLength(256);
 
 {{#if baseEntity}}
-        // ============================================
-        // RELATIONSHIPS
-        // ============================================
-
-        // Relationship to {{baseEntity}} (1:1)
+        // Relationship to {{baseEntity}}
         builder.HasOne(e => e.{{baseEntity}})
-               .WithOne()
-               .HasForeignKey<{{name}}>(e => e.{{baseEntity}}Id)
-               .OnDelete(DeleteBehavior.Cascade);
+               .WithMany()
+               .HasForeignKey(e => e.{{baseEntity}}Id)
+               .OnDelete(DeleteBehavior.Restrict);
 
-        // Index on foreign key
         builder.HasIndex(e => e.{{baseEntity}}Id)
-               .IsUnique();
+               .HasDatabaseName("IX_{{tablePrefix}}{{name}}s_{{baseEntity}}Id");
 {{/if}}
 
-        // ============================================
-        // QUERY FILTERS
-        // ============================================
-        // Note: Global query filters are applied in DbContext.OnModelCreating
-        // - Soft delete: .HasQueryFilter(e => !e.IsDeleted)
-{{#unless isSystemEntity}}
-        // - Tenant isolation: .HasQueryFilter(e => e.TenantId == _tenantId)
-        // Combined filter applied via ITenantEntity interface check
-{{/unless}}
-
-        // TODO: Add additional business-specific configuration
+        // TODO: Add business property configurations (HasMaxLength, IsRequired, indexes)
     }
 }
 `;
@@ -34813,11 +34757,11 @@ public class {{name}}Configuration : IEntityTypeConfiguration<{{name}}>
   result.instructions.push("Create migration:");
   result.instructions.push(`dotnet ef migrations add ${migrationPrefix}_vX.X.X_XXX_Add${name} --context ${dbContextName}`);
   result.instructions.push("");
-  result.instructions.push("Required fields from BaseEntity:");
-  result.instructions.push(`- Id (Guid), ${isSystemEntity ? "" : "TenantId (Guid), "}Code (string, lowercase)`);
-  result.instructions.push("- CreatedAt, UpdatedAt, CreatedBy, UpdatedBy (audit)");
-  result.instructions.push("- IsDeleted, DeletedAt, DeletedBy (soft delete)");
-  result.instructions.push("- RowVersion (concurrency)");
+  result.instructions.push("BaseEntity fields (inherited):");
+  result.instructions.push(`- Id (Guid), CreatedAt (DateTime), UpdatedAt (DateTime?)`);
+  result.instructions.push(`${isSystemEntity ? "" : "- TenantId (Guid) \u2014 from ITenantEntity"}`);
+  result.instructions.push("- CreatedBy, UpdatedBy (string?) \u2014 from IAuditableEntity");
+  result.instructions.push("- Add your own business properties (Code, Name, etc.) as needed");
   if (options?.withSeedData) {
     result.instructions.push("");
     result.instructions.push("### Seed Data");
@@ -34889,9 +34833,7 @@ public static class {{name}}SeedData
 {{#unless isSystemEntity}}
                 TenantId = (Guid?)null, // Seed data systeme sans tenant
 {{/unless}}
-                Code = ExampleCode,
                 // TODO: Ajouter les proprietes specifiques
-                IsDeleted = false,
                 CreatedAt = seedDate
             }
         };
@@ -35116,11 +35058,8 @@ async function scaffoldController(name, options, structure, config2, result, dry
   const namespace = options?.namespace || (hierarchy.controllerArea ? `${config2.conventions.namespaces.api}.Controllers.${hierarchy.controllerArea}` : `${config2.conventions.namespaces.api}.Controllers`);
   const navRoute = options?.navRoute;
   const navRouteSuffix = options?.navRouteSuffix;
-  const apiRoute = navRoute ? `api/${navRoute.replace(/\./g, "/")}${navRouteSuffix ? `/${navRouteSuffix}` : ""}` : null;
-  const routeAttribute = navRoute ? navRouteSuffix ? `[Route("${apiRoute}")]
-[NavRoute("${navRoute}", Suffix = "${navRouteSuffix}")]` : `[Route("${apiRoute}")]
-[NavRoute("${navRoute}")]` : `[Route("api/[controller]")]`;
-  const navRouteUsing = navRoute ? "using SmartStack.Api.Core.Routing;\n" : "";
+  const routeAttribute = navRoute ? navRouteSuffix ? `[NavRoute("${navRoute}", Suffix = "${navRouteSuffix}")]` : `[NavRoute("${navRoute}")]` : `[Route("api/[controller]")]`;
+  const navRouteUsing = navRoute ? "using SmartStack.Api.Routing;\n" : "";
   const controllerTemplate = `using Microsoft.AspNetCore.Authorization;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.Extensions.Logging;
@@ -35128,17 +35067,20 @@ ${navRouteUsing}
 namespace {{namespace}};
 
 /// <summary>
-/// API controller for {{name}} operations
+/// API controller for {{name}} operations.
+/// IMPORTANT: Use [RequirePermission] on each endpoint for RBAC enforcement.
 /// </summary>
 [ApiController]
 {{routeAttribute}}
 [Authorize]
 public class {{name}}Controller : ControllerBase
 {
+    private readonly I{{name}}Service _service;
     private readonly ILogger<{{name}}Controller> _logger;
 
-    public {{name}}Controller(ILogger<{{name}}Controller> logger)
+    public {{name}}Controller(I{{name}}Service service, ILogger<{{name}}Controller> logger)
     {
+        _service = service;
         _logger = logger;
     }
 
@@ -35146,21 +35088,21 @@ public class {{name}}Controller : ControllerBase
     /// Get all {{nameLower}}s
     /// </summary>
     [HttpGet]
-    public async Task<ActionResult<IEnumerable<{{name}}Dto>>> GetAll()
+    // TODO: Add [RequirePermission(Permissions.{Module}.Read)] for RBAC
+    public async Task<ActionResult<IEnumerable<object>>> GetAll(CancellationToken ct)
     {
-        _logger.LogInformation("Getting all {{nameLower}}s");
-        // TODO: Implement
-        return Ok(Array.Empty<{{name}}Dto>());
+        // TODO: Call _service.GetAllAsync(ct)
+        return Ok(Array.Empty<object>());
     }
 
     /// <summary>
     /// Get {{nameLower}} by ID
     /// </summary>
     [HttpGet("{id:guid}")]
-    public async Task<ActionResult<{{name}}Dto>> GetById(Guid id)
+    // TODO: Add [RequirePermission(Permissions.{Module}.Read)] for RBAC
+    public async Task<ActionResult<object>> GetById(Guid id, CancellationToken ct)
     {
-        _logger.LogInformation("Getting {{nameLower}} {Id}", id);
-        // TODO: Implement
+        // TODO: Call _service.GetByIdAsync(id, ct)
         return NotFound();
     }
 
@@ -35168,10 +35110,10 @@ public class {{name}}Controller : ControllerBase
     /// Create new {{nameLower}}
     /// </summary>
     [HttpPost]
-    public async Task<ActionResult<{{name}}Dto>> Create([FromBody] Create{{name}}Request request)
+    // TODO: Add [RequirePermission(Permissions.{Module}.Create)] for RBAC
+    public async Task<ActionResult<object>> Create([FromBody] object request, CancellationToken ct)
     {
-        _logger.LogInformation("Creating {{nameLower}}");
-        // TODO: Implement
+        // TODO: Call _service.CreateAsync(dto, ct)
         return CreatedAtAction(nameof(GetById), new { id = Guid.NewGuid() }, null);
     }
 
@@ -35179,10 +35121,10 @@ public class {{name}}Controller : ControllerBase
     /// Update {{nameLower}}
     /// </summary>
     [HttpPut("{id:guid}")]
-    public async Task<ActionResult> Update(Guid id, [FromBody] Update{{name}}Request request)
+    // TODO: Add [RequirePermission(Permissions.{Module}.Update)] for RBAC
+    public async Task<ActionResult> Update(Guid id, [FromBody] object request, CancellationToken ct)
     {
-        _logger.LogInformation("Updating {{nameLower}} {Id}", id);
-        // TODO: Implement
+        // TODO: Call _service.UpdateAsync(id, dto, ct)
         return NoContent();
     }
 
@@ -35190,18 +35132,13 @@ public class {{name}}Controller : ControllerBase
     /// Delete {{nameLower}}
     /// </summary>
     [HttpDelete("{id:guid}")]
-    public async Task<ActionResult> Delete(Guid id)
+    // TODO: Add [RequirePermission(Permissions.{Module}.Delete)] for RBAC
+    public async Task<ActionResult> Delete(Guid id, CancellationToken ct)
     {
-        _logger.LogInformation("Deleting {{nameLower}} {Id}", id);
-        // TODO: Implement
+        // TODO: Call _service.DeleteAsync(id, ct)
         return NoContent();
     }
 }
-
-// DTOs
-public record {{name}}Dto(Guid Id, DateTime CreatedAt);
-public record Create{{name}}Request();
-public record Update{{name}}Request();
 `;
   const context = {
     namespace,
@@ -35221,14 +35158,12 @@ public record Update{{name}}Request();
   }
   result.files.push({ path: controllerFilePath, content: controllerContent, type: "created" });
   if (navRoute) {
-    result.instructions.push("Controller created with NavRoute + explicit Route (deterministic routing).");
+    result.instructions.push("Controller created with NavRoute (route resolved from DB at startup).");
     result.instructions.push(`NavRoute: ${navRoute}${navRouteSuffix ? ` (Suffix: ${navRouteSuffix})` : ""}`);
-    result.instructions.push(`API Route: ${apiRoute}`);
     result.instructions.push("");
-    result.instructions.push("The [Route] attribute ensures deterministic API routing.");
-    result.instructions.push("The [NavRoute] attribute integrates with the navigation/permission system.");
-    result.instructions.push("Ensure the navigation path exists in the database:");
-    result.instructions.push(`  Context > Application > Module > Section matching "${navRoute}"`);
+    result.instructions.push("NavRoute resolves API routes from Navigation entities in the database.");
+    result.instructions.push("Ensure the navigation path exists (seed data required):");
+    result.instructions.push(`  Context > Application > Module matching "${navRoute}"`);
   } else {
     result.instructions.push("Controller created with traditional routing.");
     result.instructions.push("");
@@ -35416,6 +35351,27 @@ export function use{{name}}(options: Use{{name}}Options = {}) {
   const componentImportPath = hierarchy.context && hierarchy.module ? `@/components/${hierarchy.context.toLowerCase()}/${hierarchy.module.toLowerCase()}/${name}` : `./components/${name}`;
   result.instructions.push(`import { ${name} } from '${componentImportPath}';`);
   result.instructions.push(`import { use${name} } from '@/hooks/use${name}';`);
+  result.instructions.push("");
+  result.instructions.push("### IMPORTANT: Foreign Key Fields in Forms");
+  result.instructions.push("If this entity has FK fields (e.g., EmployeeId, DepartmentId):");
+  result.instructions.push("- NEVER render FK Guid fields as plain text inputs");
+  result.instructions.push("- ALWAYS use EntityLookup component from @/components/ui/EntityLookup");
+  result.instructions.push("- EntityLookup provides searchable dropdown with API-backed search");
+  result.instructions.push("- See smartstack-frontend.md section 6 for the full EntityLookup pattern");
+  result.instructions.push("");
+  result.instructions.push("Example:");
+  result.instructions.push("```tsx");
+  result.instructions.push('import { EntityLookup } from "@/components/ui/EntityLookup";');
+  result.instructions.push("");
+  result.instructions.push("<EntityLookup");
+  result.instructions.push('  apiEndpoint="/api/{context}/{app}/{related-entity}"');
+  result.instructions.push("  value={formData.relatedEntityId}");
+  result.instructions.push('  onChange={(id) => handleChange("relatedEntityId", id)}');
+  result.instructions.push('  label="Related Entity"');
+  result.instructions.push("  mapOption={(item) => ({ id: item.id, label: item.name, sublabel: item.code })}");
+  result.instructions.push("  required");
+  result.instructions.push("/>");
+  result.instructions.push("```");
 }
 async function scaffoldTest(name, options, structure, config2, result, dryRun = false) {
   const isSystemEntity = options?.isSystemEntity || false;
@@ -35810,7 +35766,7 @@ public interface I{{name}}Repository
     /// <summary>Update entity</summary>
     Task UpdateAsync({{name}} entity, CancellationToken ct = default);
 
-    /// <summary>Soft delete entity</summary>
+    /// <summary>Delete entity</summary>
     Task DeleteAsync({{name}} entity, CancellationToken ct = default);
 }
 `;
@@ -35885,8 +35841,8 @@ public class {{name}}Repository : I{{name}}Repository
     /// <inheritdoc />
     public async Task DeleteAsync({{name}} entity, CancellationToken ct = default)
     {
-        entity.SoftDelete();
-        await UpdateAsync(entity, ct);
+        _context.{{name}}s.Remove(entity);
+        await _context.SaveChangesAsync(ct);
     }
 }
 `;
@@ -57054,7 +57010,12 @@ async function scaffoldRoutes(input, config2) {
     result.instructions.push("");
     result.instructions.push("Add routes to `contextRoutes.{context}[]` with **RELATIVE** paths (no leading `/`):");
     result.instructions.push("");
+    result.instructions.push("**IMPORTANT:** Pages are lazy-loaded. Use `<Suspense fallback={<PageLoader />}>` wrapper.");
+    result.instructions.push("");
     result.instructions.push("```tsx");
+    result.instructions.push("import { lazy, Suspense } from 'react';");
+    result.instructions.push("import { PageLoader } from '@/components/ui/PageLoader';");
+    result.instructions.push("");
     result.instructions.push("const contextRoutes: ContextRouteExtensions = {");
     for (const [context, applications] of Object.entries(routeTree)) {
       result.instructions.push(`  ${context}: [`);
@@ -57063,7 +57024,7 @@ async function scaffoldRoutes(input, config2) {
           const modulePath = route.navRoute.split(".").slice(1).join("/");
           const pageEntry = pageFiles.get(route.navRoute);
           const component = pageEntry?.[0]?.componentName || `${route.navRoute.split(".").map(capitalize).join("")}Page`;
-          result.instructions.push(`    { path: '${modulePath}', element: <${component} /> },`);
+          result.instructions.push(`    { path: '${modulePath}', element: <Suspense fallback={<PageLoader />}><${component} /></Suspense> },`);
         }
       }
       result.instructions.push("  ],");
@@ -57076,7 +57037,8 @@ async function scaffoldRoutes(input, config2) {
     result.instructions.push("");
     result.instructions.push('### Pattern B: JSX Routes (if App.tsx uses `<Route path="/{context}" element={<{Layout} />}>`)');
     result.instructions.push("");
-    result.instructions.push("Insert `<Route>` children INSIDE the appropriate Layout wrapper:");
+    result.instructions.push("Insert `<Route>` children INSIDE the appropriate Layout wrapper.");
+    result.instructions.push("**IMPORTANT:** Use `<Suspense fallback={<PageLoader />}>` for lazy-loaded pages.");
     result.instructions.push("");
     for (const [context, applications] of Object.entries(routeTree)) {
       const layoutName = getLayoutName(context);
@@ -57088,7 +57050,7 @@ async function scaffoldRoutes(input, config2) {
           const modulePath = route.navRoute.split(".").slice(1).join("/");
           const pageEntry = pageFiles.get(route.navRoute);
           const component = pageEntry?.[0]?.componentName || `${route.navRoute.split(".").map(capitalize).join("")}Page`;
-          result.instructions.push(`<Route path="${modulePath}" element={<${component} />} />`);
+          result.instructions.push(`<Route path="${modulePath}" element={<Suspense fallback={<PageLoader />}><${component} /></Suspense>} />`);
         }
       }
       result.instructions.push("```");
@@ -57327,27 +57289,30 @@ function generateRouterConfig(routes, includeGuards) {
     " */",
     "",
     "import { createBrowserRouter, RouteObject } from 'react-router-dom';",
-    "import { ROUTES } from './navRoutes.generated';"
+    "import { lazy, Suspense } from 'react';",
+    "import { ROUTES } from './navRoutes.generated';",
+    "import { PageLoader } from '@/components/ui/PageLoader';"
   ];
   if (includeGuards) {
     lines.push("import { ProtectedRoute, PermissionGuard } from './guards';");
   }
   const contexts = Object.keys(routeTree);
   for (const context of contexts) {
-    lines.push(`import { ${capitalize(context)}Layout } from '../layouts/${capitalize(context)}Layout';`);
+    const name = `${capitalize(context)}Layout`;
+    lines.push(`const ${name} = lazy(() => import('../layouts/${name}').then(m => ({ default: m.${name} })));`);
   }
   lines.push("");
-  lines.push("// Page imports - customize these paths");
+  lines.push("// Page imports - lazy loaded (customize paths)");
   for (const route of routes) {
     const pageName = route.navRoute.split(".").map(capitalize).join("");
-    lines.push(`// import { ${pageName}Page } from '../pages/${pageName}Page';`);
+    lines.push(`// const ${pageName}Page = lazy(() => import('../pages/${pageName}Page').then(m => ({ default: m.${pageName}Page })));`);
   }
   lines.push("");
   lines.push("const routes: RouteObject[] = [");
   for (const [context, applications] of Object.entries(routeTree)) {
     lines.push("  {");
     lines.push(`    path: '${context}',`);
-    lines.push(`    element: <${capitalize(context)}Layout />,`);
+    lines.push(`    element: <Suspense fallback={<PageLoader />}><${capitalize(context)}Layout /></Suspense>,`);
     lines.push("    children: [");
     for (const [app, modules] of Object.entries(applications)) {
       lines.push("      {");
@@ -57575,7 +57540,9 @@ function generateClientRoutesConfig(routes, pageFiles, includeGuards) {
     "",
     "import type { RouteObject } from 'react-router-dom';",
     "import type { ContextRouteExtensions } from '@atlashub/smartstack';",
-    "import { Navigate } from 'react-router-dom';"
+    "import { lazy, Suspense } from 'react';",
+    "import { Navigate } from 'react-router-dom';",
+    "import { PageLoader } from '@/components/ui/PageLoader';"
   ];
   if (includeGuards) {
     lines.push("import { ROUTES } from './navRoutes.generated';");
@@ -57588,7 +57555,9 @@ function generateClientRoutesConfig(routes, pageFiles, includeGuards) {
     if (pageEntries) {
       for (const entry of pageEntries) {
         if (!importedComponents.has(entry.componentName)) {
-          lines.push(`import { ${entry.componentName} } from '${entry.importPath}';`);
+          lines.push(`const ${entry.componentName} = lazy(() =>`);
+          lines.push(`  import('${entry.importPath}').then(m => ({ default: m.${entry.componentName} }))`);
+          lines.push(");");
           importedComponents.add(entry.componentName);
         }
       }
@@ -57597,7 +57566,7 @@ function generateClientRoutesConfig(routes, pageFiles, includeGuards) {
   for (const route of routes) {
     if (!pageFiles.has(route.navRoute)) {
       const pageName = route.navRoute.split(".").map(capitalize).join("") + "Page";
-      lines.push(`// TODO: import { ${pageName} } from '@/pages/...';`);
+      lines.push(`// TODO: const ${pageName} = lazy(() => import('@/pages/...').then(m => ({ default: m.${pageName} })));`);
     }
   }
   lines.push("");
@@ -57626,7 +57595,7 @@ function generateClientRoutesConfig(routes, pageFiles, includeGuards) {
             lines.push(`      {`);
             lines.push(`        path: '${modulePath}',`);
             if (hasRealPage) {
-              lines.push(`        element: <PermissionGuard permissions={ROUTES['${route.navRoute}'].permissions}><${component} /></PermissionGuard>,`);
+              lines.push(`        element: <Suspense fallback={<PageLoader />}><PermissionGuard permissions={ROUTES['${route.navRoute}'].permissions}><${component} /></PermissionGuard></Suspense>,`);
             } else {
               lines.push(`        element: <PermissionGuard permissions={ROUTES['${route.navRoute}'].permissions}><div>TODO: ${component}</div></PermissionGuard>,`);
             }
@@ -57634,7 +57603,7 @@ function generateClientRoutesConfig(routes, pageFiles, includeGuards) {
           } else {
             lines.push(`      {`);
             lines.push(`        path: '${modulePath}',`);
-            lines.push(`        element: ${hasRealPage ? `<${component} />` : `<div>TODO: ${component}</div>`},`);
+            lines.push(`        element: ${hasRealPage ? `<Suspense fallback={<PageLoader />}><${component} /></Suspense>` : `<div>TODO: ${component}</div>`},`);
             lines.push(`      },`);
           }
         }
@@ -57651,7 +57620,7 @@ function generateClientRoutesConfig(routes, pageFiles, includeGuards) {
             lines.push(`  {`);
             lines.push(`    path: '${fullPath}',`);
             if (hasRealPage) {
-              lines.push(`    element: <PermissionGuard permissions={ROUTES['${route.navRoute}'].permissions}><${component} /></PermissionGuard>,`);
+              lines.push(`    element: <Suspense fallback={<PageLoader />}><PermissionGuard permissions={ROUTES['${route.navRoute}'].permissions}><${component} /></PermissionGuard></Suspense>,`);
             } else {
               lines.push(`    element: <PermissionGuard permissions={ROUTES['${route.navRoute}'].permissions}><div>TODO: ${component}</div></PermissionGuard>,`);
             }
@@ -57659,7 +57628,7 @@ function generateClientRoutesConfig(routes, pageFiles, includeGuards) {
           } else {
             lines.push(`  {`);
             lines.push(`    path: '${fullPath}',`);
-            lines.push(`    element: ${hasRealPage ? `<${component} />` : `<div>TODO: ${component}</div>`},`);
+            lines.push(`    element: ${hasRealPage ? `<Suspense fallback={<PageLoader />}><${component} /></Suspense>` : `<div>TODO: ${component}</div>`},`);
             lines.push(`  },`);
           }
         }