# SmartStackProvider — Wrapping the Client App

> **Reference for `application` skill** — how to bootstrap a SmartStack client project (npm `@atlashub/smartstack`) using the SDK provider.

## When This Reference Applies

- The client project consumes `@atlashub/smartstack` as an npm package (v3.7+)
- You are generating or auditing `App.tsx` / `main.tsx` / the application bootstrap
- The user asks "how do I wrap my app", "where do I put providers", "how do I configure SmartStack"

If the project is the SmartStack platform itself (`SmartStack.app`), the platform's internal `App.tsx` already inlines the providers and does NOT use `<SmartStackProvider>` — only client projects use it.

---

## SmartStackConfig shape

```ts
interface SmartStackConfig {
  apiUrl: string;                          // REQUIRED — backend root URL (e.g. "https://api.client.com")
  defaultLanguage?: 'fr' | 'en' | 'it' | 'de';  // default 'fr'
  debug?: boolean;                          // verbose logging
  logo?: ReactNode;                         // override branding logo
  appName?: string;                         // displayed in title/header fallback
  licenseKey?: string;                      // license string (validated against /api/license)
  extensions?: ExtensionConfig;             // see references/extensions-system.md
}
```

---

## Wrapping order (Outer → Inner)

```tsx
import { BrowserRouter } from 'react-router-dom';
import { SmartStackProvider, DynamicRouter } from '@atlashub/smartstack';
import '@atlashub/smartstack/theme.css';

const config: SmartStackConfig = {
  apiUrl: import.meta.env.VITE_API_URL,
  defaultLanguage: 'fr',
  appName: 'My Client App',
};

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <BrowserRouter>
      <SmartStackProvider config={config}>
        <DynamicRouter />
      </SmartStackProvider>
    </BrowserRouter>
  </StrictMode>,
);
```

`<SmartStackProvider>` internally nests, in this order :

```
SmartStackContext (config)
└─ GlobalErrorBoundary
   └─ ExtensionProvider
      └─ ThemeProvider
         └─ FeatureConfigProvider
            └─ AuthProvider
               └─ TenantProvider
                  └─ LicenseProvider
                     └─ FavoritesProvider
                        └─ SidebarProvider
                           └─ SessionProvider
                              └─ ThemeSync
                                 └─ NavigationProvider
                                    └─ SignalRProvider
                                       └─ {children}
```

**Do NOT re-wrap any of these providers manually.** They are exported only for advanced cases (e.g., Storybook).

---

## Hooks consumable from any descendant

| Hook | Context | Returns |
|---|---|---|
| `useSmartStack()` | SmartStackContext | `{ config }` |
| `useAuth()` | AuthContext | `{ user, login, logout, refresh, hasPermission }` |
| `useTenant()` | TenantContext | `{ currentTenant, userTenants, switchTenant, isGlobalView }` |
| `useNavigation()` | NavigationContext | `{ menu, reload, currentApp, currentModule, isLoading }` |
| `useTheme()` | ThemeContext | `{ mode, selectedTheme, selectedPreset, setTheme, setPreset, toggleMode }` |
| `useLicense()` | LicenseContext | `{ license, isFeatureEnabled, hasModule }` |
| `useSignalR()` | SignalRContext | `{ isConnected, on, off, emit }` |
| `useFavorites()` | FavoritesContext | `{ favorites, toggleFavorite, isFavorite }` |
| `useSidebar()` | SidebarContext | `{ isCollapsed, toggle, setCollapsed }` |
| `useFeatureConfig()` | FeatureConfigContext | `{ features }` |
| `useDocPanel()` | DocPanelContext | `{ isOpen, toggle, openDoc }` |

See [contexts-cheatsheet.md](contexts-cheatsheet.md) for usage examples.

---

## DO / DON'T

| ✅ DO | ❌ DON'T |
|---|---|
| Place `<SmartStackProvider>` exactly once at root | Wrap the same provider twice |
| Put `<BrowserRouter>` ABOVE `<SmartStackProvider>` | Put `<SmartStackProvider>` above the router |
| Read config via `useSmartStack()` from any descendant | Pass config down via props |
| Import `componentRegistry.generated` in `main.tsx` BEFORE the render | Forget the import (DynamicRouter will not resolve pages) |
| Wait for `i18nReady` promise before render | Render before i18n loaded (causes FOUC) |
| Provide `apiUrl` via `import.meta.env.VITE_API_URL` | Hardcode the backend URL |

---

## Reference source files (read-only — DO NOT copy verbatim)

- `D:\01 - projets\SmartStack.app\features\IA-Workflow\web\smartstack-web\src\provider\SmartStackProvider.tsx`
- `D:\01 - projets\SmartStack.app\features\IA-Workflow\web\smartstack-web\src\router\types.ts` (SmartStackConfig)
- `D:\01 - projets\SmartStack.app\features\IA-Workflow\web\smartstack-web\src\main.tsx` (i18nReady + componentRegistry import)

For overrides via `extensions`, see [extensions-system.md](extensions-system.md).
