---
name: Validate - Completeness and Integration
description: Validate documentation completeness, accuracy, and integrate into SmartStack app
next_step: null
---

## STEP 03: Validate — Completeness and Integration

### Purpose

Validate that generated documentation is complete and accurate, then integrate into the SmartStack app with proper routing and i18n configuration.

### Validation Checklist

#### All Types

- [ ] Documentation page renders correctly in React app
- [ ] i18n files created in ALL 4 languages (FR, EN, DE, IT)
- [ ] Files saved to correct directory paths
- [ ] docs-manifest.json updated with new entry
- [ ] NO "Benefices" or "Avant/Apres" sections present

#### For `user` Type Only

- [ ] Mock UI faithfully reproduces the real page interface (not generic KPI/table)
- [ ] Every Mock UI section has `Annotation` components explaining each visual element
- [ ] i18n JSON is FLAT (no root key) — `t('title')` resolves directly
- [ ] Route added as **child** of `/docs/business` group (not standalone) in DynamicRouter.tsx
- [ ] DocsLayout sidebar updated (if applicable)
- [ ] Module appears in UserIndexPage.tsx (if applicable)
- [ ] DocPanelContext.tsx mapping updated for all module routes
- [ ] i18n/config.ts updated with new namespace
- [ ] BookOpen edge button opens correct doc for the module's routes

#### For `developer|database|testing` Types

- [ ] i18n JSON uses root key matching namespace
- [ ] DocRenderer wrapper (index.tsx) passes correct `i18nNamespace` prop
- [ ] doc-data.ts contains structured data (~50 lines)
- [ ] Route added as **child** of `/system/docs` group (not standalone) in DynamicRouter.tsx
- [ ] DocsLayout sidebar updated (if applicable)

#### For `update` Type

- [ ] Mock UI updates reflect current interface
- [ ] API endpoints verified against current controller
- [ ] Business rules updated with any new validation rules
- [ ] docs-manifest.json timestamps refreshed
- [ ] All 4 language files updated

### Integration Steps

#### UserIndexPage Integration (TYPE: user only)

**MANDATORY** for `user` modules: Add the module to the navigation hierarchy.

| File | Modification |
|------|--------------|
| `UserIndexPage.tsx` | Add icon + entry in `modules[]` of parent application |
| `fr/docs.json` | Add `user.modules.{module}.name` and `.description` |
| `en/docs.json` | Add `user.modules.{module}.name` and `.description` |

**Parent applications:**
- `Administration`: admin modules (users, roles, ai, entra...)
- `Support`: support modules (tickets, sla, templates...)
- `MySpace`: personal modules (profile, preferences...)

**Verification:** The module should appear on `/docs/user` under its application.

#### DocPanelContext Integration (TYPE: user only)

**MANDATORY** for `user` modules: Update the contextual documentation panel mapping.

**File to update:** `web/smartstack-web/src/contexts/DocPanelContext.tsx`

**What to add:** For each module, add entries in the `docMapping` object for ALL the module's routes.
Keys MUST be prefixed with the application code to avoid ambiguity:

```typescript
const docMapping: Record<string, string> = {
  // Administration > {Module}
  'administration/{module}': '/docs/business/administration/{module}',
  'administration/{module}/list': '/docs/business/administration/{module}',
  'administration/{module}/create': '/docs/business/administration/{module}',
  'administration/{module}/dashboard': '/docs/business/administration/{module}',
  // ... add ALL sub-routes that exist for the module

  // Support > {Module}
  'support/{module}': '/system/docs/user/support-{module}',
  // ... add ALL sub-routes

  // MySpace > {Module}
  'myspace/{module}': '/system/docs/user/modules',
  // ... add ALL sub-routes
};
```

**Also update `appDocMapping`** if the module is the "default" for its application:

```typescript
const appDocMapping: Record<string, string> = {
  'administration': '/docs/business/administration/users',  // default for admin
  'support': '/system/docs/user/support-dashboard',
  'myspace': '/system/docs/user/modules',
};
```

**Key resolution logic:** The `getDocUrlForPath()` function extracts segments from the pathname,
detects tenant-prefixed routes (`/t/:slug/...`), and builds lookup keys as `{app}/{module}/...`:
- `/administration/users/list` → tries `administration/users/list`, then `administration/users`
- `/support/tickets/123` → tries `support/tickets/123`, then `support/tickets`
- `/t/my-company/administration/users` → strips tenant prefix, then tries `administration/users`

#### DynamicRouter.tsx Routing

Documentation pages use a **separate routing system** from business pages. They render inside `DocsLayout` (sidebar navigation), NOT `AppLayout`. There are two route groups:

- **`/docs/business`** → Business module docs (user type) — uses `<DocsLayout />`
- **`/system/docs`** → Developer/database/testing docs — uses `<DocsLayout />`

> **Note:** The `<Suspense fallback={<PageLoader />}>` is already in place at the global level (wrapping the entire Routes tree). Do NOT add per-route `<Suspense>` wrappers.

**For `user` type:** Add lazy import and **child route** inside the existing `/docs/business` group in `DynamicRouter.tsx`:

```tsx
// 1. Add lazy import at top of DynamicRouter.tsx
const {Module}DocPage = lazy(() =>
  import('@/pages/docs/business/{application}/{module}')
);

// 2. Find the existing <Route path="/docs/business" element={<DocsLayout />}> group
//    Add as CHILD route (not standalone):
<Route path="/docs/business" element={<DocsLayout />}>
  {/* ... existing doc routes ... */}
  <Route path="{application}/{module}" element={<{Module}DocPage />} />
</Route>
```

