Well-Architected microservices-oriented applications on Azure

using MediatR;

namespace Gcm.Calculation.Features.CalculateGcm;

// ---- Contract (public shape returned to the portal right-rail) ----
public sealed record CalculateGcmCommand(Guid RequestId, decimal RealizationOverride)
    : IRequest<GcmResult>;

public sealed record GcmResult(decimal GcmPercent, decimal Realization, decimal Yield);

// ---- Endpoint: one minimal-API route, one authorization policy ----
public static class CalculateGcmEndpoint
{
    public static void Map(IEndpointRouteBuilder app) => app
        .MapPost("/gcm/{requestId:guid}/calculate",
            async (Guid requestId, CalculateGcmRequest body, ISender sender) =>
            {
                var result = await sender.Send(
                    new CalculateGcmCommand(requestId, body.RealizationOverride));
                return Results.Ok(result);
            })
        .RequireAuthorization("gcm.calculate")     // fine-grained policy
        .WithName("CalculateGcm");
}

public sealed record CalculateGcmRequest(decimal RealizationOverride);

// ---- Handler: business logic for THIS feature only ----
public sealed class CalculateGcmHandler(
    GcmDbContext db, IEventPublisher events)
    : IRequestHandler<CalculateGcmCommand, GcmResult>
{
    public async Task<GcmResult> Handle(CalculateGcmCommand cmd, CancellationToken ct)
    {
        var request = await db.Requests.FindAsync([cmd.RequestId], ct)
            ?? throw new NotFoundException(cmd.RequestId);

        // Aggregate enforces invariants; returns a new calculation.
        var calc = request.Calculate(cmd.RealizationOverride);

        // Transactional outbox: state + event committed atomically.
        db.Outbox.Add(GcmCalculated.From(request.Id, calc));
        await db.SaveChangesAsync(ct);

        return new GcmResult(calc.GcmPercent, calc.Realization, calc.Yield);
    }
}

using FluentValidation;

namespace Gcm.Calculation.Features.CalculateGcm;

public sealed class CalculateGcmValidator : AbstractValidator<CalculateGcmCommand>
{
    public CalculateGcmValidator()
    {
        RuleFor(x => x.RequestId).NotEmpty();
        RuleFor(x => x.RealizationOverride)
            .InclusiveBetween(0m, 2.0m)   // 0%..200% realization
            .WithMessage("Realization override must be between 0% and 200%.");
    }
}

// Registered once as a MediatR pipeline behavior; runs before every handler.
public sealed class ValidationBehavior<TReq, TRes>(
    IEnumerable<IValidator<TReq>> validators)
    : IPipelineBehavior<TReq, TRes> where TReq : notnull
{
    public async Task<TRes> Handle(
        TReq request, RequestHandlerDelegate<TRes> next, CancellationToken ct)
    {
        foreach (var v in validators)
            await v.ValidateAndThrowAsync(request, ct);
        return await next();
    }
}

namespace Gcm.Calculation.Domain;

// Aggregate root: the ONLY place XYZ invariants live.
public sealed class GcmRequest
{
    public Guid Id { get; private set; }
    public decimal FeeBilling { get; private set; }
    public decimal DirectCosts { get; private set; }
    public decimal GeneratedExpenses { get; private set; }
    private decimal _standardRealization = 1.0m;

    public Calculation Calculate(decimal realizationOverride)
    {
        if (realizationOverride is < 0m or > 2.0m)
            throw new DomainException("Realization out of allowed range.");

        var realization = realizationOverride == 0m
            ? _standardRealization : realizationOverride;

        var revenue = FeeBilling * realization;
        var cost    = DirectCosts + GeneratedExpenses;
        var gcm     = revenue == 0 ? 0 : (revenue - cost) / revenue;   // XYZ %
        var yield   = revenue - cost;

        return new Calculation(
            GcmPercent: decimal.Round(gcm * 100, 0),
            Realization: decimal.Round(realization * 100, 0),
            Yield: decimal.Round(yield, 0));
    }
}

public sealed record Calculation(decimal GcmPercent, decimal Realization, decimal Yield);

import { useServerEvents } from "@/lib/useServerEvents";

