feat(tracker): consume Core advisory architecture endpoints via BFF gateway

Extend the Tracker->Core integration to the Core's existing advisory surface
(ADR-0104), mirroring CoreEvaluationGateway conventions (same HttpClient/
options, envelope unwrapping, MockFallback, logging). Advisory Core responses
are treated as opaque JsonElement payloads (non-binding).

- CoreArchitectureGateway (ICoreArchitectureGateway): ListTopologies,
  GetTopology, RecommendTopology(signals), EvaluatePhaseArtifacts(phase,
  topologies, declaredArtifacts); deterministic fallback stubs when Core
  unavailable and MockFallback is on, shaped error otherwise
- BFF endpoints under /api/architecture: GET topologies, GET topologies/{id},
  POST recommend-topology, POST evaluate-phase-artifacts (ArchitectureRead)
- AddHttpClient<ICoreArchitectureGateway> configured like the eval gateway
- 6 gateway unit tests (path/verb/body + envelope + fallback)

Build clean; 74/74 tests pass.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: beyondnetPeru

src/apps/tracker-api/Tracker.Presentation/Endpoints/Integration/CoreArchitectureEndpoints.cs

@@ -0,0 +1,113 @@
+using Tracker.Presentation.Auth;
+using Tracker.Presentation.Integration;
+
+namespace Tracker.Presentation.Endpoints.Integration;
+
+public static class CoreArchitectureEndpoints
+{
+    public static void MapCoreArchitectureEndpoints(this IEndpointRouteBuilder app)
+    {
+        var group = app.MapGroup("/architecture")
+            .WithTags("Core Architecture");
+
+        group.MapGet("/topologies", async (
+            ICoreArchitectureGateway gateway,
+            ITrackerUserContext user,
+            CancellationToken ct) =>
+        {
+            try
+            {
+                return Results.Ok(await gateway.ListTopologiesAsync(ct));
+            }
+            catch (CoreArchitectureGatewayException ex)
+            {
+                return ToProblem(ex);
+            }
+        })
+        .WithName("ListCoreTopologies")
+        .RequireTrackerPermission(TrackerPermissions.ArchitectureRead)
+        .Produces(200)
+        .Produces(401)
+        .Produces(403)
+        .Produces(502);
+
+        group.MapGet("/topologies/{id}", async (
+            string id,
+            ICoreArchitectureGateway gateway,
+            ITrackerUserContext user,
+            CancellationToken ct) =>
+        {
+            try
+            {
+                return Results.Ok(await gateway.GetTopologyAsync(id, ct));
+            }
+            catch (CoreArchitectureGatewayException ex)
+            {
+                return ToProblem(ex);
+            }
+        })
+        .WithName("GetCoreTopology")
+        .RequireTrackerPermission(TrackerPermissions.ArchitectureRead)
+        .Produces(200)
+        .Produces(401)
+        .Produces(403)
+        .Produces(502);
+
+        group.MapPost("/recommend-topology", async (
+            RecommendTopologyRequest request,
+            ICoreArchitectureGateway gateway,
+            ITrackerUserContext user,
+            CancellationToken ct) =>
+        {
+            try
+            {
+                var signals = request.Signals ?? new Dictionary<string, object?>();
+                return Results.Ok(await gateway.RecommendTopologyAsync(signals, ct));
+            }
+            catch (CoreArchitectureGatewayException ex)
+            {
+                return ToProblem(ex);
+            }
+        })
+        .WithName("RecommendCoreTopology")
+        .RequireTrackerPermission(TrackerPermissions.ArchitectureRead)
+        .Produces(200)
+        .Produces(401)
+        .Produces(403)
+        .Produces(502);
+
+        group.MapPost("/evaluate-phase-artifacts", async (
+            EvaluatePhaseArtifactsRequest request,
+            ICoreArchitectureGateway gateway,
+            ITrackerUserContext user,
+            CancellationToken ct) =>
+        {
+            try
+            {
+                var result = await gateway.EvaluatePhaseArtifactsAsync(
+                    request.Phase ?? string.Empty,
+                    request.Topologies ?? [],
+                    request.DeclaredArtifacts ?? [],
+                    ct);
+                return Results.Ok(result);
+            }
+            catch (CoreArchitectureGatewayException ex)
+            {
+                return ToProblem(ex);
+            }
+        })
+        .WithName("EvaluateCorePhaseArtifacts")
+        .RequireTrackerPermission(TrackerPermissions.ArchitectureRead)
+        .Produces(200)
+        .Produces(401)
+        .Produces(403)
+        .Produces(502);
+    }
+
+    private static IResult ToProblem(CoreArchitectureGatewayException ex)
+    {
+        return Results.Json(
+            new { code = ex.Code, message = ex.Message },
+            statusCode: ex.StatusCode);
+    }
+}

src/apps/tracker-api/Tracker.Presentation/Endpoints/Integration/CoreEvaluationDtos.cs

