## Qu'est-ce qu'un projet client SmartStack ? What is a SmartStack client project?

Un projet client SmartStack est une application metier construite sur les fondations du socle SmartStack. Le socle fournit tout ce qui est commun a une application professionnelle — authentification JWT, gestion des roles (RBAC via HasData), isolation multi-tenant, communication temps reel (SignalR), notifications et audit. Votre projet se concentre exclusivement sur votre logique metier : vos entites, vos services, vos pages.

A SmartStack client project is a business application built on top of the SmartStack foundation. The foundation provides everything common to a professional application — JWT authentication, role management (RBAC via HasData), multi-tenant isolation, real-time communication (SignalR), notifications and auditing. Your project focuses exclusively on your business logic: your entities, your services, your pages.

La separation est stricte : vous n'avez jamais besoin de toucher au code du socle. Vous etendez SmartStack en ajoutant vos propres couches, et le socle evolue independamment via les mises a jour (`ss upgrade`).

The separation is strict: you never need to touch the foundation code. You extend SmartStack by adding your own layers, and the foundation evolves independently through updates (`ss upgrade`).

💡

##### Principe fondamental

##### Core principle

Vous ne modifiez jamais les internes de SmartStack. Vous etendez le socle en ajoutant vos entites dans le Domain, vos services dans Application, vos tables dans votre propre DbContext. Quand SmartStack evolue, un simple `ss upgrade` met a jour les fondations sans toucher a votre code.

You never modify SmartStack internals. You extend the foundation by adding your entities in Domain, your services in Application, your tables in your own DbContext. When SmartStack evolves, a simple `ss upgrade` updates the foundations without touching your code.

## Architecture

### Clean Architecture

Votre projet suit le pattern Clean Architecture en 4 couches. Le principe fondamental : les dependances pointent toujours vers le centre. Le Domain ne connait rien du monde exterieur. L'Application orchestre sans savoir comment les donnees sont stockees. L'Infrastructure implemente les details techniques. L'Api expose les endpoints.

Your project follows the Clean Architecture pattern with 4 layers. The core principle: dependencies always point inward. Domain knows nothing about the outside world. Application orchestrates without knowing how data is stored. Infrastructure implements technical details. Api exposes the endpoints.

D
Domain
Coeur metier
Business core

C'est ici que vivent vos entites metier (`Product`, `Order`, `Customer`...), vos interfaces et vos regles de validation. Cette couche n'a aucune dependance sur un framework — c'est du C# pur. Le package SmartStack fournit les classes de base (`BaseEntity`, `IAuditable`...).

This is where your business entities live (`Product`, `Order`, `Customer`...), your interfaces and validation rules. This layer has no dependency on any framework — it's pure C#. The SmartStack package provides base classes (`BaseEntity`, `IAuditable`...).

A
Application
Orchestration
Orchestration

La couche d'orchestration. Vos services metier, vos DTOs, vos interfaces de repository. C'est aussi ici que se declare `IExtensionsDbContext` — le contrat que l'Infrastructure doit implementer. Aucune reference a EF Core ou SQL Server ici.

The orchestration layer. Your business services, DTOs, repository interfaces. This is also where `IExtensionsDbContext` is declared — the contract that Infrastructure must implement. No reference to EF Core or SQL Server here.

I
Infrastructure
Acces aux donnees
Data access

L'implementation technique. `ExtensionsDbContext` (votre DbContext EF Core), les repositories, les configurations d'entites (`EntityTypeConfiguration`). C'est la seule couche qui sait comment vos donnees sont stockees. Les migrations EF Core vivent ici.

The technical implementation. `ExtensionsDbContext` (your EF Core DbContext), repositories, entity configurations (`EntityTypeConfiguration`). This is the only layer that knows how your data is stored. EF Core migrations live here.

P
Api
Point d'entree HTTP
HTTP entry point

Le point d'entree de votre application. Vos controllers REST, la configuration Swagger, `Program.cs` avec l'injection de dependances. C'est la couche la plus externe — elle orchestre le demarrage et expose vos endpoints.

Your application's entry point. Your REST controllers, Swagger configuration, `Program.cs` with dependency injection. This is the outermost layer — it orchestrates startup and exposes your endpoints.

### Dual-DbContext

SmartStack utilise une architecture Dual-DbContext qui separe strictement les donnees du socle de vos donnees metier. Le socle gere ses propres tables (Users, Roles, Tenants, Permissions, AuditLogs) via son contexte interne. Votre projet utilise `ExtensionsDbContext` pour ses propres tables.