**For `developer|database|testing` types:** Add **child route** inside the existing `/system/docs` group in `DynamicRouter.tsx`:

```tsx
// 1. Add lazy import at top of DynamicRouter.tsx
const {Tool}DocPage = lazy(() =>
  import('@/pages/docs/{category}/{tool}')
);

// 2. Find the existing <Route path="/system/docs" element={<DocsLayout />}> group
//    Add as CHILD route:
<Route path="/system/docs" element={<DocsLayout />}>
  {/* ... existing doc routes ... */}
  <Route path="{category}/{tool}" element={<{Tool}DocPage />} />
</Route>
```

#### DynamicRouter Documentation Routes

Documentation routes are statically defined in `DynamicRouter.tsx` (not dynamically generated from the navigation API). When adding new documentation pages, add the lazy import and `<Route>` entry in the documentation section of `DynamicRouter.tsx`.

#### DocsLayout Sidebar Update

If the new documentation page should appear in the sidebar navigation, update the `navigation` array in `DocsLayout.tsx` with the new entry (label, path, icon).

#### Important Notes

- Documentation routes do **NOT** use `AppLayout`, `ProtectedRoute`, or `LicenseGuard`
- Documentation routes have **no tenant prefix** (`/t/:slug/...`) — they are globally accessible
- Documentation routes require **no specific permission** to access

#### i18n Config Update

**File:** `web/smartstack-web/src/i18n/config.ts`

Add the new namespace to `loadLanguageResources`:

```typescript
// 1. Add to destructured imports
const {
  docsAdministrationUsers,
  docsAdministrationPermissions,
  docsAdministrationNewModule, // NEW
  // ...
} = resources;

// 2. Add dynamic import with fallback
const docsAdministrationNewModule = await import(
  '@i18n/docs-administration-new-module.json'
).catch(() => ({ default: {} }));

// 3. Add to return object
return {
  // ...
  docsAdministrationNewModule,
};

// 4. Add to ns array in i18n.init()
ns: [
  'common',
  'nav',
  'docsAdministrationUsers',
  'docsAdministrationPermissions',
  'docsAdministrationNewModule', // NEW
  // ...
]
```

#### docs-manifest.json Update

Add or update entry with metadata:

```json
{
  "id": "{module}",
  "type": "user",
  "title": "Module Title",
  "application": "administration",
  "path": "/docs/business/administration/{module}",
  "created_at": "2026-02-17T10:30:00Z",
  "refreshed_at": "2026-02-17T10:30:00Z",
  "i18n_namespace": "docsAdministration{Module}",
  "routes": [
    "{module}",
    "{module}/list",
    "{module}/create"
  ]
}
```

### Data Sources Reference

| Data | Source |
|------|--------|
| DB schemas | `src/SmartStack.Infrastructure/Persistence/Configurations/` |
| Tables | `ApplicationDbContextModelSnapshot.cs` |
| Existing documentation | `web/smartstack-web/src/pages/docs/` |
| Testing tools | WebSearch (current versions) |
| Real UI pages | `web/smartstack-web/src/pages/{Application}/` |
| Controllers | `src/SmartStack.Api/Controllers/` |
| Domain entities | `src/SmartStack.Domain/Entities/` |
| Permissions | `src/SmartStack.Domain/Authorization/Permissions.cs` |

### Associated Files Reference

- **React Templates:** `templates.md`
- **Data Schema:** `data-schema.md`
- **DocRenderer:** `web/smartstack-web/src/components/docs/DocRenderer.tsx`
- **Types:** `web/smartstack-web/src/components/docs/types.ts`
- **DocPanelContext:** `web/smartstack-web/src/contexts/DocPanelContext.tsx`
- **DocEdgeButton:** `web/smartstack-web/src/components/ui/DocEdgeButton.tsx`
- **DocPanel:** `web/smartstack-web/src/components/ui/DocPanel.tsx`
- **i18n Config:** `web/smartstack-web/src/i18n/config.ts`
- **Manifest Schema:** `_resources/docs-manifest-schema.md`
- **Complete Command:** `.claude/commands/documentation-module.md`

### Success Metrics

- [x] Documentation page renders correctly in React app
- [x] Mock UI faithfully reproduces the real page interface (user type)
- [x] Every Mock UI section has `Annotation` components (user type)
- [x] i18n files created in ALL 4 languages (FR, EN, DE, IT) with correct format
- [x] Route added as child of correct DocsLayout group in DynamicRouter.tsx
- [x] Route added in DynamicRouter.tsx documentation section
- [x] DocsLayout sidebar updated (if applicable)
- [x] docs-manifest.json updated
- [x] i18n/config.ts updated with new namespace
- [x] Module appears in UserIndexPage (if type = user)
- [x] DocPanelContext.tsx mapping updated (if type = user)
- [x] BookOpen edge button opens correct doc for the module's routes
- [x] NO "Benefices" or "Avant/Apres" sections present
- [x] All tests pass and app builds successfully

### Completion

**Documentation workflow complete.** The generated documentation is now:
- Fully integrated into SmartStack app
- Accessible via routing system
- Accessible via DocPanel contextual button
- Internationalized in FR, EN, DE, IT
- Listed in docs-manifest.json for discovery

**Next:** Monitor for feedback on documentation accuracy and completeness. Use step-03 validation checklist for future updates.
