@atlashub/smartstack-cli 1.37.0 → 2.1.0

package/templates/skills/business-analyse/steps/step-05-handoff.md

@@ -54,27 +54,33 @@ Read: templates/tpl-handoff.md    # ~100 lines
 
 **CRITICAL: Handoff must reference ACTUAL code patterns!**
 
+> **NOTE:** Use `{project_namespace}` (from 00-context.md) instead of hardcoded "SmartStack".
+> For client projects, namespace is typically `{ProjectName}` (e.g., `demo_multitenant`).
+
 If `{economy_mode}` = false, launch parallel agents:
 
 ```
 Agent 1: Backend patterns
-  "Explore src/SmartStack.Domain/Entities/ and
-   src/SmartStack.Application/Features/ to document:
-   - Entity naming pattern
-   - CQRS handler pattern
-   - Validation pattern
-   - Repository pattern"
+  "Explore src/{project_namespace}.Domain/Business/ and
+   src/{project_namespace}.Application/Business/ to document:
+   - Entity naming pattern and folder hierarchy (Domain/{Context}/{App}/{Module}/)
+   - Service interface pattern (Application/Common/Interfaces/)
+   - DTO pattern (Application/{Context}/{App}/{Module}/DTOs/)
+   - Validation pattern"
 
 Agent 2: Frontend patterns
-  "Explore web/smartstack-web/src/pages/business/ to document:
+  "Explore web/src/pages/business/ to document:
    - Page component structure
    - API service pattern
    - i18n usage pattern
    - Form handling pattern"
 
 Agent 3: Infrastructure patterns
-  "Explore src/SmartStack.Infrastructure/ to document:
-   - EF Core configuration pattern
+  "Explore src/{project_namespace}.Infrastructure/ to document:
+   - EF Core configuration pattern (Persistence/Configurations/{Module}/)
+   - Service implementation pattern (Services/{Module}/)
+   - SeedData pattern (Persistence/Seeding/Data/{Module}/)
+   - Navigation/Permission/RolePermission seed files
    - DbContext registration
    - Migration naming convention"
 ```
@@ -87,25 +93,46 @@ If `{economy_mode}` = true:
 
 ### 5. Map Specifications to Files
 
+> **IMPORTANT:** Replace `{project_namespace}` with the actual project namespace (from 00-context.md).
+> Use the folder hierarchy `{Context}/{Application}/{Module}/` — NEVER put files at the root of a layer.
+
 **Backend files to create:**
 
 | Layer | File | Template/Pattern |
 |-------|------|------------------|