SmartStack uses a Dual-DbContext architecture that strictly separates foundation data from your business data. The foundation manages its own tables (Users, Roles, Tenants, Permissions, AuditLogs) through its internal context. Your project uses `ExtensionsDbContext` for its own tables.

Cette separation a trois avantages concrets :

This separation has three concrete advantages:

- Vos migrations n'interferent jamais avec les tables du socle
- Your migrations never interfere with foundation tables
- Les mises a jour SmartStack (`ss upgrade`) n'impactent pas votre schema
- SmartStack updates (`ss upgrade`) don't impact your schema
- Vous visualisez clairement ce qui vous appartient vs. ce qui est gere par le framework
- You can clearly see what belongs to you vs. what is managed by the framework

📚

Toutes les operations sur vos migrations passent par les skills `/efcore`. Le MCP valide les noms, detecte les conflits entre branches et assure la coherence. Voir la page EF Core pour le workflow complet.

All operations on your migrations go through `/efcore` skills. The MCP validates names, detects conflicts between branches and ensures consistency. See the EF Core page for the complete workflow.

## Creer votre projet Create your project

La commande `ss init` cree un projet complet et pret a developper. Voici ce qui se passe etape par etape :

The `ss init` command creates a complete, ready-to-develop project. Here's what happens step by step:

1. ##### Choisir le nom du projet

   ##### Choose the project name

   Le nom devient le namespace C# racine de toute votre application : `MyApp.Domain`, `MyApp.Application`, `MyApp.Infrastructure`, `MyApp.Api`. Choisissez un identifiant C# valide (PascalCase, sans espaces ni tirets).

   The name becomes the root C# namespace for your entire application: `MyApp.Domain`, `MyApp.Application`, `MyApp.Infrastructure`, `MyApp.Api`. Choose a valid C# identifier (PascalCase, no spaces or dashes).

