## Qu'est-ce qu'une application SmartStack ? What is a SmartStack application?

Une application SmartStack s'organise en 4 niveaux : Application → Module → Section → Resource. Chaque niveau genere automatiquement sa navigation, ses permissions et ses roles.

A SmartStack application is organized in 4 levels: Application → Module → Section → Resource. Each level automatically generates its navigation, permissions and roles.

💡

Vous decrivez votre besoin (ex: « Creer un module Employes avec gestion des contrats »), SmartStack genere le code full-stack : entite, API, pages React, navigation dans le menu, permissions CRUD et assignation aux roles. Voir l'arbre de decision pour choisir le bon skill.

You describe your need (e.g., « Create an Employees module with contract management »), SmartStack generates the full-stack code: entity, API, React pages, menu navigation, CRUD permissions and role assignment. See the decision tree to choose the right skill.

## 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`.

## Quel skill utiliser ? Which skill to use?

Choisissez votre situation, le diagramme vous guide vers le bon parcours.

Choose your situation, the diagram guides you to the right path.

## 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.

## Environnement Linux sur Windows (WSL) Linux Environment on Windows (WSL)

SmartStack fonctionne nativement sous Windows, mais l'utilisation d'un terminal Linux via WSL (Windows Subsystem for Linux) offre un environnement de developpement plus fluide et performant — meilleur support de Git, scripts bash natifs, et outils comme `tmux` pour gerer plusieurs sessions.

SmartStack works natively on Windows, but using a Linux terminal via WSL (Windows Subsystem for Linux) provides a smoother and more performant development environment — better Git support, native bash scripts, and tools like `tmux` for managing multiple sessions.

### 1. Installer WSL2 et Ubuntu 1. Install WSL2 and Ubuntu

Ouvrez un terminal PowerShell en administrateur et lancez la commande suivante. Elle installe WSL2 avec Ubuntu comme distribution par defaut :

Open a PowerShell terminal as Administrator and run the following command. It installs WSL2 with Ubuntu as the default distribution:

    # PowerShell (Administrateur) — installe WSL2 + Ubuntu
    wsl --install

Redemarrez votre machine apres l'installation. Au premier lancement d'Ubuntu, vous devrez creer un nom d'utilisateur et un mot de passe Linux (independants de votre compte Windows).

Restart your machine after installation. On first Ubuntu launch, you'll need to create a Linux username and password (independent from your Windows account).

💡

Si WSL est deja installe mais avec la version 1, mettez a jour vers WSL2 : `wsl --set-default-version 2`. WSL2 utilise un vrai noyau Linux et offre de meilleures performances I/O.

If WSL is already installed but on version 1, upgrade to WSL2: `wsl --set-default-version 2`. WSL2 uses a real Linux kernel and offers better I/O performance.

Pour verifier que tout fonctionne :

To verify everything works:

    # PowerShell — verifier la version et la distribution
    wsl --list --verbose

    # Resultat attendu :
    #   NAME      STATE    VERSION
    # * Ubuntu    Running  2

### 2. Configurer Ubuntu 2. Configure Ubuntu

Une fois dans le terminal Ubuntu, commencez par mettre a jour les paquets systeme, puis installez les outils de developpement essentiels :

Once inside the Ubuntu terminal, start by updating system packages, then install essential development tools:

    # Mettre a jour les paquets systeme
    sudo apt update && sudo apt upgrade -y

    # Installer les outils de base
    sudo apt install -y git curl wget unzip build-essential

#### Installer Node.js (via nvm) Install Node.js (via nvm)

Utilisez nvm (Node Version Manager) pour installer Node.js — cela permet de gerer facilement plusieurs versions :

Use nvm (Node Version Manager) to install Node.js — it allows easy management of multiple versions:

    # Installer nvm
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

    # Recharger le profil
    source ~/.bashrc

    # Installer la derniere version LTS de Node.js
    nvm install --lts

    # Verifier
    node --version
    npm --version

#### Installer .NET SDK Install .NET SDK

    # Installer le SDK .NET (Ubuntu)
    sudo apt install -y dotnet-sdk-10.0

    # Verifier
    dotnet --version

⚠️

Si le paquet `dotnet-sdk-10.0` n'est pas disponible, ajoutez d'abord le depot Microsoft :

If the `dotnet-sdk-10.0` package is not available, add the Microsoft repository first:

    wget https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
    sudo dpkg -i packages-microsoft-prod.deb
    rm packages-microsoft-prod.deb
    sudo apt update
    sudo apt install -y dotnet-sdk-10.0

### 3. Installer et configurer tmux 3. Install and configure tmux

tmux (terminal multiplexer) vous permet de diviser votre terminal en plusieurs panneaux, de detacher des sessions et de garder des processus en cours meme si vous fermez votre terminal. C'est particulierement utile pour lancer simultanement le backend .NET, le frontend React et Claude Code.