-| Domain | `src/SmartStack.Domain/Entities/Business/{Entity}.cs` | Standard entity |
-| Application | `src/SmartStack.Application/Features/{Module}/Commands/` | CQRS pattern |
-| Application | `src/SmartStack.Application/Features/{Module}/Queries/` | CQRS pattern |
-| Application | `src/SmartStack.Application/Features/{Module}/DTOs/` | Request/Response DTOs |
-| Application | `src/SmartStack.Application/Features/{Module}/Validators/` | FluentValidation |
-| Infrastructure | `src/SmartStack.Infrastructure/Persistence/Configurations/` | EF Core config |
-| API | `src/SmartStack.Api/Controllers/Business/{Module}Controller.cs` | NavRoute controller |
+| Domain | `src/{project_namespace}.Domain/Business/{Application}/{Module}/{Entity}.cs` | BaseEntity + IAuditableEntity |
+| Application/DTOs | `src/{project_namespace}.Application/Business/{Application}/{Module}/DTOs/{Entity}Dto.cs` | Record DTOs (Response, Create, Update) |
+| Application/DTOs | `src/{project_namespace}.Application/Business/{Application}/{Module}/DTOs/{Entity}MappingExtensions.cs` | Entity ↔ DTO mapping |
+| Application/Interface | `src/{project_namespace}.Application/Common/Interfaces/I{Entity}Service.cs` | Service interface |
+| Application/Permissions | `src/{project_namespace}.Application/Business/{Application}/{Module}/Permissions.cs` | Static permission constants |
+| Infrastructure/Config | `src/{project_namespace}.Infrastructure/Persistence/Configurations/{Module}/{Entity}Configuration.cs` | EF Core config + HasData |
+| Infrastructure/Service | `src/{project_namespace}.Infrastructure/Services/{Module}/{Entity}Service.cs` | Service implementation |
+| API | `src/{project_namespace}.Api/Controllers/Business/{Application}/{Module}Controller.cs` | NavRoute + RequirePermission |
+
+**SeedData files to create/modify (CRITICAL — without these, module is invisible and returns 403):**
+
+| Layer | File | Content |
+|-------|------|---------|
+> **5 mandatory seed files** for every new module. 4 are EF Core Configurations (HasData → migrations), 1 is Application layer code.
+
+| # | Layer | File | Type | Content |
+|---|-------|------|------|---------|
+| 1 | Infrastructure | `Persistence/Configurations/Navigation/NavigationModuleConfiguration.cs` | HasData (migration) | Module entry in `nav_Modules` |
+| 2 | Infrastructure | `Persistence/Configurations/Navigation/NavigationTranslationConfiguration.cs` | HasData (migration) | 4 translations (fr, en, it, de) per new nav entity |
+| 3 | Infrastructure | `Persistence/Configurations/Navigation/PermissionConfiguration.cs` | HasData (migration) | Wildcard + CRUD permissions in `nav_Permissions` |
+| 4 | Application | `Application/Business/{Application}/{Module}/Permissions.cs` | Code (compile-time) | Static constants for `[RequirePermission]` |
+| 5 | Infrastructure | `Persistence/Configurations/Authorization/RolePermissionConfiguration.cs` | HasData (migration) | Role→Permission for {App} Admin, {App} Manager, {App} Contributor, {App} Viewer |
+
+**Optional :** `Persistence/Seeding/Data/{Module}/{Entity}SeedData.cs` — Demo data for development (runtime, not migration)
 
 **Frontend files to create:**
 
 | Layer | File | Pattern |
 |-------|------|---------|
-| Pages | `web/smartstack-web/src/pages/business/{app}/{module}/` | Page components |
-| Services | `web/smartstack-web/src/services/api/{module}Api.ts` | Axios service |
-| i18n | `web/smartstack-web/src/i18n/locales/{lang}/{module}.json` | 4 languages |
+| Pages | `web/src/pages/business/{app}/{module}/page.tsx` | Page component (list + actions) |
+| Components | `web/src/components/business/{module}/` | Entity-specific components |
+| Services | `web/src/services/api/{module}Api.ts` | Axios service (typed) |
+| i18n | `web/src/i18n/locales/{lang}/{module}.json` | 4 languages (fr, en, it, de) |
 
 ---
 
@@ -116,25 +143,49 @@ For each file, provide explicit instructions:
 ```markdown
 ### Backend: {Entity}.cs
 
-**Path:** `src/SmartStack.Domain/Entities/Business/{Entity}.cs`
+**Path:** `src/{project_namespace}.Domain/Business/{Application}/{Module}/{Entity}.cs`
+
+**Reference:** Copy pattern from existing entity in same layer (use Explore agent to find)
 
-**Reference:** Copy pattern from `src/SmartStack.Domain/Entities/Business/[ExistingEntity].cs`
+**Base class:** `BaseEntity` + `IAuditableEntity` (provides Id, TenantId, CreatedAt, UpdatedAt, CreatedBy, UpdatedBy)
 
-**Properties to add:**
+**Properties to add (business properties ONLY — base class fields are automatic):**
 | Property | Type | Attributes | From BR |
 |----------|------|------------|---------|
-| Id | Guid | [Key] | - |
 | {attr1} | string | [Required, MaxLength(100)] | BR-001 |
 | {attr2} | decimal | [Precision(18,2)] | BR-002 |
-| TenantId | Guid | [Required] | Multi-tenant |
-| CreatedAt | DateTime | Audit | - |
-| UpdatedAt | DateTime | Audit | - |
+| Code | string | [Required, MaxLength(50)] | Unique per tenant |
+
+> **DO NOT add:** Id, TenantId, CreatedAt, UpdatedAt, CreatedBy, UpdatedBy — these are automatic via BaseEntity/IAuditableEntity.
 
 **Business rules to implement:**
 - BR-001: {rule} -> Implement in Validator
 - BR-002: {rule} -> Implement in Entity method
 ```
 
