# Spec Template Reference

> **Layer:** 3 | **Load:** on-demand | **Keywords:** spec, specification, template

**The canonical template is `docs/spec.md` of the template system** (REGISTRY id `spec`),
resolved from the installed package — see `framework/templates/README.md`.

This file contains extended examples for each spec section.

---

## Example: Entity (Pseudo-code)

```csharp
class ProcessingJob {
  Guid Id
  string OriginalPhotoUrl     // Azure Blob URL, max 500 chars
  string? ProcessedPhotoUrl   // Nullable, populated after processing
  ProcessingStatus Status     // Enum: Pending, Processing, Completed, Failed
  DateTime CreatedAt
  ICollection<ExecutionLog> Logs  // 1:N relationship
}

enum ProcessingStatus {
  Pending = 0, Processing = 1, Completed = 2,  // Normal flow
  Failed = 100                                   // Error states (high values)
}
```

## Example: Command (Pseudo-code)

```csharp
UploadPhotoCommand {
  Input: IFormFile photo, string? email
  Output: Guid jobId

  Handler:
    1. Validate file (size <= 10MB, type in [.jpg, .png])
    2. Upload to Azure Blob Storage
    3. Create ProcessingJob entity (status = Pending)
    4. Enqueue Hangfire background job
    5. Return jobId
}
```

## Example: API Endpoints

```csharp
PhotoProcessingController {
  POST /api/upload        → multipart/form-data → { jobId: Guid }
  GET  /api/status/{id}   → jobId → { status, progress, createdAt }
  GET  /api/download/{id} → jobId → Redirect to Blob URL or 404
}
```

## Example: Flow

```
Upload Flow (Actor: User)
1. User selects photo → System validates (size, type) → If invalid: show error
2. User sees preview → clicks "Upload"
3. System creates ProcessingJob → uploads to Blob → enqueues Hangfire job → returns jobId
4. System navigates to /processing/{jobId} → polls every 5s
End State: User on progress page, job processing in background
```

## Example: ADR

### ADR-001: Use Hangfire for Background Jobs
**Status:** Accepted
**Context:** Need background processing for AI photo transformation (30-120s).
**Decision:** Hangfire (self-hosted).
**Alternatives:**
1. Azure Functions — serverless, auto-scaling, but cold start + $10/mo for 50k jobs
2. Hangfire — zero cost, simpler, but scales with app
3. Quartz.NET — more features, but steeper learning curve
**Trade-offs:** Simplicity vs Features (Hangfire sufficient for MVP)

## Example: Cost Estimate

| Resource | SKU | Monthly | Justification |
|----------|-----|---------|---------------|
| Blob Storage | LRS | $0.02 | Store photos, low redundancy OK |
| Azure SQL | Basic | $4.99 | < 100k jobs/month |
| Container App | Consumption | $0.49 | Scale to zero |
| Hangfire | Self-hosted | $0.00 | In-process |
| **Total** | | **~$5.50** | |

---

*MORPH-SPEC by Polymorphism Tech*