# SmartStack Client Project Templates

These templates are used by the SmartStack CLI to generate new client projects.

## Template Files

| File | Description | Destination |
|------|-------------|-------------|
| `ExtensionsDbContext.cs.template` | DbContext for client entities | `{ProjectName}.Infrastructure/Persistence/` |
| `IExtensionsDbContext.cs.template` | Interface for ExtensionsDbContext | `{ProjectName}.Application/Common/Interfaces/` |
| `DependencyInjection.Infrastructure.cs.template` | DI configuration for Infrastructure | `{ProjectName}.Infrastructure/` |
| `Program.cs.template` | API entry point with migration order | `{ProjectName}.Api/` |
| `DesignTimeExtensionsDbContextFactory.cs.template` | Factory for EF Core CLI tools | `{ProjectName}.Infrastructure/Persistence/` |
| `ExampleEntity.cs.template` | Example entity with FK to Core | `{ProjectName}.Domain/Entities/` (optional) |
| `ExampleService.cs.template` | Example service using ICoreDataService | `{ProjectName}.Infrastructure/Services/` (optional) |
| `ExampleEntityConfiguration.cs.template` | Example EF Core configuration | `{ProjectName}.Infrastructure/Persistence/Configurations/` (optional) |

## Placeholders

The following placeholders are replaced during project generation:

| Placeholder | Description | Example |
|-------------|-------------|---------|
| `{{ProjectName}}` | PascalCase project name | `MyCompany` |

## Architecture Overview

### Dual DbContext Pattern

SmartStack uses two separate DbContexts:

1. **CoreDbContext** (from SmartStack NuGet package)
   - Schema: `core`
   - Manages: Users, Roles, Permissions, Navigation, etc.
   - Migrations: `core.__EFMigrationsHistory`

2. **ExtensionsDbContext** (client project)
   - Schema: `extensions`
   - Manages: Client-specific entities
   - Migrations: `extensions.__EFMigrationsHistory`

### FK References to Core Entities

When your entities need to reference Core entities (User, Role, etc.):

```csharp
// IN YOUR ENTITY - Store GUID only
public Guid CustomerId { get; private set; }  // FK to User

// IN YOUR SERVICE - Use ICoreDataService
var user = await _coreDataService.GetUserByIdAsync(entity.CustomerId);
```

**DO NOT** create navigation properties to Core entities, as ExtensionsDbContext doesn't know about them.

### Migration Order

Migrations must be applied in order:

1. Core migrations first (SmartStack platform tables)
2. Extensions migrations second (client tables that may reference Core)

This is handled automatically in `Program.cs.template`.

## Frontend Setup (React)

### Route Registration

SmartStack uses **PageRegistry + DynamicRouter** for routing. Register your pages:

```tsx
import { PageRegistry } from '@atlashub/smartstack';
import { lazy } from 'react';

// Register your application pages
PageRegistry.register('rh.time.dashboard', lazy(() => import('./pages/TimeDashboard')));
PageRegistry.register('rh.time.list', lazy(() => import('./pages/TimeList')));
PageRegistry.register('rh.time.detail', lazy(() => import('./pages/TimeDetail')));
```

Navigation entries (menu, permissions, routes) are managed in the database.
DynamicRouter resolves everything automatically — no manual route wiring needed.

### App chrome + mobile shell (inherited)

The application chrome is rendered by `@atlashub/smartstack` around
`<DynamicRouter />` — there is no `AppShell` or `Sidebar` to write. On desktop
that means the header, the hierarchical sidebar and the tenant/user menus. On
mobile it means the full **"descente par paliers"** shell: Applications →
Modules → Sections → the resource page, hierarchical back + breadcrumbs, tenant
chip, transverse search, offline banner and the outbox sheet — plus a
**transverse bottom bar** with four fixed entries:

| Tab | Source |
|---|---|
| Applications | the palier root (this app's DB menu) |
| Tâches | `GET /api/me/tasks` |
| Activité | `GET /api/me/activity` |
| Compte | profile, tenant, language, theme, sign-out |

The paliers ARE the navigation tables you already seed — nothing mobile-specific
to declare. The shell is **on by default**; the optional block in `main.tsx` only
makes it explicit and carries the tunables:

```tsx
// enabled defaults to true, breakpoint to 768 — omit the block for the defaults
<SmartStackProvider config={{ apiUrl, extensions: {}, mobile: { enabled: true, breakpoint: 768 } }}>
```

`/pwa` writes that block (along with the service worker, manifest and offline
wiring). A page appears inside the shell only if it carries `PageMobileMeta`
(from its `pwa.support`) — no metadata means desktop-only.

To surface this app's own queues in **Tâches** / **Activité**, register
`AddExtensionTasks<ExtensionsDbContext>(…)` or an `ITaskProvider` /
`IActivityProvider` from the backend Infrastructure DI — the mobile pages ship
in the package.

## Usage

```bash
# Create new project
smartstack init MyProject

# Add entity to Extensions
smartstack scaffold entity Order --context extensions

# Create migration (sanctioned /efcore CLI — computes the ext_v{version}_{seq3}_{Description} name)
npx --prefer-offline tsx skills/efcore/cli/create/index.ts --spec '{"cwd":".","description":"AddOrders"}'

# Apply migrations (policy-gated: autonomous on a provably-local DB)
npx --prefer-offline tsx skills/efcore/cli/apply/index.ts --spec '{"cwd":"."}'
```