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

## Usage

```bash
# Create new project
smartstack init MyProject

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

# Create migration
dotnet ef migrations add ext_v1.0.0_001_AddOrders --context ExtensionsDbContext

# Apply migrations
dotnet ef database update
```