@@ -82,6 +82,21 @@ public sealed class CoreEvaluationError
     public string Message { get; init; } = string.Empty;
 }
 
+// Body for POST /api/architecture/recommend-topology. Signals are arbitrary
+// technical inputs the Core weighs; the Tracker forwards them opaquely.
+public sealed class RecommendTopologyRequest
+{
+    public Dictionary<string, object?>? Signals { get; init; }
+}
+
+// Body for POST /api/architecture/evaluate-phase-artifacts.
+public sealed class EvaluatePhaseArtifactsRequest
+{
+    public string? Phase { get; init; }
+    public string[]? Topologies { get; init; }
+    public string[]? DeclaredArtifacts { get; init; }
+}
+
 // Mirrors the canonical Evolith Core EvaluationResult (ADR-0101): an
 // `overallVerdict` (PASS/FAIL/…) plus per-kind `results` (here we map the `gate`
 // kind). Unwrapped from the ADR-0073 `{ success, data }` envelope upstream.

src/apps/tracker-api/Tracker.Presentation/Integration/CoreArchitectureGateway.cs

@@ -0,0 +1,199 @@
+using System.Net.Http.Json;
+using System.Text.Json;
+using Microsoft.Extensions.Options;
+
+namespace Tracker.Presentation.Integration;
+
+/// <summary>
+/// Reads the Evolith Core's EXISTING advisory architecture surface (topology
+/// manifests, topology recommendation, phase-artifact evaluation). The Core is
+/// stateless and these responses are advisory / non-binding; the gateway treats
+/// them as opaque JSON payloads, unwrapping only the transport envelope
+/// (<c>data/result/value/payload</c>) before handing the inner element back.
+/// </summary>
+public interface ICoreArchitectureGateway
+{
+    Task<JsonElement> ListTopologiesAsync(CancellationToken cancellationToken);
+
+    Task<JsonElement> GetTopologyAsync(string id, CancellationToken cancellationToken);
+
+    Task<JsonElement> RecommendTopologyAsync(
+        IReadOnlyDictionary<string, object?> signals,
+        CancellationToken cancellationToken);
+
+    Task<JsonElement> EvaluatePhaseArtifactsAsync(
+        string phase,
+        IReadOnlyList<string> topologies,
+        IReadOnlyList<string> declaredArtifacts,
+        CancellationToken cancellationToken);
+}
+
+public sealed class CoreArchitectureGateway(
+    HttpClient httpClient,
+    IOptions<CoreEvaluationOptions> options,
+    ILogger<CoreArchitectureGateway> logger) : ICoreArchitectureGateway
+{
+    private static readonly JsonSerializerOptions JsonOptions = new(JsonSerializerDefaults.Web);
+    private readonly CoreEvaluationOptions _options = options.Value;
+
+    public Task<JsonElement> ListTopologiesAsync(CancellationToken cancellationToken)
+    {
+        return GetAsync(
+            "architecture/topologies",
+            () => CloneJson("[]"),
+            cancellationToken);
+    }
+
+    public Task<JsonElement> GetTopologyAsync(string id, CancellationToken cancellationToken)
+    {
+        return GetAsync(
+            $"architecture/topologies/{Uri.EscapeDataString(id)}",
+            () => CloneJson("{\"source\":\"tracker-bff-mock-fallback\"}"),
+            cancellationToken);
+    }
+
+    public Task<JsonElement> RecommendTopologyAsync(
+        IReadOnlyDictionary<string, object?> signals,
+        CancellationToken cancellationToken)
+    {
+        var payload = new Dictionary<string, object?> { ["signals"] = signals };
+        return PostAsync(
+            "architecture/recommend-topology",
+            payload,
+            () => CloneJson(
+                "{\"recommended\":\"modular-monolith\",\"rationale\":\"mock-fallback\",\"source\":\"tracker-bff-mock-fallback\"}"),
+            cancellationToken);
+    }
+
+    public Task<JsonElement> EvaluatePhaseArtifactsAsync(
+        string phase,
+        IReadOnlyList<string> topologies,
+        IReadOnlyList<string> declaredArtifacts,
+        CancellationToken cancellationToken)
+    {
+        var payload = new Dictionary<string, object?>
+        {
+            ["phase"] = phase,
+            ["topologies"] = topologies,
+            ["declaredArtifacts"] = declaredArtifacts
+        };
+        return PostAsync(
+            "architecture/evaluate-phase-artifacts",
+            payload,
+            () => CloneJson(
+                "{\"completeness\":0,\"required\":[],\"present\":[],\"missing\":[],\"source\":\"tracker-bff-mock-fallback\"}"),
+            cancellationToken);
+    }
+
+    private async Task<JsonElement> GetAsync(
+        string path,
+        Func<JsonElement> fallback,
+        CancellationToken cancellationToken)
+    {
+        try
+        {
+            using var response = await httpClient.GetAsync(path, cancellationToken);
+            return await HandleResponseAsync(response, path, fallback, cancellationToken);
+        }
+        catch (Exception ex) when (ex is HttpRequestException or TaskCanceledException or JsonException)
+        {
+            return HandleException(ex, path, fallback);
+        }
+    }
+
+    private async Task<JsonElement> PostAsync(
+        string path,
+        object payload,
+        Func<JsonElement> fallback,
+        CancellationToken cancellationToken)
+    {
+        try
+        {
+            using var response = await httpClient.PostAsJsonAsync(path, payload, JsonOptions, cancellationToken);
+            return await HandleResponseAsync(response, path, fallback, cancellationToken);
+        }
+        catch (Exception ex) when (ex is HttpRequestException or TaskCanceledException or JsonException)
+        {
+            return HandleException(ex, path, fallback);
+        }
+    }
+
+    private async Task<JsonElement> HandleResponseAsync(
+        HttpResponseMessage response,
+        string path,
+        Func<JsonElement> fallback,
+        CancellationToken cancellationToken)
+    {
+        var responseJson = await response.Content.ReadAsStringAsync(cancellationToken);
+
+        if (!response.IsSuccessStatusCode)
+        {
+            if (_options.MockFallback)
+            {
+                logger.LogWarning(
+                    "Core architecture request {Path} failed with {StatusCode}; returning configured mock fallback. Body: {Body}",
+                    path,
+                    (int)response.StatusCode,
+                    responseJson);
+                return fallback();
+            }
+
+            throw new CoreArchitectureGatewayException(
+                "CoreArchitecture.HttpError",
+                $"Core architecture request '{path}' failed with HTTP {(int)response.StatusCode}.",
+                (int)response.StatusCode);
+        }
+
+        using var document = JsonDocument.Parse(responseJson);
+        return ExtractEnvelopePayload(document.RootElement).Clone();
+    }
+
+    private JsonElement HandleException(Exception ex, string path, Func<JsonElement> fallback)
+    {
+        if (_options.MockFallback)
+        {
+            logger.LogWarning(ex, "Core architecture request {Path} unavailable; returning configured mock fallback.", path);
+            return fallback();
+        }
+
+        throw new CoreArchitectureGatewayException(
+            "CoreArchitecture.Unavailable",
+            ex.Message,
+            502);
+    }
+
+    // Mirrors CoreEvaluationGateway.ExtractEnvelopePayload: unwrap the transport
+    // envelope so callers see the inner advisory payload, not the { success, data }
+    // wrapper (ADR-0073).
+    private static JsonElement ExtractEnvelopePayload(JsonElement root)
+    {
+        foreach (var propertyName in new[] { "data", "result", "value", "payload" })
+        {
+            if (root.ValueKind == JsonValueKind.Object && root.TryGetProperty(propertyName, out var payload))
+            {
+                return payload;
+            }
+        }
+
+        return root;
+    }
+
+    private static JsonElement CloneJson(string json)
+    {
+        using var document = JsonDocument.Parse(json);
+        return document.RootElement.Clone();
+    }
+}
+
+/// <summary>
+/// Shaped error surfaced when the Core architecture surface is unavailable or
+/// errors and MockFallback is disabled. Endpoints translate this into a problem
+/// response.
+/// </summary>
+public sealed class CoreArchitectureGatewayException(string code, string message, int statusCode)
+    : Exception(message)
+{
+    public string Code { get; } = code;
+
+    public int StatusCode { get; } = statusCode;
+}