+```markdown
+### SeedData: Navigation + Permissions + Roles
+
+**CRITICAL: These seeds make the module visible and accessible. Without them → 403 errors.**
+
+**Step 1 — Navigation seeds:**
+- Add module entry in `NavigationModuleConfiguration.cs` (HasData)
+- Add 4 translations per nav entity in `NavigationTranslationConfiguration.cs`
+- Use deterministic GUIDs (SHA256 of full_path or sequential pattern)
+
+**Step 2 — Permission seeds:**
+- Add CRUD permissions + wildcard in `PermissionConfiguration.cs` (HasData)
+- Add compile-time constants in `Permissions.cs` (Application layer)
+
+**Step 3 — Role-Permission seeds:**
+- Add associations in `RolePermissionConfiguration.cs` (HasData)
+- Default: Admin=wildcard, Manager=read+create+update, Contributor=read+create+update, Viewer=read
+
+**Step 4 — Migration:**
+- Run MCP `suggest_migration` for naming
+- Create migration with `dotnet ef migrations add`
+```
+
 ---
 
 ### 7. Map Business Rules to Code
@@ -272,12 +323,32 @@ Ce document est un prompt autonome pour Claude Code.
 
 ## 7. POST-IMPLEMENTATION CHECKLIST
 
-- [ ] Build backend OK (`dotnet build`)
-- [ ] Build frontend OK (`pnpm build`)
+**Build & Tests:**
+- [ ] Backend build OK (`dotnet build`)
+- [ ] Frontend build OK (`pnpm build`)
 - [ ] Tests pass (`dotnet test`)
-- [ ] EF Core migration created
-- [ ] Permissions in PermissionConfiguration.cs
+
+**Folder Conventions:**
+- [ ] Domain entities in `Domain/Business/{Application}/{Module}/` (not flat)
+- [ ] Application DTOs in `Application/Business/{Application}/{Module}/DTOs/`
+- [ ] Infrastructure configs in `Configurations/{Module}/` (subfolder)
+- [ ] Infrastructure services in `Services/{Module}/` (subfolder)
+- [ ] Controller in `Controllers/Business/{Application}/`
+
+**SeedData Core (CRITICAL):**
+- [ ] Navigation module entry in `NavigationModuleConfiguration.cs` (HasData)
+- [ ] Navigation translations in `NavigationTranslationConfiguration.cs` (4 langues)
+- [ ] Permissions in `PermissionConfiguration.cs` (HasData: CRUD + wildcard)
+- [ ] Permission constants in `Permissions.cs` (Application layer)
+- [ ] Role-Permission assignments in `RolePermissionConfiguration.cs` (HasData: 4 roles)
+- [ ] EF Core migration created (includes all HasData seeds)
+
+**Frontend & i18n:**
 - [ ] i18n complete (FR, EN, IT, DE)
+- [ ] Nested routes (NOT flat routes)
+- [ ] Pages in `pages/business/{app}/{module}/`
+
+**Documentation:**
 - [ ] Documentation: `/business-analyse:6-doc-html {feature_id}`
 - [ ] Documentation manifest updated: `docs-manifest.json`
 
@@ -359,56 +430,137 @@ mkdir -p .ralph/reports
 
 **ULTRATHINK about task decomposition:**
 - Each task must be atomic (implementable in one Ralph iteration)
-- Tasks follow the SmartStack layer order: Domain → Application → Infrastructure → API → Frontend → Tests → Validation
+- Tasks follow the SmartStack layer order: Domain → Application → Infrastructure → API → Frontend → i18n → Tests → Validation
 - Conditionally include tasks based on feature scope (skip layers not present in the handoff document)
+- Each task MUST include `category`, `dependencies`, and `acceptance_criteria` (schema v2)
 
-**Conditional Task Generation Rules:**
+**Granularity Rules:**
+- 1 task per entity (domain, EF config, unit tests)
+- 1 task per entity for CQRS (commands + queries + DTOs grouped per entity)
+- 1 task per controller (API)
+- 1 task per page (frontend)
+- Max 1 entity per task — do NOT group multiple entities into a single task
+- Enums and shared value objects can be grouped in 1 task if they belong to the same module
+
+**Conditional Task Generation Rules (v2 schema):**
 
 For each layer, generate tasks ONLY if the handoff document contains specifications for that layer.