export function GcmRequestPage({ requestId }: { requestId: string }) {
  // Right-rail read model, pushed from the server (near real time).
  const live = useServerEvents(`/api/live/gcm/${requestId}`, {
    gcm: { gcmPercent: 60, realization: 108, yield: 1000 },
  });

  return (
    <div className="portal-grid">            {/* CSS grid: main 1fr / rail 300px */}
      <EngagementForm requestId={requestId} />   {/* parent/child CRUD tablix */}
      <aside className="rail">
        <GcmGauge value={live.gcm.gcmPercent} />      {/* the big 60% */}
        <Realization value={live.gcm.realization} yield={live.gcm.yield} />
        <SystemFeed items={live.feed} />              {/* Azure updates / health */}
      </aside>
    </div>
  );
}

import { useEffect, useState } from "react";

// Thin EventSource wrapper: auto-reconnect, Last-Event-ID, multiplexed events.
export function useServerEvents<T>(url: string, initial: T): T & { feed: string[] } {
  const [state, setState] = useState({ ...initial, feed: [] as string[] });

  useEffect(() => {
    const es = new EventSource(url, { withCredentials: true });
    es.addEventListener("gcm", (e) =>
      setState((s) => ({ ...s, gcm: JSON.parse((e as MessageEvent).data) })));
    es.addEventListener("system", (e) =>
      setState((s) => ({ ...s, feed: [(e as MessageEvent).data, ...s.feed].slice(0, 5) })));
    es.onerror = () => { /* browser retries automatically with Last-Event-ID */ };
    return () => es.close();
  }, [url]);

  return state as T & { feed: string[] };
}

{
  "$schema": "https://json.schemastore.org/staticwebapp.config.json",
  "navigationFallback": { "rewrite": "/index.html", "exclude": ["/assets/*"] },
  "routes": [
    { "route": "/api/*", "allowedRoles": ["authenticated"] },
    { "route": "/admin/*", "allowedRoles": ["gcm.admin"] }
  ],
  "auth": {
    "identityProviders": {
      "azureActiveDirectory": {
        "registration": {
          "openIdIssuer": "https://login.microsoftonline.com/<tenant>/v2.0",
          "clientIdSettingName": "AAD_CLIENT_ID",
          "clientSecretSettingName": "AAD_CLIENT_SECRET"
        }
      }
    }
  },
  "globalHeaders": {
    "Content-Security-Policy": "default-src 'self'; connect-src 'self' https://*.azure-api.net",
    "X-Content-Type-Options": "nosniff",
    "Strict-Transport-Security": "max-age=63072000; includeSubDomains; preload"
  }
}

import { Suspense, lazy } from "react";
import { ErrorBoundary } from "./ErrorBoundary";
import { REMOTES, type SlotId } from "./slots.config";

// The shell renders a slot by loading whatever remote is registered for it.
// It knows the CONTRACT (props in / events out), never the remote's internals.
export function SlotHost({ slot, ctx }: { slot: SlotId; ctx: SlotContext }) {
  const entry = REMOTES[slot];
  if (!entry) return null;                       // slot empty = render nothing

  const Remote = lazy(entry.load);               // dynamic import of the remote
  return (
    <section className={`slot slot-${slot}`} data-slot={slot}>
      <ErrorBoundary fallback={<SlotFallback slot={slot} />}>   {/* bad remote degrades, never white-screens */}
        <Suspense fallback={<SlotSkeleton />}>
          <Remote {...entry.props} context={ctx} />   {/* versioned contract */}
        </Suspense>
      </ErrorBoundary>
    </section>
  );
}

// portal/src/shell/slots.config.ts
// The registry maps slots -> remote pointers. Each pointer is versioned and
// canaried like a backend revision; changing it needs NO shell rebuild.
export type SlotId = "main" | "rail-1" | "rail-2";

export interface RemoteEntry {
  team: string;
  version: string;
  load: () => Promise<{ default: React.ComponentType<any> }>;
  props?: Record<string, unknown>;
}