src/apps/tracker-api/Tracker.Presentation/Program.cs

@@ -31,6 +31,20 @@
     }
 });
 
+// Advisory architecture surface reuses the SAME Core base address + options as
+// the evaluation gateway (CoreApi section, /api/v1 base, optional Bearer key).
+builder.Services.AddHttpClient<ICoreArchitectureGateway, CoreArchitectureGateway>((sp, client) =>
+{
+    var options = sp.GetRequiredService<Microsoft.Extensions.Options.IOptions<CoreEvaluationOptions>>().Value;
+    client.BaseAddress = new Uri(options.BaseUrl.TrimEnd('/') + "/");
+    client.Timeout = TimeSpan.FromMilliseconds(options.TimeoutMs);
+    if (!string.IsNullOrWhiteSpace(options.ApiKey))
+    {
+        client.DefaultRequestHeaders.Authorization =
+            new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", options.ApiKey);
+    }
+});
+
 builder.Services.AddEndpointsApiExplorer();
 builder.Services.AddSwaggerGen(c =>
 {
@@ -72,6 +86,7 @@
 api.MapArchitectureReferenceEndpoints();
 api.MapCoreEvaluationEndpoints();
 api.MapCoreEvaluationTransactionEndpoints();
+api.MapCoreArchitectureEndpoints();
 
 app.MapGet("/health", () => Results.Ok(new { status = "healthy", timestamp = DateTime.UtcNow }));
 api.MapGet("/health", () => Results.Ok(new { status = "healthy", timestamp = DateTime.UtcNow }));