# Business Analysis - SmartStack Architecture Reference (_architecture.md)

> **Loaded by:** step-01-cadrage, step-03a-data, step-05a-handoff
> **Purpose:** Provide architectural context for relevant questions and aligned recommendations

---

## 5 Couches (Clean Architecture)

| Couche | Projet | Contenu | Impact BA |
|--------|--------|---------|-----------|
| **Domain** | `SmartStack.Domain` | Entites, enums, interfaces | Entites identifiees en discovery |
| **Application** | `SmartStack.Application` | CQRS (Commands/Queries), validations, DTOs | Use cases de la specification |
| **Infrastructure** | `SmartStack.Infrastructure` | EF Core, services externes, jobs | Integrations et contraintes techniques |
| **API** | `SmartStack.API` | Controllers REST, permissions | Endpoints et securite |
| **Web** | `smartstack-web` | React 19, pages, composants | UI/UX et navigation |

---

## Classes de Base des Entites

| Classe | Interface | Champs auto-inclus | Quand utiliser |
|--------|-----------|---------------------|----------------|
| `BaseEntity` | - | `Id` (Guid), `TenantId`, `CreatedAt`, `UpdatedAt` | **Defaut pour toute entite metier** |
| `BaseEntity` | `IAuditableEntity` | + `CreatedBy`, `UpdatedBy` | Entite avec audit complet |
| `SystemEntity` | - | `Id` (Guid), `CreatedAt` (pas de TenantId) | Entites systeme (navigation, permissions) |
| `BaseEntity` | `ISoftDeletable` | + `IsDeleted`, `DeletedBy`, `DeletedAt` | Entite avec suppression logique |
| `HierarchicalEntity` | - | + `ParentId`, `Level`, `Path` | Arborescences (categories, menus) |

> **IMPORTANT :** Ne JAMAIS proposer `CreatedBy`, `UpdatedBy`, `IsDeleted`, `TenantId` comme champs explicites — ils sont AUTOMATIQUES via la classe de base ou l'interface.

---

## Services d'Integration Disponibles

| Service | Interface | Quand le proposer |
|---------|-----------|-------------------|
| Notifications in-app | `INotificationService` | Alertes, evenements, rappels |
| Workflow automatise | `IWorkflowService` | Emails transactionnels, webhooks, actions chainees |
| Completion IA | `IAICompletionService` | Suggestions, classification, generation contenu |
| SignalR temps reel | `IHubContext<BusinessHub>` | Mises a jour en temps reel |
| Jobs planifies | Hangfire `IBackgroundJobClient` | Traitements differes, purges, imports |

---

## Conventions Base de Donnees

| Aspect | Convention | Exemple |
|--------|------------|---------|
| Schema | `core` (socle SmartStack) vs `extensions` (entites client/metier) | `core.auth_Roles`, `nav_Applications`, `supp_Tickets` |
| Tables | `{prefix}_{EntityPlural}` (prefixe domaine + PascalCase pluriel) | `auth_Users`, `nav_Applications`, `supp_Tickets` |
| Prefixes domaine | `auth_`, `nav_`, `cfg_`, `ref_`, `wkf_`, `ai_`, `loc_`, `lic_`, `tenant_`, `support_` | Pour un nouveau module metier : choisir un prefixe court (3-5 chars) |
| FK | `{Entity}Id` (ex: `ClientId`, `OrderId`) | |
| Index | `IX_{Table}_{Column}` | `IX_bik_FreeBickes_TenantId_Code` |
| Migration | 1 migration par feature, nommee via MCP (`suggest_migration`) | `extensions_v1.0.0_001_AddFreeBicke` |

---

## Conventions de Dossiers (Clean Architecture)