export const REMOTES: Record<SlotId, RemoteEntry> = {
  "main":   { team: "engagement", version: "2.3",
              load: () => import("engagement/Form") },
  "rail-1": { team: "gcm-calc",   version: "1.4",
              load: () => import("gcmGauge/Widget") },
  "rail-2": { team: "rate-tables",version: "3.0",
              load: () => import("pyBilling/Widget") },
};

// Slot contract every remote must honor (props in, events out).
export interface SlotContext {
  requestId: string;
  tokens: DesignTokens;                 // shared theme = no divergent styling
  emit: (event: string, detail: unknown) => void;  // remote -> shell events
}

// portal/vite.config.mfe.ts  (host shell)
import { defineConfig } from "vite";
import federation from "@originjs/vite-plugin-federation";

export default defineConfig({
  plugins: [
    federation({
      name: "shell",
      remotes: {
        // Each remote is a separately deployed bundle (own SWA or CDN path).
        engagement: "https://gcm.contoso.com/remotes/engagement/remoteEntry.js",
        gcmGauge:   "https://gcm.contoso.com/remotes/gcm-gauge/remoteEntry.js",
        pyBilling:  "https://gcm.contoso.com/remotes/py-billing/remoteEntry.js",
      },
      shared: ["react", "react-dom"],   // singletons — one copy across remotes
    }),
  ],
});

/* The remote adapts to its SLOT size, not the screen. It renders correctly
   whether the shell drops it in the wide rail, a drawer, or a mobile sheet. */
.gauge { container-type: inline-size; }

@container (min-width: 240px) {
  .gauge .value    { font-size: 44px; }
  .gauge .subtext  { display: block; }
}
@container (max-width: 239px) {
  .gauge .value    { font-size: 24px; }
  .gauge .subtext  { display: none; }   /* compact form in a narrow slot */
}

/* portal/src/shell/shell.css  — the shell owns cross-cutting region policy */
.portal-grid {
  display: grid;
  grid-template-columns: 150px 1fr 300px;      /* nav | main | rail */
  grid-template-areas: "nav main rail";
}

/* Narrow: rails leave the grid and become a bottom sheet; nav collapses. */
@media (max-width: 860px) {
  .portal-grid { grid-template-columns: 1fr; grid-template-areas: "main"; }
  .slot-rail-1, .slot-rail-2 { position: fixed; bottom: 0; left: 0; right: 0; }
  .left-nav { transform: translateX(-100%); }  /* behind a hamburger */
}

public static class StreamGcmEndpoint
{
    public static void Map(IEndpointRouteBuilder app) => app
        .MapGet("/live/gcm/{id:guid}", async (
            Guid id, HttpContext ctx, IConnectionMultiplexer redis,
            CancellationToken ct) =>
        {
            ctx.Response.Headers.ContentType = "text/event-stream";
            ctx.Response.Headers.CacheControl = "no-cache";
            ctx.Response.Headers["X-Accel-Buffering"] = "no";

            var sub = redis.GetSubscriber();
            var channel = $"gcm:{id}";                 // authorized per-request channel

            await sub.SubscribeAsync(channel, async (_, msg) =>
            {
                // msg = {"event":"gcm","data":{...}} produced by the projector
                var frame = SseFrame.Parse(msg!);
                await ctx.Response.WriteAsync(
                    $"event: {frame.Event}\nid: {frame.Id}\ndata: {frame.Data}\n\n", ct);
                await ctx.Response.Body.FlushAsync(ct);
            });

            // Keep-alive comment every 15s so proxies don't drop the stream.
            while (!ct.IsCancellationRequested)
            {
                await ctx.Response.WriteAsync(": keep-alive\n\n", ct);
                await ctx.Response.Body.FlushAsync(ct);
                await Task.Delay(TimeSpan.FromSeconds(15), ct);
            }
        })
        .RequireAuthorization("gcm.read");
}