+Each task must have: `id`, `description`, `status: "pending"`, `category`, `dependencies`, `acceptance_criteria`.
 
 ```
 LAYER 1 - DOMAIN (if entities defined in handoff section 3/4):
-  Task: "Create {Entity} entity in SmartStack.Domain/Entities/Business/ with properties: {property_list}"
-  Task: "Create {Entity}Status enum if status workflow defined"
-  (One task per entity)
-
-LAYER 2 - APPLICATION (if CQRS handlers defined in handoff section 3/4):
-  Task: "Create CQRS Commands for {Entity}: {Create/Update/Delete}Command + Handler + Validator"
-  Task: "Create CQRS Queries for {Entity}: GetAll{Entity}Query, Get{Entity}ByIdQuery + Handlers"
-  Task: "Create DTOs for {Entity}: {Entity}Dto, Create{Entity}Request, Update{Entity}Request"
-  Task: "Register permissions in Permissions.cs and PermissionConfiguration.cs for business.{app}.{module}"
+  Task per entity:
+    description: "Create {Entity} entity in Domain/Business/{Application}/{Module}/{Entity}.cs with properties: {property_list}. Use BaseEntity + IAuditableEntity."
+    category: "domain"
+    dependencies: []
+    acceptance_criteria: "Entity compiles, properties match handoff spec, correct base class (BaseEntity + IAuditableEntity), correct namespace and folder hierarchy"
+  Task (if enums needed):
+    description: "Create domain enums for {Module}: {EnumList} in Domain/Enums/{Module}/"
+    category: "domain"
+    dependencies: []
+    acceptance_criteria: "Enums compile, values match handoff spec"
+
+LAYER 1.5 - SEED DATA (ALWAYS included for new modules):
+  Task 1 (navigation seeds):
+    description: "Create navigation seed data: add module entry in NavigationModuleConfiguration.cs (HasData) + 4-language translations in NavigationTranslationConfiguration.cs. Use deterministic GUIDs."
+    category: "seed-data"
+    dependencies: []
+    acceptance_criteria: "HasData entries compile, module visible in nav_Modules, translations in 4 languages (fr, en, it, de)"
+  Task 2 (permission seeds):
+    description: "Create permission seeds: add CRUD + wildcard permissions in PermissionConfiguration.cs (HasData) + compile-time constants in Permissions.cs (Application layer) for business.{app}.{module}"
+    category: "seed-data"
+    dependencies: [ID of navigation seed task]
+    acceptance_criteria: "HasData entries compile, Permissions.cs constants usable in [RequirePermission], wildcard + read/create/update/delete permissions present"
+  Task 3 (role-permission seeds):
+    description: "Create role-permission seed data: assign permissions to 4 default roles (Admin=wildcard, Manager=read+create+update, Contributor=read+create+update, Viewer=read) in RolePermissionConfiguration.cs (HasData)"
+    category: "seed-data"
+    dependencies: [ID of permission seed task]
+    acceptance_criteria: "HasData entries compile, 4 role levels assigned, Admin has wildcard access"
+
+LAYER 2 - APPLICATION (if service interfaces/DTOs defined in handoff section 3/4):
+  Task per entity:
+    description: "Create Application layer for {Entity}: Service interface (I{Entity}Service.cs), DTOs ({Entity}Dto, Create{Entity}Request, Update{Entity}Request in DTOs/), MappingExtensions"
+    category: "application"
+    dependencies: [ID of corresponding DOMAIN task for this entity]
+    acceptance_criteria: "Interface compiles, DTOs match handoff properties, mapping extensions cover all properties"
 
 LAYER 3 - INFRASTRUCTURE (if EF Core config or services in handoff):
-  Task: "Create EF Core configuration for {Entity} with HasData seed and migration"
-  Task: "Register {Entity} DbSet in ApplicationDbContext"
-  Task: "Create {Entity}Service implementing I{Entity}Service with DI registration" (if services needed)
+  Task per entity:
+    description: "Create EF Core configuration in Configurations/{Module}/{Entity}Configuration.cs with table prefix, indexes, relationships, and schema (core or extensions)"
+    category: "infrastructure"
+    dependencies: [ID of corresponding DOMAIN task for this entity]
+    acceptance_criteria: "Configuration compiles, DbSet registered in DbContext, table uses {prefix}_{Entity}s naming, indexes match handoff"
+  Task (once per module):
+    description: "Create EF Core migration for {Module} entities (includes navigation, permission, and role-permission seed data from HasData)"
+    category: "infrastructure"
+    dependencies: [IDs of ALL EF Core configuration tasks + ALL seed-data tasks]
+    acceptance_criteria: "Migration applies without errors, 3 files present (Migration.cs, Designer.cs, ModelSnapshot.cs), HasData seeds included in migration"
+  Task per service (if services needed):
+    description: "Create {Service} implementing I{Service} with DI registration"
+    category: "infrastructure"
+    dependencies: [IDs of relevant DOMAIN + APPLICATION tasks]
+    acceptance_criteria: "Service compiles, registered in DI, follows existing patterns"
 
 LAYER 4 - API (if endpoints defined in handoff section 8):
-  Task: "Create {Module}Controller with CRUD endpoints: GET, POST, GET/{id}, PUT/{id}, DELETE/{id}"
+  Task per controller:
+    description: "Create {Entity}Controller in Controllers/Business/{Application}/ with endpoints: {endpoint list}, [NavRoute('business.{app}.{module}')] + [Authorize] + [RequirePermission(Permissions.{Module}.Read)] attributes"
+    category: "api"
+    dependencies: [IDs of APPLICATION tasks for this entity + INFRASTRUCTURE migration task + seed-data permission task]
+    acceptance_criteria: "Controller compiles, endpoints respond, Swagger displays all routes, [RequirePermission] uses Permissions.cs constants (not string literals)"
 
 LAYER 5 - FRONTEND (if frontend files in handoff section 5):
-  Task: "Create {module}Api.ts API service with Axios calls"
-  Task: "Create use{Module}.ts hook with React Query + SignalR"
-  Task: "Create {Module}Page.tsx list page with EntityCard"
-  Task: "Create {Module}Form.tsx create/edit form"
-  Task: "Add routes in App.tsx for business/{app}/{module}"
+  Task (API service):
+    description: "Create web/src/services/api/{module}Api.ts API service with Axios calls for all endpoints"
+    category: "frontend"
+    dependencies: [IDs of ALL API controller tasks]
+    acceptance_criteria: "API service compiles, all endpoints covered, types match DTOs"
+  Task per page:
+    description: "Create web/src/pages/business/{app}/{module}/page.tsx with {description of page content}"
+    category: "frontend"
+    dependencies: [ID of frontend API service task]
+    acceptance_criteria: "Page renders, API calls work, navigation functional"
+  Task (routes):
+    description: "Add NESTED routes (NOT flat) in App.tsx for business/{app}/{module} and register in navigation"
+    category: "frontend"
+    dependencies: [IDs of ALL frontend page tasks]
+    acceptance_criteria: "Nested routes resolve, navigation links appear in menu, no redirect to Home"
 
 LAYER 6 - I18N (if i18n keys in handoff section 10):
-  Task: "Create i18n translation files for {module} in 4 languages (fr, en, it, de)"
+  Task:
+    description: "Create i18n translation files for {module} in 4 languages (fr, en, it, de)"
+    category: "i18n"
+    dependencies: [IDs of frontend page tasks]
+    acceptance_criteria: "4 language files created, all keys from handoff present, no missing translations"
 
 LAYER 7 - TESTS (always included):
-  Task: "Create unit tests: {Entity}ValidatorTests + {Entity}Tests"
-  Task: "Create integration tests: {Module}ControllerTests with 200, 201, 400, 403, 404 scenarios"
+  Task per entity:
+    description: "Create unit tests for {Entity}: {Entity}ValidatorTests + {Entity}Tests (entity methods)"
+    category: "test"
+    dependencies: [ID of APPLICATION task for this entity]
+    acceptance_criteria: "Tests pass, validator rules covered, entity methods tested"
+  Task per controller:
+    description: "Create integration tests for {Entity}Controller: 200, 201, 400, 403, 404 scenarios"
+    category: "test"
+    dependencies: [ID of API task for this controller]
+    acceptance_criteria: "Tests pass, all status codes covered, permission denial tested"
 
 LAYER 8 - VALIDATION (always included):
-  Task: "Run dotnet build, pnpm build, dotnet test - fix any failures"
-  Task: "Run MCP validate_conventions to verify all naming conventions"
+  Task 1:
+    description: "Run dotnet build + dotnet test - fix any build errors or test failures"
+    category: "validation"
+    dependencies: [IDs of ALL test tasks]
+    acceptance_criteria: "Build succeeds, all tests pass"
+  Task 2:
+    description: "Run MCP validate_conventions to verify all naming and structural conventions"
+    category: "validation"
+    dependencies: [ID of validation task 1]
+    acceptance_criteria: "MCP validation clean, no convention violations"
 ```
 
 **Sizing rules:**
