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.

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.

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

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

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

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:

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:

   Copy

   "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:

   Copy

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

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

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:

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