// Background worker: pulls external sources, normalizes, publishes to Redis.
public sealed class ExternalFeedWorker(
    IHttpClientFactory http, IConnectionMultiplexer redis, ILogger<ExternalFeedWorker> log)
    : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken ct)
    {
        var sources = new (string Name, string Url)[]
        {
            ("azure-updates",  "https://www.microsoft.com/releasecommunications/api/v2/azure/rss"),
            ("service-health", "https://management.azure.com/.../events?api-version=2022-10-01"),
            ("marketplace",    "https://catalogapi.azure.com/products?api-version=2023-01-01"),
        };
        var sub = redis.GetSubscriber();

        while (!ct.IsCancellationRequested)
        {
            foreach (var (name, url) in sources)
            {
                try
                {
                    var client = http.CreateClient("feeds");   // managed identity for ARM calls
                    var items = await FeedReader.ReadAsync(client, url, ct);
                    foreach (var item in items)
                        await sub.PublishAsync("system:status",
                            SseFrame.System(name, item).ToJson());
                }
                catch (Exception ex) { log.LogWarning(ex, "Feed {Name} failed", name); }
            }
            await Task.Delay(TimeSpan.FromSeconds(30), ct);   // < 5s for domain, ≤30s external
        }
    }
}

// Runs in-process; polls the outbox and publishes, marking rows dispatched.
public sealed class OutboxDispatcher(
    IServiceScopeFactory scopes, ServiceBusSender sender, ILogger<OutboxDispatcher> log)
    : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken ct)
    {
        while (!ct.IsCancellationRequested)
        {
            using var scope = scopes.CreateScope();
            var db = scope.ServiceProvider.GetRequiredService<GcmDbContext>();

            var batch = await db.Outbox
                .Where(o => o.DispatchedUtc == null)
                .OrderBy(o => o.OccurredUtc).Take(100).ToListAsync(ct);

            foreach (var evt in batch)
            {
                var msg = new ServiceBusMessage(evt.Payload)
                {
                    MessageId = evt.Id.ToString(),      // broker-side de-dupe
                    Subject   = evt.Type,
                    SessionId = evt.AggregateId.ToString()
                };
                await sender.SendMessageAsync(msg, ct);
                evt.DispatchedUtc = DateTime.UtcNow;
            }
            await db.SaveChangesAsync(ct);
            await Task.Delay(TimeSpan.FromMilliseconds(500), ct);
        }
    }
}

// Consumers are idempotent: a processed-message table guards re-delivery.
public sealed class GcmCalculatedConsumer(ReadModelDbContext db)
{
    public async Task Handle(ServiceBusReceivedMessage msg, CancellationToken ct)
    {
        if (await db.Processed.AnyAsync(p => p.MessageId == msg.MessageId, ct))
            return;                                   // already applied — skip

        var e = msg.Body.ToObjectFromJson<GcmCalculated>();
        var row = await db.Requests.FindAsync([e.RequestId], ct)
                  ?? new RequestListItem { Id = e.RequestId };
        row.ExpectedGcm = e.GcmPercent;               // update the "My XYZ Requests" list
        row.Status = "Draft";
        db.Requests.Update(row);
        db.Processed.Add(new Processed(msg.MessageId, DateTime.UtcNow));
        await db.SaveChangesAsync(ct);                // state + dedupe committed together
    }
}

<inbound>
  <validate-jwt header-name="Authorization" failed-validation-httpcode="401">
    <openid-config url="https://login.microsoftonline.com/{{tenant}}/v2.0/.well-known/openid-configuration" />
    <audiences><audience>api://gcm</audience></audiences>
    <required-claims>
      <claim name="scp" match="any"><value>gcm.access</value></claim>
    </required-claims>
  </validate-jwt>
  <rate-limit-by-key calls="600" renewal-period="60"
      counter-key="@(context.Request.Headers.GetValueOrDefault('Authorization'))" />
  <set-backend-service backend-id="aca-engagement" />
</inbound>

// Fine-grained: not just "is a partner", but "owns THIS request's market".
public sealed class ApproveRequestAuthorizer(IOrgGraph org) : IAuthorizationHandler
{
    public async Task<bool> CanApprove(ClaimsPrincipal user, Guid requestId)
    {
        var market  = await org.MarketForRequest(requestId);
        var userOid = user.FindFirstValue("oid");

        // Relationship-based check against the org graph + Entra app roles.
        var isApprover = user.IsInRole("gcm.approver");
        var inMarket   = await org.IsPartnerInMarket(userOid, market);
        var notSelf    = await org.RequesterOf(requestId) != userOid;   // no self-approval

        return isApprover && inMarket && notSelf;
    }
}