-- Simple feature (1 entity, CRUD only): ~8-12 tasks
-- Medium feature (2-3 entities, business rules): ~15-20 tasks
-- Complex feature (multiple entities, integrations): ~20-30 tasks
+- Simple feature (1 entity, CRUD only): ~10-15 tasks
+- Medium feature (2-3 entities, business rules): ~18-25 tasks
+- Complex feature (multiple entities, integrations): ~25-35 tasks
 
 #### 12bis.3 Write prd.json
 
@@ -416,20 +568,50 @@ Write to: `.ralph/prd.json`
 
 ```json
 {
+  "$version": "2.0.0",
   "feature": "{feature_id} - {feature_description}",
+  "status": "pending",
   "created": "{ISO 8601 timestamp}",
-  "max_iterations": 30,
-  "completion_promise": "IMPLEMENTATION COMPLETE",
-  "current_iteration": 1,
-  "source": "{output_dir}/4-development-handoff.md",
+  "updated_at": "{ISO 8601 timestamp}",
+  "metadata": {
+    "cli_version": "{version from package.json}",
+    "branch": "{current git branch}",
+    "project_path": "{cwd}",
+    "mcp_servers": { "smartstack": true, "context7": true }
+  },
+  "config": {
+    "max_iterations": 30,
+    "completion_promise": "IMPLEMENTATION COMPLETE",
+    "current_iteration": 1
+  },
+  "source": {
+    "type": "ba-handoff",
+    "handoff_path": "{output_dir}/4-development-handoff.md",
+    "frd_path": "{output_dir}/3-functional-specification.md",
+    "brd_path": "{output_dir}/2-business-requirements.md"
+  },
   "tasks": [
-    { "id": 1, "description": "...", "passes": false },
-    { "id": 2, "description": "...", "passes": false }
-  ]
+    {
+      "id": 1,
+      "description": "Create {Entity} entity in Domain/Business/{Application}/{Module}/{Entity}.cs with properties: {list}",
+      "status": "pending",
+      "category": "domain",
+      "dependencies": [],
+      "acceptance_criteria": "Entity compiles, properties match handoff spec",
+      "started_at": null,
+      "completed_at": null,
+      "iteration": null,
+      "commit_hash": null,
+      "files_changed": { "created": [], "modified": [] },
+      "validation": null,
+      "error": null
+    }
+  ],
+  "history": []
 }
 ```
 