| Couche | Pattern de dossiers | Exemple (module FreeBicke dans business > operations) |
|--------|--------------------|---------------------------------------------------------|
| **Domain** | `{Project}.Domain/Business/{Application}/{Module}/` | `Domain/Business/Operations/FreeBicke/FreeBicke.cs` |
| **Application/DTOs** | `{Project}.Application/Business/{Application}/{Module}/DTOs/` | `Application/Business/Operations/FreeBicke/DTOs/FreeBickeDto.cs` |
| **Application/Interfaces** | `{Project}.Application/Common/Interfaces/` | `Application/Common/Interfaces/IFreeBickeService.cs` |
| **Infrastructure/Config** | `{Project}.Infrastructure/Persistence/Configurations/{Application}/{Module}/` | `Configurations/Operations/FreeBicke/FreeBickeConfiguration.cs` |
| **Infrastructure/Services** | `{Project}.Infrastructure/Services/{Application}/{Module}/` | `Services/Operations/FreeBicke/FreeBickeService.cs` |
| **Infrastructure/SeedData** | `{Project}.Infrastructure/Persistence/Seeding/Data/{Application}/{Module}/` | `Seeding/Data/Operations/FreeBicke/FreeBickeSeedData.cs` |
| **API/Controllers** | `{Project}.Api/Controllers/Business/{Application}/` | `Controllers/Business/Operations/FreeBickeController.cs` |
| **Frontend/Pages** | `web/src/pages/{application}/{module}/` | `pages/operations/freebicke/page.tsx` |
| **Frontend/i18n** | `web/src/i18n/locales/{lang}/{module}.json` | `locales/fr/freebicke.json` |

> **IMPORTANT :** Chaque module a son **propre sous-dossier** dans chaque couche. Ne JAMAIS mettre tous les fichiers a la racine d'une couche.

---

## SeedData Core (Obligatoire pour chaque feature)

> **Chaque nouvelle feature necessite des SeedData dans 5 fichiers core** pour etre fonctionnelle (navigation visible, permissions actives, roles assignes).

| # | Fichier | Contenu | Mecanisme |
|---|---------|---------|-----------|
| 1 | `NavigationModuleConfiguration.cs` | Entree module dans `nav_Modules` (HasData) | EF Core Migration |
| 2 | `NavigationTranslationConfiguration.cs` | Traductions du module (4 langues x chaque entite nav) | EF Core Migration |
| 3 | `PermissionConfiguration.cs` | Permissions CRUD + wildcards dans `nav_Permissions` (HasData) | EF Core Migration |
| 4 | `Permissions.cs` (Application layer) | Constantes compile-time pour `[RequirePermission]` | Code |
| 5 | `RolePermissionConfiguration.cs` | Associations role-permission dans `auth_RolePermissions` (HasData) | EF Core Migration |

**Roles par defaut pour chaque application (4 niveaux) :**

| Role | Permissions | Description |
|------|-------------|-------------|
| **{App} Admin** | `{app}.*` (wildcard) | Acces complet a l'application |
| **{App} Manager** | `read`, `create`, `update`, `assign` | Gestion complete sans suppression |
| **{App} Contributor** | `read`, `create`, `update` | Contribution active |
| **{App} Viewer** | `read` uniquement | Consultation seule |

> **CRITIQUE :** Si les SeedData ne sont pas crees, le module sera invisible dans la navigation et les permissions retourneront 403.

---

## Contraintes Non-Negociables

| Contrainte | Detail |
|------------|--------|
| **Multi-tenant** | `TenantId` sur toute entite metier, isolation automatique |
| **RBAC** | Permissions `{app}.{module}.{action}`, HasData pattern |
| **CQRS** | Commands (write) et Queries (read) separes via MediatR |
| **Validation** | FluentValidation pour toute commande |
| **i18n** | 4 langues obligatoires (fr, en, it, de) |
| **Soft Delete** | Pas de DELETE physique sauf purge RGPD planifiee |

---

## Outils MCP Pertinents pour le BA

| Phase BA | Outil MCP | Usage |
|----------|-----------|-------|
| Pre-research (01) | `analyze_extension_points` | Decouvrir modules/entites existants |
| Pre-research (01) | `api_docs` | Consulter la documentation API existante |
| Analyse (02) | `validate_conventions` | Verifier les noms d'entites proposes |
| Specification (03) | `generate_permissions` | Generer la matrice de permissions |
| Handoff (05) | `scaffold_extension` | Preparer le scaffolding |
