# SmartStack Layers — Execution Rules & Skill/MCP Mapping

> **Loaded by:** step-02 (planning) and step-03 (execution)
> **Purpose:** Defines per-layer folder conventions, skill/MCP tools, and verification rules.

---

## Layer 0 — Domain (sequential)

**Entities:** `Domain/Entities/{ContextPascal}/{App}/{Module}/`
**Enums:** `Domain/Enums/{ContextPascal}/{App}/{Module}/`
**Exceptions:** `Domain/Exceptions/{ContextPascal}/{App}/{Module}/`

| Action | Tool |
|--------|------|
| Create entity | MCP `scaffold_extension` (type: entity) |
| Validate | MCP `validate_conventions` |

**Rules:**
- Inherit `AuditableEntity`, implement `IHasData` for multi-tenant
- Audit fields: CreatedAt, CreatedBy, ModifiedAt, ModifiedBy
- Domain events for state changes
- Value objects for composite values

---

## Layer 0 — Infrastructure: EF Core (sequential)

**Configs:** `Infrastructure/Persistence/Configurations/{ContextPascal}/{App}/{Module}/`
**Migrations:** `Infrastructure/Persistence/Migrations/` (NEVER subdirectories)

| Action | Tool |
|--------|------|
| Create config | MCP `scaffold_extension` (type: configuration) |
| Create migration | MCP `suggest_migration` → `dotnet ef migrations add` |
| Validate | MCP `check_migrations` |

**Rules:**
- One config per entity, table name = plural
- All relationships explicitly configured
- Indexes on FKs and frequent queries
- Register DbSet in ExtensionsDbContext
- Migration name ALWAYS from MCP `suggest_migration`
- Migration flag: `-o Persistence/Migrations`

**BLOCKING:** `dotnet build --no-restore` MUST pass after migration.

---

## Layer 1 — Application (parallel with API)

**Services:** `Application/Services/{ContextPascal}/{App}/{Module}/`
**DTOs:** `Application/DTOs/{ContextPascal}/{App}/{Module}/`
**Validators:** `Application/Validators/{ContextPascal}/{App}/{Module}/`

| Action | Tool |
|--------|------|
| Create service/DTO | MCP `scaffold_extension` |
| Complex service logic | /application skill |
| Validate | MCP `validate_conventions` |

**Rules:**
- CQRS with MediatR
- FluentValidation for all commands
- DTOs separate from domain entities
- Service interfaces in Application, implementations in Infrastructure

---

## Layer 1 — API (parallel with Application)

**Controllers:** `Api/Controllers/{ContextShort}/{App}/{Entity}Controller.cs`

| Context | Controller Folder |
|---------|-------------------|
| `platform.administration` | `Admin` |
| `platform.support` | `Support` |
| `business.*` | `Business` |
| `personal.*` | `User` |

| Action | Tool |
|--------|------|
| Simple CRUD controller | MCP `scaffold_extension` |
| Complex controller | /controller skill |
| Validate | MCP `validate_security` |

**Rules:**
- `[RequirePermission(Permissions.{Module}.{Action})]` on EVERY endpoint
- NEVER use `[Authorize]` without specific permission
- Swagger XML documentation
- Return DTOs, never domain entities

---

## Layer 1 — Seed Data (parallel)

**Folder:** `Infrastructure/Persistence/Seeding/Data/{ModulePascal}/`

| Action | Tool |
|--------|------|
| Generate permissions | MCP `generate_permissions` (PRIMARY) |
| Navigation seed | Template below |
| Roles seed | Template below |
| Provider | Template below |

### Seed Data Chain (5 files)

1. **NavigationModuleSeedData.cs** — Deterministic GUIDs (SHA256), 4 languages
2. **PermissionsSeedData.cs** — MCP `generate_permissions` first, fallback template
3. **RolesSeedData.cs** — Context-based: Admin=CRUD, Manager=CRU, Contributor=CR, Viewer=R
4. **SeedConstants.cs** — Shared deterministic GUIDs
5. **{App}SeedDataProvider.cs** — Implements IClientSeedDataProvider
   - SeedNavigationAsync + SeedPermissionsAsync + SeedRolePermissionsAsync
   - DI: `services.AddScoped<IClientSeedDataProvider, {App}SeedDataProvider>()`

**FORBIDDEN:**
- `Guid.NewGuid()` → use deterministic GUIDs (SHA256)
- Missing translations (must have fr, en, it, de)
- Empty seed classes with no seeding logic

---

## Layer 2 — Frontend (parallel with I18n)

**Pages:** `src/pages/{ContextPascal}/{AppPascal}/{Module}/`
**Components:** `src/components/{Module}/`

| Action | Tool |
|--------|------|
| API client | MCP `scaffold_api_client` |
| Routes | MCP `scaffold_routes` |
| Complex pages | /ui-components skill |
| Validate routes | MCP `validate_frontend_routes` |

**Layout mapping:**

| Context | Layout | Route prefix |
|---------|--------|-------------|
| `platform.*` | `AdminLayout` | `/platform` |
| `business.*` | `BusinessLayout` | `/business` |
| `personal.*` | `UserLayout` | `/personal/myspace` |

**Components:** SmartTable, SmartFilter, EntityCard, SmartForm, StatCard (NEVER raw HTML)
**CSS:** Variables only → `bg-[var(--bg-card)]`, `text-[var(--text-primary)]`

**FORBIDDEN:**
- `src/pages/{Module}/` (flat, missing Context/App)
- `import axios` → use `@/services/api/apiClient`
- `<table>` → use SmartTable
- Hardcoded colors → use CSS variables
- Only fr/en → MUST have 4 languages

---

## Layer 2 — I18n

4 JSON files: fr, en, it, de — identical key structures.

---

## Layer 3 — Tests (sequential, if -t)

| Action | Tool |
|--------|------|
| Unit tests (domain) | MCP `scaffold_tests` (target_layer: domain) |
| Unit tests (app) | MCP `scaffold_tests` (target_layer: application) |
| Integration tests (api) | MCP `scaffold_tests` (target_layer: api, type: integration) |
| Security tests | MCP `scaffold_tests` (type: security) |
| Coverage check | MCP `analyze_test_coverage` |
| Scenarios | MCP `suggest_test_scenarios` |

**Target:** >= 80% coverage, 100% pass rate.
**Fix CODE, not tests.**