-> **Note:** The `source` field links back to the handoff document for reference. It is not read by Ralph's execution engine and is backward-compatible.
+> **Schema v2.0.0** — Compatible avec ralph-loop step-01 sans migration. Chaque tache inclut `category`, `dependencies` et `acceptance_criteria` pour un pilotage precis de l'execution.
 
 #### 12bis.4 Initialize progress.txt
 

package/templates/skills/business-analyse/templates/tpl-handoff.md

@@ -37,6 +37,9 @@ This document is a self-contained prompt for Claude Code.
 | Feature ID | {FEAT-XXX} |
 | Module | business/{application}/{module} |
 | Base Permission | `business.{app}.{module}` |
+| Project Namespace | `{project_namespace}` |
+| DB Schema | `extensions` (client entities) / `core` (navigation, permissions) |
+| Table Prefix | `{prefix}_` (e.g., `bik_`) |
 | Complexity | {Simple/Medium/Complex} |
 
 ## 2. [EXPLORE] EXISTING PATTERNS
@@ -45,42 +48,73 @@ BEFORE coding, explore these files to understand the patterns:
 
 ```
 BACKEND:
-- src/SmartStack.Domain/Entities/ → Entity structure
-- src/SmartStack.Application/Features/ → CQRS pattern
-- src/SmartStack.Infrastructure/Persistence/Configurations/ → EF Core
+- src/{project_namespace}.Domain/Business/ → Entity structure + folder hierarchy
+- src/{project_namespace}.Application/Business/ → DTOs + service interfaces
+- src/{project_namespace}.Application/Common/Interfaces/ → Service contracts
+- src/{project_namespace}.Infrastructure/Persistence/Configurations/ → EF Core configs (subfolder per module)
+- src/{project_namespace}.Infrastructure/Services/ → Service implementations (subfolder per module)
+- src/{project_namespace}.Infrastructure/Persistence/Seeding/Data/ → SeedData patterns
+
+SEED DATA (CRITICAL):
+- NavigationModuleConfiguration.cs → How modules are seeded (HasData)
+- NavigationTranslationConfiguration.cs → How translations are seeded (4 languages)
+- PermissionConfiguration.cs → How permissions are seeded (HasData)
+- RolePermissionConfiguration.cs → How role-permission mappings are seeded
 
 FRONTEND:
-- web/smartstack-web/src/pages/business/ → Existing pages
-- web/smartstack-web/src/components/ → Reusable components
-- web/smartstack-web/src/services/api/ → API calls
+- web/src/pages/business/ → Existing pages
+- web/src/components/ → Reusable components
+- web/src/services/api/ → API calls
 ```
 
 ## 3. FILES TO CREATE
 
 ### 3.1 Backend
 
