@polymorphism-tech/morph-spec 4.7.1 → 4.7.2

package/.morph/framework/standards/infrastructure/azure/services/storage.md

@@ -0,0 +1,407 @@
+# Azure Storage Services Standard
+
+> **Scope:** blazor-azure
+> **Layer:** 2 (on keyword)
+> **Keywords:** azure storage, blob, queue, table, file storage
+> **Load When:** azure storage keywords detected
+
+Azure Storage services patterns for Blob, Queue, Table, and File storage.
+
+---
+
+## Overview
+
+Azure Storage provides:
+- **Blob Storage**: Object storage for unstructured data (files, images, videos)
+- **Queue Storage**: Message queuing for async processing
+- **Table Storage**: NoSQL key-value store
+- **File Storage**: SMB file shares
+
+**Stack:** .NET 10 + Blazor Server
+
+---
+
+## Core Principles
+
+1. **Managed Identity**: Use Managed Identity over connection strings
+2. **SAS Tokens**: Use SAS for temporary access delegation
+3. **Retry Policies**: Configure exponential backoff for transient failures
+4. **Lifecycle Management**: Auto-delete old blobs with lifecycle policies
+5. **Cost Optimization**: Use appropriate storage tiers (Hot/Cool/Archive)
+
+---
+
+## Installation
+
+```bash
+dotnet add package Azure.Storage.Blobs
+dotnet add package Azure.Storage.Queues
+dotnet add package Azure.Identity
+```
+
+---
+
+## Blob Storage
+
+### DI Configuration
+
+```csharp
+// Program.cs
+using Azure.Identity;
+using Azure.Storage.Blobs;
+
+builder.Services.AddSingleton(sp =>
+{
+    var blobServiceUri = new Uri(builder.Configuration["AzureStorage:BlobServiceUri"]!);
+    return new BlobServiceClient(blobServiceUri, new DefaultAzureCredential());
+});
+```
+
+### Upload Blob
+
+```csharp
+public class FileUploadService
+{
+    private readonly BlobServiceClient _blobServiceClient;
+
+    public FileUploadService(BlobServiceClient blobServiceClient)
+    {
+        _blobServiceClient = blobServiceClient;
+    }
+
+    public async Task<string> UploadFileAsync(Stream fileStream, string fileName, string containerName)
+    {
+        var containerClient = _blobServiceClient.GetBlobContainerClient(containerName);
+        await containerClient.CreateIfNotExistsAsync();
+
+        var blobClient = containerClient.GetBlobClient(fileName);
+
+        await blobClient.UploadAsync(fileStream, overwrite: true);
+
+        return blobClient.Uri.ToString();
+    }
+}
+```
+
+### Download Blob
+
+```csharp
+public async Task<Stream> DownloadFileAsync(string fileName, string containerName)
+{
+    var containerClient = _blobServiceClient.GetBlobContainerClient(containerName);
+    var blobClient = containerClient.GetBlobClient(fileName);
+
+    var response = await blobClient.DownloadAsync();
+    return response.Value.Content;
+}
+```
+
+### Generate SAS Token
+
+```csharp
+using Azure.Storage.Sas;
+
+public string GenerateSasUri(string containerName, string blobName, TimeSpan validity)
+{
+    var containerClient = _blobServiceClient.GetBlobContainerClient(containerName);
+    var blobClient = containerClient.GetBlobClient(blobName);
+
+    var sasBuilder = new BlobSasBuilder
+    {
+        BlobContainerName = containerName,
+        BlobName = blobName,
+        Resource = "b", // Blob
+        StartsOn = DateTimeOffset.UtcNow,
+        ExpiresOn = DateTimeOffset.UtcNow.Add(validity)
+    };
+
+    sasBuilder.SetPermissions(BlobSasPermissions.Read);
+
+    var sasUri = blobClient.GenerateSasUri(sasBuilder);
+    return sasUri.ToString();
+}
+```
+
+---
+
+## Queue Storage
+
+### DI Configuration
+
+```csharp
+// Program.cs
+builder.Services.AddSingleton(sp =>
+{
+    var queueServiceUri = new Uri(builder.Configuration["AzureStorage:QueueServiceUri"]!);
+    return new QueueServiceClient(queueServiceUri, new DefaultAzureCredential());
+});
+```
+
+### Send Message
+
+```csharp
+public class QueueService
+{
+    private readonly QueueServiceClient _queueServiceClient;
+
+    public QueueService(QueueServiceClient queueServiceClient)
+    {
+        _queueServiceClient = queueServiceClient;
+    }
+
+    public async Task SendMessageAsync(string queueName, string message)
+    {
+        var queueClient = _queueServiceClient.GetQueueClient(queueName);
+        await queueClient.CreateIfNotExistsAsync();
+
+        await queueClient.SendMessageAsync(message);
+    }
+
+    public async Task SendMessageWithDelayAsync(string queueName, string message, TimeSpan delay)
+    {
+        var queueClient = _queueServiceClient.GetQueueClient(queueName);
+        await queueClient.CreateIfNotExistsAsync();
+
+        await queueClient.SendMessageAsync(message, visibilityTimeout: delay);
+    }
+}
+```
+
+### Process Messages
+
+```csharp
+using Azure.Storage.Queues.Models;
+
+public async Task ProcessMessagesAsync(string queueName, CancellationToken cancellationToken)
+{
+    var queueClient = _queueServiceClient.GetQueueClient(queueName);
+
+    while (!cancellationToken.IsCancellationRequested)
+    {
+        QueueMessage[] messages = await queueClient.ReceiveMessagesAsync(maxMessages: 32);
+
+        foreach (var message in messages)
+        {
+            try
+            {
+                // Process message
+                await ProcessMessageAsync(message.MessageText);
+
+                // Delete message after successful processing
+                await queueClient.DeleteMessageAsync(message.MessageId, message.PopReceipt);
+            }
+            catch (Exception ex)
+            {
+                // Log error, message will become visible again after timeout
+                _logger.LogError(ex, "Failed to process message {MessageId}", message.MessageId);
+            }
+        }
+
+        if (messages.Length == 0)
+        {
+            await Task.Delay(TimeSpan.FromSeconds(5), cancellationToken);
+        }
+    }
+}
+```
+
+---
+
+## Table Storage
+
+### DI Configuration
+
+```csharp
+dotnet add package Azure.Data.Tables
+
+// Program.cs
+builder.Services.AddSingleton(sp =>
+{
+    var tableServiceUri = new Uri(builder.Configuration["AzureStorage:TableServiceUri"]!);
+    return new TableServiceClient(tableServiceUri, new DefaultAzureCredential());
+});
+```
+
+### Entity Model
+
+```csharp
+using Azure;
+using Azure.Data.Tables;
+
+public class ProductEntity : ITableEntity
+{
+    public string PartitionKey { get; set; } = default!; // Category
+    public string RowKey { get; set; } = default!;       // ProductId
+    public DateTimeOffset? Timestamp { get; set; }
+    public ETag ETag { get; set; }
+
+    public string Name { get; set; } = string.Empty;
+    public decimal Price { get; set; }
+    public int Stock { get; set; }
+}
+```
+
+### CRUD Operations
+
+```csharp
+public class ProductTableService
+{
+    private readonly TableClient _tableClient;
+
+    public ProductTableService(TableServiceClient tableServiceClient)
+    {
+        _tableClient = tableServiceClient.GetTableClient("products");
+        _tableClient.CreateIfNotExists();
+    }
+
+    public async Task AddProductAsync(ProductEntity product)
+    {
+        await _tableClient.AddEntityAsync(product);
+    }
+
+    public async Task<ProductEntity?> GetProductAsync(string category, string productId)
+    {
+        try
+        {
+            return await _tableClient.GetEntityAsync<ProductEntity>(category, productId);
+        }
+        catch (RequestFailedException ex) when (ex.Status == 404)
+        {
+            return null;
+        }
+    }
+
+    public async Task<List<ProductEntity>> QueryProductsAsync(string category)
+    {
+        var query = _tableClient.QueryAsync<ProductEntity>(p => p.PartitionKey == category);
+
+        var results = new List<ProductEntity>();
+        await foreach (var product in query)
+        {
+            results.Add(product);
+        }
+
+        return results;
+    }
+
+    public async Task UpdateProductAsync(ProductEntity product)
+    {
+        await _tableClient.UpdateEntityAsync(product, ETag.All, TableUpdateMode.Replace);
+    }
+
+    public async Task DeleteProductAsync(string category, string productId)
+    {
+        await _tableClient.DeleteEntityAsync(category, productId);
+    }
+}
+```
+
+---
+
+## Best Practices
+
+### Retry Policy
+
+```csharp
+using Azure.Core;
+
+var options = new BlobClientOptions
+{
+    Retry =
+    {
+        Mode = RetryMode.Exponential,
+        MaxRetries = 3,
+        Delay = TimeSpan.FromSeconds(2),
+        MaxDelay = TimeSpan.FromSeconds(10)
+    }
+};
+
+var blobServiceClient = new BlobServiceClient(blobServiceUri, credential, options);
+```
+
+### Blob Metadata
+
+```csharp
+var metadata = new Dictionary<string, string>
+{
+    { "uploadedBy", userId },
+    { "fileType", "invoice" },
+    { "department", "finance" }
+};
+
+await blobClient.UploadAsync(stream, metadata: metadata);
+
+// Retrieve metadata
+var properties = await blobClient.GetPropertiesAsync();
+var uploadedBy = properties.Value.Metadata["uploadedBy"];
+```
+
+### Lifecycle Management
+
+```json
+// Configure in Azure Portal or via Bicep
+{
+  "rules": [
+    {
+      "name": "deleteOldBackups",
+      "enabled": true,
+      "type": "Lifecycle",
+      "definition": {
+        "filters": {
+          "blobTypes": ["blockBlob"],
+          "prefixMatch": ["backups/"]
+        },
+        "actions": {
+          "baseBlob": {
+            "delete": {
+              "daysAfterModificationGreaterThan": 30
+            }
+          }
+        }
+      }
+    }
+  ]
+}
+```
+
+---
+
+## Bicep Configuration
+
+```bicep
+resource storageAccount 'Microsoft.Storage/storageAccounts@2023-01-01' = {
+  name: storageAccountName
+  location: location
+  sku: {
+    name: 'Standard_LRS'
+  }
+  kind: 'StorageV2'
+  properties: {
+    allowBlobPublicAccess: false
+    minimumTlsVersion: 'TLS1_2'
+    supportsHttpsTrafficOnly: true
+  }
+}
+
+// Grant Container App Blob access
+resource blobRoleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
+  scope: storageAccount
+  name: guid(storageAccount.id, principalId, 'Storage Blob Data Contributor')
+  properties: {
+    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'ba92f5b4-2d11-453d-a403-e96b0029c9fe')
+    principalId: principalId
+  }
+}
+```
+
+---
+
+## References
+
+- [Azure Blob Storage](https://learn.microsoft.com/azure/storage/blobs/)
+- [Azure Queue Storage](https://learn.microsoft.com/azure/storage/queues/)
+- [Azure Table Storage](https://learn.microsoft.com/azure/storage/tables/)
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/.morph/framework/standards/infrastructure/docker/easypanel-deploy.md

@@ -0,0 +1,196 @@
+# EasyPanel Deployment Standard
+
+> **Scope:** nextjs-supabase
+> **Layer:** 2 (on keyword)
+> **Keywords:** easypanel, docker, deploy, deployment, container
+> **Load When:** easypanel or docker deployment keywords detected
+
+Stack: Next.js 15 + Supabase + .NET Backend
+
+## Core Rules
+
+- ALWAYS use multi-stage Docker builds for minimal image size
+- ALWAYS configure health checks for zero-downtime deploys
+- NEVER hardcode secrets in Dockerfiles -- use EasyPanel environment variables
+- ALWAYS use `.dockerignore` to exclude node_modules, .git, .env files
+- SSL is automatic via Let's Encrypt -- no manual certificate management
+
+## .NET 10 Dockerfile
+
+```dockerfile
+FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
+WORKDIR /src
+COPY *.csproj .
+RUN dotnet restore
+COPY . .
+RUN dotnet publish -c Release -o /app/publish --no-restore
+
+FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS runtime
+WORKDIR /app
+RUN adduser --disabled-password --gecos "" appuser
+USER appuser
+COPY --from=build /app/publish .
+ENV ASPNETCORE_URLS=http://+:8080
+EXPOSE 8080
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD curl -f http://localhost:8080/health || exit 1
+ENTRYPOINT ["dotnet", "MyApp.Api.dll"]
+```
+
+## Next.js Standalone Dockerfile
+
+```dockerfile
+FROM node:22-alpine AS base
+
+FROM base AS builder
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+COPY . .
+ENV NEXT_TELEMETRY_DISABLED=1
+RUN npm run build
+
+FROM base AS runner
+WORKDIR /app
+ENV NODE_ENV=production NEXT_TELEMETRY_DISABLED=1
+RUN addgroup --system --gid 1001 nodejs && adduser --system --uid 1001 nextjs
+COPY --from=builder /app/public ./public
+COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
+COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
+USER nextjs
+EXPOSE 3000
+ENV PORT=3000 HOSTNAME="0.0.0.0"
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/api/health || exit 1
+CMD ["node", "server.js"]
+```
+
+Required: `output: "standalone"` in `next.config.ts`.
+
+## .dockerignore
+
+```
+node_modules
+.next
+.git
+.env*
+*.md
+.vscode
+coverage
+test
+__tests__
+```
+
+## EasyPanel Service Config
+
+| Setting | .NET Backend | Next.js Frontend |
+|---------|-------------|-----------------|
+| Source | GitHub | GitHub |
+| Build method | Dockerfile | Dockerfile |
+| Dockerfile path | `./backend/Dockerfile` | `./frontend/Dockerfile` |
+| Port | 8080 | 3000 |
+| Domain | api.example.com | app.example.com |
+
+### GitHub Integration
+
+1. Generate GitHub PAT with `repo` scope
+2. EasyPanel: Settings > GitHub > Add token
+3. Select repository and branch
+4. Enable "Auto Deploy" for webhook-triggered deploys
+
+### Domain and SSL
+
+DNS setup (CNAME to EasyPanel server):
+```
+app.example.com  CNAME  your-server.easypanel.host
+api.example.com  CNAME  your-server.easypanel.host
+```
+
+SSL via Let's Encrypt is automatic. Force HTTPS enabled by default.
+
+## Environment Variables
+
+### .NET Backend
+
+```env
+ASPNETCORE_ENVIRONMENT=Production
+ASPNETCORE_URLS=http://+:8080
+ConnectionStrings__DefaultConnection=Host=...;Database=...;Username=...;Password=...
+Supabase__Url=https://xxx.supabase.co
+Supabase__ServiceRoleKey=eyJ...
+Supabase__JwtSecret=your-jwt-secret
+```
+
+### Next.js Frontend
+
+```env
+NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
+NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
+NEXT_PUBLIC_API_URL=https://api.example.com
+```
+
+## Health Check Endpoints
+
+```csharp
+// .NET: Program.cs
+builder.Services.AddHealthChecks()
+    .AddNpgSql(connectionString, name: "database");
+app.MapHealthChecks("/health");
+```
+
+```ts
+// Next.js: app/api/health/route.ts
+export async function GET() {
+  return Response.json({ status: "healthy", timestamp: new Date().toISOString() });
+}
+```
+
+## Zero-Downtime Deploys
+
+EasyPanel uses Docker HEALTHCHECK to determine container readiness:
+
+1. New container starts alongside old container
+2. Health check passes after start-period + retries
+3. Traffic shifts to new container
+4. Old container stopped
+
+| HEALTHCHECK Param | Value | Purpose |
+|-------------------|-------|---------|
+| `--interval` | 30s | Time between checks |
+| `--timeout` | 5s | Max response wait |
+| `--start-period` | 10s | Startup grace period |
+| `--retries` | 3 | Failures before unhealthy |
+
+## Monitoring
+
+- **Logs**: Real-time in EasyPanel UI
+- **Metrics**: CPU, memory, network via dashboard
+- **Restart**: Auto-restart on crash (default)
+
+Structured logging:
+
+```csharp
+// .NET: Serilog with JSON output
+builder.Host.UseSerilog((ctx, cfg) => cfg
+    .ReadFrom.Configuration(ctx.Configuration)
+    .WriteTo.Console(new JsonFormatter()));
+```
+
+```ts
+// Next.js: pino
+import pino from "pino";
+const logger = pino({ level: process.env.LOG_LEVEL ?? "info" });
+```
+
+## Deployment Checklist
+
+| Step | Action |
+|------|--------|
+| 1 | Verify `output: "standalone"` in next.config.ts |
+| 2 | Test Docker build locally |
+| 3 | Test health endpoint |
+| 4 | Configure env vars in EasyPanel |
+| 5 | Set up custom domain + DNS |
+| 6 | Verify SSL certificate |
+| 7 | Enable auto-deploy from GitHub |
+| 8 | Push to main, verify deployment |