2. ##### Le wizard vous guide

   ##### The wizard guides you

   En mode interactif, le wizard pose deux questions : Multi-tenant ? (activez si votre application doit isoler les donnees par client/organisation) et Azure AD B2C ? (si l'authentification passe par Azure B2C, necessite multi-tenant). En mode rapide (`-y`), les valeurs par defaut sont utilisees (single-tenant, pas de B2C).

   In interactive mode, the wizard asks two questions: Multi-tenant? (enable if your app needs to isolate data per client/organization) and Azure AD B2C? (if authentication goes through Azure B2C, requires multi-tenant). In quick mode (`-y`), defaults are used (single-tenant, no B2C).

3. ##### La commande genere tout

   ##### The command generates everything

   Solution .NET 4 projets Clean Architecture, frontend React/Vite/Tailwind preconfigure, fichiers VS Code (debug, tasks, extensions recommandees), `CLAUDE.md` pour Claude Code, `.smartstack/config.json` qui identifie votre projet, et `Directory.Build.props` pour le TargetFramework partage.

   .NET solution with 4 Clean Architecture projects, preconfigured React/Vite/Tailwind frontend, VS Code files (debug, tasks, recommended extensions), `CLAUDE.md` for Claude Code, `.smartstack/config.json` identifying your project, and `Directory.Build.props` for the shared TargetFramework.

    # Creer un projet avec le wizard interactif
    ss init MyApp

    # Mode rapide : valeurs par defaut (single-tenant, pas de B2C)
    ss init MyApp -y

    # Multi-tenant avec Azure AD B2C
    ss init MyApp --multi-tenant --b2c

    # Previsualiser sans rien creer
    ss init MyApp --dry-run

⚠️

`ss init` sans nom de projet fonctionne aussi — il configure SmartStack sur un projet .NET existant (CLAUDE.md, hooks, verification MCP) au lieu d'en creer un nouveau. Utile pour integrer SmartStack a un projet deja en cours.

`ss init` without a project name also works — it configures SmartStack on an existing .NET project (CLAUDE.md, hooks, MCP verification) instead of creating a new one. Useful for integrating SmartStack into an ongoing project.

## Structure du projet Project structure

Voici la structure generee par `ss init MyApp`, annotee avec le role de chaque element :

Here is the structure generated by `ss init MyApp`, annotated with the role of each element:

    MyApp/
    ├── src/                                   ← Backend .NET Clean Architecture
    │   ├── MyApp.Domain/              ← Entites, interfaces, regles metier
    │   ├── MyApp.Application/         ← Services, DTOs, IExtensionsDbContext
    │   ├── MyApp.Infrastructure/      ← ExtensionsDbContext, Repositories, Migrations
    │   └── MyApp.Api/                 ← Controllers, Swagger, Program.cs
    ├── web/                                   ← Frontend
    │   └── myapp-web/                 ← React + Vite + Tailwind
    ├── tests/                                 ← Tests unitaires et integration
    ├── .smartstack/config.json        ← Identite du projet SmartStack
    ├── CLAUDE.md                      ← Contexte IA pour Claude Code
    ├── Directory.Build.props          ← TargetFramework partage (net10.0)
    ├── .vscode/                       ← Debug, tasks, extensions recommandees
    ├── .ralph/                        ← Configuration Ralph (IA)
    └── MyApp.sln                      ← Solution Visual Studio

### Fichiers cles

### Key files

⚙
.smartstack/config.json
Identite du projet
Project identity

Contient le type de projet (client vs socle), le nom du DbContext, le namespace racine et la version SmartStack installee. Toutes les commandes CLI (`ss upgrade`, `ss doctor`) lisent ce fichier pour savoir comment traiter votre projet. Ne le modifiez pas manuellement.

Contains the project type (client vs foundation), DbContext name, root namespace and installed SmartStack version. All CLI commands (`ss upgrade`, `ss doctor`) read this file to know how to handle your project. Do not modify it manually.

📝
CLAUDE.md
Contexte IA
AI context

Le contexte que Claude Code utilise pour comprendre votre projet. Genere automatiquement avec les conventions SmartStack, la structure du projet et les regles a respecter. Vous pouvez l'enrichir avec vos propres conventions et regles metier.

The context Claude Code uses to understand your project. Auto-generated with SmartStack conventions, project structure and rules to follow. You can enrich it with your own conventions and business rules.

🔌
appsettings.json
Configuration API
API configuration

Dans `src/MyApp.Api/`. C'est ici que vous definissez la connection string SQL Server, les parametres JWT, les URLs autorisees (CORS), et la configuration multi-tenant si activee. C'est le premier fichier a configurer apres `ss init`.

In `src/MyApp.Api/`. This is where you define the SQL Server connection string, JWT settings, allowed URLs (CORS), and multi-tenant configuration if enabled. It's the first file to configure after `ss init`.

⚖
Directory.Build.props
Framework partage
Shared framework

Centralise le `TargetFramework` (net10.0) pour tous les projets .NET. Au lieu de definir la version dans chaque `.csproj`, ce fichier unique simplifie les futures mises a jour de framework.

Centralizes the `TargetFramework` (net10.0) for all .NET projects. Instead of defining the version in each `.csproj`, this single file simplifies future framework upgrades.

### Frontend — React + Vite + Tailwind

Le frontend est une application React moderne qui s'integre au socle SmartStack via deux mecanismes :

The frontend is a modern React application that integrates with the SmartStack foundation through two mechanisms:

- `SmartStackProvider` — wrape votre application et fournit l'authentification, les roles, le theming et les notifications. Vous n'avez rien a configurer, c'est deja en place dans `main.tsx`.
- `SmartStackProvider` — wraps your application and provides authentication, roles, theming and notifications. You don't need to configure anything, it's already set up in `main.tsx`.
- `mergeRoutes()` — fusionne vos routes metier avec les routes SmartStack (login, profil, admin, gestion des roles...). Vous developpez vos pages dans `src/pages/` et les declarez dans `App.tsx`.
- `mergeRoutes()` — merges your business routes with SmartStack routes (login, profile, admin, role management...). You develop your pages in `src/pages/` and declare them in `App.tsx`.

## Cycle de developpement Development cycle

Voici le flux typique quand vous ajoutez une fonctionnalite a votre projet. Chaque etape a un skill ou un outil dedie qui vous guide :

Here is the typical flow when adding a feature to your project. Each step has a dedicated skill or tool to guide you:

Vous pouvez realiser chaque etape manuellement, ou generer un module complet (entite + service + controller + page) avec `/application`.

You can perform each step manually, or generate a complete module (entity + service + controller + page) with `/application`.

🔗

##### Pages liees

##### Related pages

EF Core — workflow complet des migrations (conflits, rebase, squash) • GitFlow — gestion des branches et versioning

EF Core — complete migration workflow (conflicts, rebase, squash) • GitFlow — branch management and versioning

## Maintenir votre projet Maintain your project

Trois commandes couvrent la maintenance de votre environnement SmartStack. Chacune a un perimetre different — voici quand et pourquoi les utiliser :

Three commands cover your SmartStack environment maintenance. Each has a different scope — here's when and why to use them:

🔄
ss update
Outillage Claude Code
Claude Code tooling

Met a jour les skills, agents et hooks de Claude Code vers la derniere version. Utilisez-la quand SmartStack publie de nouvelles capacites IA (nouveaux skills, agents ameliores, hooks de securite). Ne touche jamais a votre code ni a vos packages — c'est uniquement l'outillage Claude Code qui evolue.

Updates Claude Code skills, agents and hooks to the latest version. Use it when SmartStack publishes new AI capabilities (new skills, improved agents, security hooks). Never touches your code or packages — only the Claude Code tooling evolves.

`--local` installe dans `.claude/` du projet installs in the project's `.claude/` • `--dry-run` previsualise previews

📦
ss upgrade
Packages du projet
Project packages

Met a jour les packages SmartStack dans votre projet : NuGet (SmartStack, EF Core, JWT, Swashbuckle...) dans tous les projets .NET, et npm (`@atlashub/smartstack`) dans le frontend. Si necessaire, applique automatiquement des migrations de code pour adapter votre projet aux breaking changes.

Updates SmartStack packages in your project: NuGet (SmartStack, EF Core, JWT, Swashbuckle...) in all .NET projects, and npm (`@atlashub/smartstack`) in the frontend. If needed, automatically applies code migrations to adapt your project to breaking changes.

`--preview` versions prerelease prerelease versions • `--dry-run` liste sans appliquer list without applying

🩺
ss doctor
Diagnostic complet
Full diagnostic

Diagnostique l'ensemble de votre environnement : versions (Node.js, .NET, Git, Claude Code), etat du MCP, licence, composants installes, configuration. Affiche les correctifs recommandes pour chaque probleme detecte. Lancez-la quand quelque chose ne fonctionne pas ou apres une installation fraiche.

Diagnoses your entire environment: versions (Node.js, .NET, Git, Claude Code), MCP state, license, installed components, configuration. Shows recommended fixes for each detected issue. Run it when something doesn't work or after a fresh installation.

`--json` export JSON JSON export • `--verbose` details complets full details

## Premiers pas apres l'initialisation First steps after initialization

Votre projet est cree. Voici les etapes pour le rendre operationnel :

Your project is created. Here are the steps to make it operational:

1. ##### Configurer la base de donnees

   ##### Configure the database

   Ouvrez `src/MyApp.Api/appsettings.json`, section `ConnectionStrings`. Remplacez la valeur par defaut par votre serveur SQL Server :

   Open `src/MyApp.Api/appsettings.json`, section `ConnectionStrings`. Replace the default value with your SQL Server:

       "ConnectionStrings": {
         "DefaultConnection": "Server=localhost;Database=MyApp;Trusted_Connection=true;TrustServerCertificate=true"
       }

2. ##### Initialiser GitFlow

   ##### Initialize GitFlow

   Dans Claude Code, tapez `/gitflow init`. Cela configure les branches `main`/`develop`, le versioning SemVer et les worktrees Git. Indispensable avant de commencer a developper en equipe.

   In Claude Code, type `/gitflow init`. This configures `main`/`develop` branches, SemVer versioning and Git worktrees. Essential before starting team development.

3. ##### Creer la migration initiale

   ##### Create the initial migration

   Dans Claude Code : `/efcore migration`. Le MCP suggere le nom de la migration et valide son contenu. Cette premiere migration cree les tables de votre `ExtensionsDbContext`.

   In Claude Code: `/efcore migration`. The MCP suggests the migration name and validates its content. This first migration creates the tables for your `ExtensionsDbContext`.

4. ##### Deployer la base de donnees

   ##### Deploy the database

   Dans Claude Code : `/efcore db-deploy`. Applique toutes les migrations en attente et cree les tables dans SQL Server. Vous pouvez verifier l'etat avec `/efcore db-status`.

   In Claude Code: `/efcore db-deploy`. Applies all pending migrations and creates the tables in SQL Server. You can check the state with `/efcore db-status`.

5. ##### Installer le frontend

   ##### Install the frontend

   Dans le terminal, placez-vous dans le dossier frontend :

   In the terminal, navigate to the frontend folder:

       cd web/myapp-web
       npm install

6. ##### Commencer a developper

   ##### Start developing

   Creez votre premiere branche avec `/gitflow start feature ma-feature`, puis utilisez `/application` pour generer un module complet.

   Create your first branch with `/gitflow start feature my-feature`, then use `/application` to generate a complete module.