-| File | Template | Description |
-|------|----------|-------------|
-| `Domain/Entities/{Entity}.cs` | Domain Entity | Properties + rules |
-| `Application/Features/{Module}/` | CQRS | MediatR handlers |
-| `Infrastructure/.../Configurations/` | EF Core | Config + HasData |
-| `Api/Controllers/Business/` | Controller | REST endpoints |
-
-### 3.2 Frontend
-
-| File | Template | Description |
-|------|----------|-------------|
-| `pages/business/{app}/{module}/` | React Page | List + detail |
-| `services/api/{module}Api.ts` | API Service | Axios calls |
-| `i18n/locales/{lang}/{module}.json` | Translations | FR, EN, IT, DE |
+| File | Path Pattern | Description |
+|------|-------------|-------------|
+| Domain Entity | `Domain/Business/{Application}/{Module}/{Entity}.cs` | BaseEntity + IAuditableEntity |
+| Service Interface | `Application/Common/Interfaces/I{Entity}Service.cs` | Service contract |
+| DTOs | `Application/Business/{Application}/{Module}/DTOs/{Entity}Dto.cs` | Response, Create, Update records |
+| Mapping | `Application/Business/{Application}/{Module}/DTOs/{Entity}MappingExtensions.cs` | Entity ↔ DTO mapping |
+| Permission Constants | `Application/Business/{Application}/{Module}/Permissions.cs` | Compile-time constants |
+| EF Configuration | `Infrastructure/Persistence/Configurations/{Module}/{Entity}Configuration.cs` | Table + indexes + HasData |
+| Service Implementation | `Infrastructure/Services/{Module}/{Entity}Service.cs` | Business logic |
+| Controller | `Api/Controllers/Business/{Application}/{Module}Controller.cs` | NavRoute + RequirePermission |
+
+### 3.2 SeedData Core (CRITICAL — without these, module is invisible and returns 403)
+
+> **5 mandatory files** for every new module (4 EF Core HasData + 1 Application code):
+
+| # | File | Layer | Content |
+|---|------|-------|---------|
+| 1 | `NavigationModuleConfiguration.cs` | Infrastructure (HasData) | Module entry in `nav_Modules` |
+| 2 | `NavigationTranslationConfiguration.cs` | Infrastructure (HasData) | 4 translations (fr, en, it, de) per nav entity |
+| 3 | `PermissionConfiguration.cs` | Infrastructure (HasData) | Wildcard + CRUD permissions in `nav_Permissions` |
+| 4 | `Permissions.cs` | Application (code) | Compile-time constants for `[RequirePermission]` |
+| 5 | `RolePermissionConfiguration.cs` | Infrastructure (HasData) | Role→Permission for {App} Admin, {App} Manager, {App} Contributor, {App} Viewer |
+
+### 3.3 Frontend
+
+| File | Path Pattern | Description |
+|------|-------------|-------------|
+| Main Page | `pages/business/{app}/{module}/page.tsx` | List + actions |
+| Components | `components/business/{module}/` | Entity-specific components |
+| API Service | `services/api/{module}Api.ts` | Typed Axios calls |
+| Translations | `i18n/locales/{lang}/{module}.json` | FR, EN, IT, DE |
 
 ## 4. DETAILED SPECIFICATIONS
 
 ### 4.1 Entity
 