tmux (terminal multiplexer) lets you split your terminal into multiple panes, detach sessions and keep processes running even if you close your terminal. It's particularly useful for simultaneously running the .NET backend, React frontend and Claude Code.

    # Installer tmux
    sudo apt install -y tmux

    # Verifier la version
    tmux -V

#### Activer la souris dans tmux Enable mouse in tmux

Par defaut, tmux ne repond pas aux clics de souris. Pour activer le support complet de la souris (clic pour changer de panneau, scroll, redimensionnement, selection de texte), creez ou modifiez le fichier `~/.tmux.conf` :

By default, tmux does not respond to mouse clicks. To enable full mouse support (click to switch panes, scroll, resize, text selection), create or edit the `~/.tmux.conf` file:

    # Creer/editer la configuration tmux
    cat << 'EOF' > ~/.tmux.conf
    # ── Activer la souris ──
    set -g mouse on

    # ── Ameliorer le support des couleurs ──
    set -g default-terminal "tmux-256color"
    set -ag terminal-overrides ",xterm-256color:RGB"

    # ── Historique de scroll etendu (10 000 lignes) ──
    set -g history-limit 10000

    # ── Commencer les indices de fenetres/panneaux a 1 ──
    set -g base-index 1
    setw -g pane-base-index 1

    # ── Raccourcis pratiques pour diviser les panneaux ──
    # Ctrl+b puis | = split vertical
    bind | split-window -h -c "#{pane_current_path}"
    # Ctrl+b puis - = split horizontal
    bind - split-window -v -c "#{pane_current_path}"

    # ── Recharger la config avec Ctrl+b puis r ──
    bind r source-file ~/.tmux.conf \; display "Config rechargee!"
    EOF

Si tmux est deja en cours d'execution, rechargez la configuration sans le fermer :

If tmux is already running, reload the configuration without closing it:

    # Depuis l'interieur de tmux : Ctrl+b puis :
    # Tapez la commande suivante :
    source-file ~/.tmux.conf

    # Ou si vous avez ajoute le raccourci ci-dessus :
    # Ctrl+b puis r

#### Commandes essentielles tmux Essential tmux commands

Toutes les commandes tmux commencent par le prefixe `Ctrl+b`, suivi d'une touche. Voici les plus utiles :

All tmux commands start with the prefix `Ctrl+b`, followed by a key. Here are the most useful ones:

Action | Action | Raccourci | Shortcut | Description
--- | --- | --- | --- | ---
Nouvelle session | New session | `tmux new -s dev` | Cree une session nommee "dev" | Creates a session named "dev"
Detacher la session | Detach session | `Ctrl+b d` | Detache sans fermer (les processus continuent) | Detaches without closing (processes keep running)
Rattacher la session | Reattach session | `tmux attach -t dev` | Revient a la session "dev" | Returns to the "dev" session
Split vertical | Vertical split | `Ctrl+b |` | Divise le panneau verticalement | Splits the pane vertically
Split horizontal | Horizontal split | `Ctrl+b -` | Divise le panneau horizontalement | Splits the pane horizontally
Naviguer entre panneaux | Navigate panes | `Ctrl+b ←↑↓→` | Fleches directionnelles pour changer de panneau | Arrow keys to switch panes
Fermer un panneau | Close pane | `Ctrl+b x` | Ferme le panneau actif (confirmation demandee) | Closes the active pane (confirmation required)
Lister les sessions | List sessions | `tmux ls` | Affiche toutes les sessions actives | Shows all active sessions

#### Workflow SmartStack avec tmux SmartStack workflow with tmux

Voici un exemple de session tmux typique pour le developpement SmartStack avec 3 panneaux :

Here's a typical tmux session example for SmartStack development with 3 panes:

    # Creer une session de developpement
    tmux new -s smartstack

    # Panneau 1 : Backend .NET (deja actif)
    cd /mnt/d/MyApp/src/MyApp.Api
    dotnet watch run

    # Ctrl+b | → Split vertical pour le panneau 2 : Frontend
    cd /mnt/d/MyApp/web/myapp-web
    npm run dev

    # Ctrl+b - → Split horizontal pour le panneau 3 : Claude Code
    cd /mnt/d/MyApp
    claude

💡

##### Acceder a vos fichiers Windows depuis WSL

##### Access your Windows files from WSL

Vos disques Windows sont montes automatiquement sous `/mnt/`. Le disque `C:` est accessible a `/mnt/c/`, le disque `D:` a `/mnt/d/`, etc. Vous pouvez donc travailler directement sur vos projets Windows depuis le terminal Ubuntu.

Your Windows drives are automatically mounted under `/mnt/`. The `C:` drive is accessible at `/mnt/c/`, the `D:` drive at `/mnt/d/`, etc. You can therefore work directly on your Windows projects from the Ubuntu terminal.