# --- build ---
FROM mcr.microsoft.com/dotnet/sdk:9.0 AS build
WORKDIR /src
COPY *.sln ./
COPY services/gcm-calculation/*.csproj services/gcm-calculation/
RUN dotnet restore services/gcm-calculation
COPY . .
RUN dotnet publish services/gcm-calculation -c Release -o /app \
    /p:PublishTrimmed=false /p:UseAppHost=false

# --- runtime (distroless, non-root, read-only) ---
FROM mcr.microsoft.com/dotnet/aspnet:9.0-noble-chiseled AS final
WORKDIR /app
COPY --from=build /app .
USER $APP_UID
ENV ASPNETCORE_HTTP_PORTS=8080
EXPOSE 8080
HEALTHCHECK CMD ["dotnet", "healthcheck.dll", "--url", "http://localhost:8080/health/ready"]
ENTRYPOINT ["dotnet", "Gcm.Calculation.dll"]

resource "azurerm_container_app" "gcm_calc" {
  name                         = "aca-gcm-calc"
  container_app_environment_id = azurerm_container_app_environment.main.id
  resource_group_name          = azurerm_resource_group.app.name
  revision_mode                = "Multiple"          # enables canary traffic split

  identity { type = "UserAssigned"
             identity_ids = [azurerm_user_assigned_identity.gcm_calc.id] }

  ingress {
    external_enabled = false                          # private; only APIM calls it
    target_port      = 8080
    transport        = "http"
    traffic_weight { latest_revision = true  percentage = 90 }
    traffic_weight { revision_suffix = "stable" percentage = 10 }
  }

  template {
    min_replicas = 0                                  # scale-to-zero (Consumption)
    max_replicas = 10
    container {
      name   = "gcm-calc"
      image  = "${azurerm_container_registry.acr.login_server}/gcm-calc@${var.image_digest}"
      cpu    = 0.5
      memory = "1Gi"
      liveness_probe  { transport = "HTTP" port = 8080 path = "/health/live" }
      readiness_probe { transport = "HTTP" port = 8080 path = "/health/ready" }
    }
    custom_scale_rule {
      name             = "sb-queue"
      custom_rule_type = "azure-servicebus"
      metadata = { queueName = "gcm-calc", messageCount = "20" }
    }
  }
}

resource "azurerm_container_app_environment" "main" {
  name                       = "cae-gcm-${var.ring}"
  location                   = var.location
  resource_group_name        = var.rg_name
  log_analytics_workspace_id = var.law_id
  infrastructure_subnet_id   = var.aca_subnet_id
  zone_redundancy_enabled    = true                 # 99.95%+ target
  internal_load_balancer_enabled = true             # private ingress only
  tags = var.tags
}

resource "azurerm_container_app_environment_storage" "shared" {
  name                         = "artifacts"
  container_app_environment_id = azurerm_container_app_environment.main.id
  account_name                 = var.storage_account_name
  share_name                   = var.file_share_name
  access_key                   = var.storage_access_key
  access_mode                  = "ReadOnly"
}

output "environment_id" { value = azurerm_container_app_environment.main.id }

// infra/bicep/modules/aca-env.bicep
param ring string
param location string = resourceGroup().location
param lawId string
param acaSubnetId string
param tags object = {}

resource cae 'Microsoft.App/managedEnvironments@2024-03-01' = {
  name: 'cae-gcm-${ring}'
  location: location
  tags: tags
  properties: {
    appLogsConfiguration: {
      destination: 'log-analytics'
      logAnalyticsConfiguration: { customerId: lawId }
    }
    zoneRedundant: true
    vnetConfiguration: {
      infrastructureSubnetId: acaSubnetId
      internal: true
    }
  }
}

output environmentId string = cae.id

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "ring": { "type": "string" },
    "lawId": { "type": "string" },
    "acaSubnetId": { "type": "string" }
  },
  "resources": [
    {
      "type": "Microsoft.App/managedEnvironments",
      "apiVersion": "2024-03-01",
      "name": "[concat('cae-gcm-', parameters('ring'))]",
      "location": "[resourceGroup().location]",
      "properties": {
        "zoneRedundant": true,
        "vnetConfiguration": {
          "infrastructureSubnetId": "[parameters('acaSubnetId')]",
          "internal": true
        },
        "appLogsConfiguration": {
          "destination": "log-analytics",
          "logAnalyticsConfiguration": { "customerId": "[parameters('lawId')]" }
        }
      }
    }
  ],
  "outputs": {
    "environmentId": {
      "type": "string",
      "value": "[resourceId('Microsoft.App/managedEnvironments', concat('cae-gcm-', parameters('ring')))]"
    }
  }
}

name: build-and-promote
on:
  push: { branches: [main] }

permissions:
  id-token: write          # OIDC federation to Azure
  contents: read
  packages: write

jobs:
  build:
    runs-on: ubuntu-latest
    outputs: { digest: ${{ steps.push.outputs.digest }} }
    steps:
      - uses: actions/checkout@v4
      - uses: azure/login@v2
        with:
          client-id: ${{ vars.AZURE_CLIENT_ID }}
          tenant-id: ${{ vars.AZURE_TENANT_ID }}
          subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}
      - name: Build, scan & push image
        id: push
        run: |
          az acr build -r $ACR -t gcm-calc:$GITHUB_SHA services/gcm-calculation
          trivy image --exit-code 1 --severity CRITICAL $ACR.azurecr.io/gcm-calc:$GITHUB_SHA
          echo "digest=$(az acr repository show -n $ACR --image gcm-calc:$GITHUB_SHA \
            --query digest -o tsv)" >> $GITHUB_OUTPUT

  dogfood:
    needs: build
    environment: dogfood
    runs-on: ubuntu-latest
    steps:
      - uses: hashicorp/setup-terraform@v3
      - run: terraform -chdir=infra/terraform apply -auto-approve \
               -var-file=envs/dogfood.tfvars -var=image_digest=${{ needs.build.outputs.digest }}
      - run: ./scripts/smoke-and-contract-tests.sh dogfood

  canary:
    needs: [build, dogfood]
    environment: canary          # requires 1 reviewer + green SLO gate
    runs-on: ubuntu-latest
    steps:
      - run: terraform -chdir=infra/terraform apply -auto-approve \
               -var-file=envs/canary.tfvars -var=image_digest=${{ needs.build.outputs.digest }}
      - run: ./scripts/watch-slo.sh --error-budget 0.1 --window 15m   # auto-rollback on burn
  # private-preview / public-preview / ga follow the same shape with stricter approvals

builder.Services.AddOpenTelemetry()
    .ConfigureResource(r => r.AddService("gcm-calculation"))
    .WithTracing(t => t
        .AddAspNetCoreInstrumentation()
        .AddHttpClientInstrumentation()
        .AddSqlClientInstrumentation()
        .AddSource("Gcm.Calculation")
        .AddAzureMonitorTraceExporter())        // connection string from Key Vault
    .WithMetrics(m => m
        .AddAspNetCoreInstrumentation()
        .AddRuntimeInstrumentation()
        .AddMeter("Gcm.Calculation")
        .AddAzureMonitorMetricExporter());

// Custom business metric surfaced on the ops dashboard.
var meter = new Meter("Gcm.Calculation");
var calcDuration = meter.CreateHistogram<double>("gcm.calc.duration.ms");

resource "azurerm_monitor_scheduled_query_rules_alert_v2" "gcm_error_budget" {
  name                = "gcm-calc-error-budget-burn"
  resource_group_name = var.rg_name
  location            = var.location
  severity            = 1
  evaluation_frequency = "PT5M"
  window_duration      = "PT15M"
  scopes = [var.app_insights_id]

  criteria {
    query = <<-KQL
      requests
      | where cloud_RoleName == "gcm-calculation"
      | summarize failRate = 100.0 * countif(success == false) / count()
    KQL
    operator  = "GreaterThan"
    threshold = 1                 # > 1% error rate over 15m
    time_aggregation_method = "Average"
  }
  action { action_groups = [var.oncall_action_group_id] }
}