+**Base class:** `BaseEntity` + `IAuditableEntity`
+**Table name:** `{prefix}_{EntityPlural}` in schema `extensions` (e.g., `extensions.bik_FreeBickes`)
+**Schema:** `extensions` for business entities, `core` for system entities (navigation, permissions)
+> DO NOT add Id, TenantId, CreatedAt, UpdatedAt, CreatedBy, UpdatedBy — these are automatic via BaseEntity + IAuditableEntity.
+
 | Attribute | Description | Required | Rules |
 |-----------|-------------|----------|-------|
-| Id | Unique identifier | Yes | GUID |
+| Code | Unique code per tenant | Yes | MaxLength(50), unique index with TenantId |
 | {attr} | {description} | {Yes/No} | {validation} |
 
 ### 4.2 API Endpoints
@@ -99,6 +133,31 @@ FRONTEND:
 |-------|------|----------------|
 | BR-001 | {rule} | {where to implement} |
 
+### 4.4 SeedData Specifications
+
+**Navigation seeds:**
+| Level | Code | Label FR | Label EN | Label IT | Label DE | Icon | Route |
+|-------|------|----------|----------|----------|----------|------|-------|
+| Module | {module} | {label_fr} | {label_en} | {label_it} | {label_de} | {Icon} | /business/{app}/{module} |
+
+**Permission seeds:**
+| Path | Level | Action | Description |
+|------|-------|--------|-------------|
+| business.{app}.{module}.* | Module | Wildcard | Full access |
+| business.{app}.{module}.read | Module | Read | View |
+| business.{app}.{module}.create | Module | Create | Create |
+| business.{app}.{module}.update | Module | Update | Modify |
+| business.{app}.{module}.delete | Module | Delete | Remove |
+
+**Role-Permission matrix:**
+| Permission | {App} Admin | {App} Manager | {App} Contributor | {App} Viewer |
+|------------|-------------|---------------|-------------------|--------------|
+| wildcard (*) | X | - | - | - |
+| read | - | X | X | X |
+| create | - | X | X | - |
+| update | - | X | X | - |
+| delete | - | - | - | - |
+
 ## 5. REQUIRED TESTS
 
 - [ ] Unit test: Entity validation
@@ -108,12 +167,29 @@ FRONTEND:
 
 ## 6. POST-IMPLEMENTATION CHECKLIST
 
+**Build & Tests:**
 - [ ] Backend build OK
 - [ ] Frontend build OK
 - [ ] Tests passing
-- [ ] EF Core migration created
-- [ ] Permissions in PermissionConfiguration.cs
+
+**Folder Conventions:**
+- [ ] Domain entities in `Domain/Business/{Application}/{Module}/`
+- [ ] Application DTOs in `Application/Business/{Application}/{Module}/DTOs/`
+- [ ] Infrastructure configs in `Configurations/{Module}/`
+- [ ] Infrastructure services in `Services/{Module}/`
+- [ ] Controller in `Controllers/Business/{Application}/`
+
+**SeedData Core (CRITICAL):**
+- [ ] Navigation module entry (HasData in NavigationModuleConfiguration.cs)
+- [ ] Navigation translations (4 languages in NavigationTranslationConfiguration.cs)
+- [ ] Permissions (HasData in PermissionConfiguration.cs: wildcard + CRUD)
+- [ ] Permission constants (Permissions.cs in Application layer)
+- [ ] Role-Permission assignments (HasData in RolePermissionConfiguration.cs: 4 roles)
+- [ ] EF Core migration created (includes all HasData seeds)
+
+**Frontend & i18n:**
 - [ ] i18n complete (4 languages)
+- [ ] Nested routes (NOT flat)
 - [ ] Documentation: `/business-analyse:6-doc-html {FEAT-XXX}`
 
 ---