Add back-office tenant overview with dashboard, accounts, users, billing events, and Stripe reconciliation

AGENTS.md

@@ -1,3 +1,15 @@
+## Behavioral Guidelines
+
+1. **Think before coding.** State assumptions explicitly. If uncertain, ask rather than guess. When multiple interpretations exist, present them - don't pick silently.
+
+2. **Goal-driven execution.** Define success criteria before iterating. Loop until verified. Strong success criteria let you loop independently; "make it work" requires constant clarification.
+
+3. **Read before you write.** Before adding code in a file, read the file's exports, the immediate caller, and obvious shared utilities. "Looks orthogonal to me" is the most dangerous phrase in this codebase.
+
+4. **Checkpoint significant steps.** After each step in a multi-step task, summarize what was done, what's verified, and what's left. Don't continue from a state you can't describe back.
+
+5. **Fail loud.** Surface uncertainty, don't hide it. "Completed" is wrong if anything was skipped silently. "Tests pass" is wrong if any were skipped. "Feature works" is wrong if the edge case wasn't verified.
+
 ## Build, Test, and Format
 
 Use the developer CLI skills (`build`, `test`, `format`, `lint`, `e2e`, `aspire-restart`, `team-interrupt`) for all code workflows. They invoke `dotnet run --project developer-cli -- <command>` directly. Never run `dotnet`, `npm`, or `npx` directly - the pre-tool-use Bash hook blocks them.

README.md

@@ -38,6 +38,16 @@ Follow our [up-to-date roadmap](https://github.com/orgs/PlatformPlatform/project
 
 Show your support for our project - give us a star on GitHub! It truly means a lot! ⭐
 
+### Back office
+
+Operate the platform: manage account signups, users, and logins, and monitor revenue, MRR, churn, invoices, and Stripe drift.
+
+<img src="https://platformplatformgithub.blob.core.windows.net/BackOffice.gif" alt="PlatformPlatform Back Office" title="PlatformPlatform Back Office" />
+
+### Product demo
+
+End-user flows: tenant signup, account settings, Google login, welcome flow, accessibility and localization, and Stripe-powered subscription signup and management.
+
 <img src="https://platformplatformgithub.blob.core.windows.net/$root/PlatformPlatformDemo.gif" alt="PlatformPlatform Demo" title="PlatformPlatform Demo" />
 
 # Getting Started

application/AppGateway.Tests/ApiAggregationServiceTests.cs

@@ -0,0 +1,173 @@
+using System.Net;
+using System.Text;
+using AppGateway.ApiAggregation;
+using FluentAssertions;
+using Microsoft.Extensions.Logging.Abstractions;
+using Microsoft.Extensions.Primitives;
+using SharedKernel.Configuration;
+using Xunit;
+using Yarp.ReverseProxy.Configuration;
+
+namespace AppGateway.Tests;
+
+public sealed class ApiAggregationServiceTests
+{
+    private const string AccountOpenApiJson = """
+                                              {
+                                                "openapi": "3.0.0",
+                                                "info": { "title": "PlatformPlatform Account API", "version": "v1" },
+                                                "paths": {
+                                                  "/api/account/users": { "get": { "responses": { "200": { "description": "OK" } } } },
+                                                  "/internal-api/account/probe": { "get": { "responses": { "200": { "description": "OK" } } } }
+                                                }
+                                              }
+                                              """;
+
+    private const string MainOpenApiJson = """
+                                           {
+                                             "openapi": "3.0.0",
+                                             "info": { "title": "PlatformPlatform Main API", "version": "v1" },
+                                             "paths": {
+                                               "/api/main/health": { "get": { "responses": { "200": { "description": "OK" } } } }
+                                             }
+                                           }
+                                           """;
+
+    // Simulates a future endpoint that accidentally leaks into the account document with a
+    // /api/back-office prefix; the aggregator's belt-and-braces filter must drop it.
+    private const string AccountOpenApiJsonWithLeakedBackOfficePath = """
+                                                                      {
+                                                                        "openapi": "3.0.0",
+                                                                        "info": { "title": "PlatformPlatform Account API", "version": "v1" },
+                                                                        "paths": {
+                                                                          "/api/account/users": { "get": { "responses": { "200": { "description": "OK" } } } },
+                                                                          "/api/back-office/leaked": { "get": { "responses": { "200": { "description": "OK" } } } }
+                                                                        }
+                                                                      }
+                                                                      """;
+
+    [Fact]
+    public async Task GetAggregatedOpenApiJson_ShouldIncludeAccountApiPaths()
+    {
+        // Arrange
+        var service = CreateService(AccountOpenApiJson, MainOpenApiJson);
+
+        // Act
+        var aggregated = await service.GetAggregatedOpenApiJson();
+
+        // Assert
+        aggregated.Should().Contain("\"/api/account/users\"");
+    }
+
+    [Fact]
+    public async Task GetAggregatedOpenApiJson_ShouldIncludeMainApiPaths()
+    {
+        // Arrange
+        var service = CreateService(AccountOpenApiJson, MainOpenApiJson);
+
+        // Act
+        var aggregated = await service.GetAggregatedOpenApiJson();
+
+        // Assert
+        aggregated.Should().Contain("\"/api/main/health\"");
+    }
+
+    [Fact]
+    public async Task GetAggregatedOpenApiJson_ShouldExcludeBackOfficePaths()
+    {
+        // Arrange
+        var service = CreateService(AccountOpenApiJsonWithLeakedBackOfficePath, MainOpenApiJson);
+
+        // Act
+        var aggregated = await service.GetAggregatedOpenApiJson();
+
+        // Assert
+        aggregated.Should().NotContain("/api/back-office/");
+        aggregated.Should().Contain("\"/api/account/users\"");
+    }
+
+    [Fact]
+    public async Task GetAggregatedOpenApiJson_ShouldExcludeInternalApiPaths()
+    {
+        // Arrange
+        var service = CreateService(AccountOpenApiJson, MainOpenApiJson);
+
+        // Act
+        var aggregated = await service.GetAggregatedOpenApiJson();
+
+        // Assert
+        aggregated.Should().NotContain("/internal-api/");
+    }
+
+    private static ApiAggregationService CreateService(string accountDocumentJson, string mainDocumentJson)
+    {
+        var handler = new StubHttpMessageHandler(request =>
+            {
+                var requestUrl = request.RequestUri!.ToString();
+                if (requestUrl.EndsWith("/openapi/account.json", StringComparison.OrdinalIgnoreCase))
+                {
+                    return BuildJsonResponse(accountDocumentJson);
+                }
+
+                if (requestUrl.EndsWith("/openapi/v1.json", StringComparison.OrdinalIgnoreCase))
+                {
+                    return BuildJsonResponse(mainDocumentJson);
+                }
+
+                return new HttpResponseMessage(HttpStatusCode.NotFound) { ReasonPhrase = $"Unstubbed URL: {requestUrl}" };
+            }
+        );
+
+        var clusters = new ClusterConfig[]
+        {
+            new() { ClusterId = "account-api", Destinations = new Dictionary<string, DestinationConfig> { ["destination"] = new() { Address = "https://placeholder.invalid" } } },
+            new() { ClusterId = "main-api", Destinations = new Dictionary<string, DestinationConfig> { ["destination"] = new() { Address = "https://placeholder.invalid" } } }
+        };
+
+        var proxyConfigProvider = new StubProxyConfigProvider(new StubProxyConfig(clusters));
+        var httpClientFactory = new StubHttpClientFactory(handler);
+        var ports = new PortAllocation(9000);
+        return new ApiAggregationService(NullLogger<ApiAggregationService>.Instance, proxyConfigProvider, httpClientFactory, ports);
+    }
+
+    private static HttpResponseMessage BuildJsonResponse(string json)
+    {
+        return new HttpResponseMessage(HttpStatusCode.OK)
+        {
+            Content = new StringContent(json, Encoding.UTF8, "application/json")
+        };
+    }
+
+    private sealed class StubHttpMessageHandler(Func<HttpRequestMessage, HttpResponseMessage> responder) : HttpMessageHandler
+    {
+        protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
+        {
+            return Task.FromResult(responder(request));
+        }
+    }
+
+    private sealed class StubHttpClientFactory(HttpMessageHandler handler) : IHttpClientFactory
+    {
+        public HttpClient CreateClient(string name)
+        {
+            return new HttpClient(handler, false);
+        }
+    }
+
+    private sealed class StubProxyConfigProvider(IProxyConfig config) : IProxyConfigProvider
+    {
+        public IProxyConfig GetConfig()
+        {
+            return config;
+        }
+    }
+
+    private sealed class StubProxyConfig(IReadOnlyList<ClusterConfig> clusters) : IProxyConfig
+    {
+        public IReadOnlyList<RouteConfig> Routes => Array.Empty<RouteConfig>();
+
+        public IReadOnlyList<ClusterConfig> Clusters => clusters;
+
+        public IChangeToken ChangeToken => new CancellationChangeToken(CancellationToken.None);
+    }
+}

application/AppGateway/ApiAggregation/ApiAggregationService.cs

@@ -5,7 +5,7 @@
 
 namespace AppGateway.ApiAggregation;
 
-public class ApiAggregationService(
+public sealed class ApiAggregationService(
     ILogger<ApiAggregationService> logger,
     IProxyConfigProvider proxyConfigProvider,
     IHttpClientFactory httpClientFactory,
@@ -36,16 +36,27 @@
         var proxyConfiguration = proxyConfigProvider.GetConfig();
 
         // account-api emits two OpenAPI documents (account, back-office) post-consolidation; the
-        // user-facing aggregator only surfaces 'account' since back-office endpoints don't appear
-        // in the user-facing contract.
+        // user-facing aggregator only surfaces 'account' since back-office endpoints are admin-only
+        // and don't appear in the public contract.
         var accountCluster = proxyConfiguration.Clusters.FirstOrDefault(c => c.ClusterId == "account-api");
         if (accountCluster is not null)
         {
             var accountDocument = await FetchOpenApiDocument(accountCluster, "account");
             CombineOpenApiDocuments(aggregatedOpenApiDocument, accountDocument);
         }
 
+        // main-api emits a single OpenAPI document at /openapi/v1.json (ApiDocumentLayout.Single).
+        // It must be aggregated so future routes added to main appear in the unified public contract
+        // without further wiring here.
+        var mainCluster = proxyConfiguration.Clusters.FirstOrDefault(c => c.ClusterId == "main-api");
+        if (mainCluster is not null)
+        {
+            var mainDocument = await FetchOpenApiDocument(mainCluster, "v1");
+            CombineOpenApiDocuments(aggregatedOpenApiDocument, mainDocument);
+        }
+
         FilterInternalEndpoints(aggregatedOpenApiDocument);
+        FilterBackOfficeEndpoints(aggregatedOpenApiDocument);
 
         return aggregatedOpenApiDocument;
     }
@@ -73,7 +84,7 @@
     private void CombineOpenApiDocuments(OpenApiDocument aggregatedOpenApiDocument, OpenApiDocument openApiDocument)
     {
         // Merge paths
         foreach (var path in openApiDocument.Paths)
         {
             if (!aggregatedOpenApiDocument.Paths.ContainsKey(path.Key))
             {
@@ -116,4 +127,21 @@
             openApiDocument.Paths.Remove(path);
         }
     }
+
+    // Belt-and-braces guard: account-api's 'account' document already excludes back-office endpoints
+    // because they're grouped under a separate ApiExplorer document, but if a future endpoint
+    // accidentally leaks into the account group with a /api/back-office/ prefix we still drop it
+    // from the public contract.
+    private static void FilterBackOfficeEndpoints(OpenApiDocument openApiDocument)
+    {
+        var backOfficePaths = openApiDocument.Paths
+            .Where(p => p.Key.StartsWith("/api/back-office/"))
+            .Select(p => p.Key)
+            .ToArray();
+
+        foreach (var path in backOfficePaths)
+        {
+            openApiDocument.Paths.Remove(path);
+        }
+    }
 }

application/AppHost/Program.cs

@@ -82,6 +82,14 @@
     .WithEnvironment("KESTREL_PORT", ports.AccountWorkers.ToString())
     .WithReference(accountDatabase)
     .WithReference(azureStorage)
+    // The BillingDriftWorker resolves StripeClientFactory which reads these. Without them the worker
+    // process sees UnconfiguredStripeClient even when Stripe is configured at the API level, and every
+    // stale subscription logs a warn + fail line through ProcessPendingStripeEvents on every worker start.
+    .WithEnvironment("Stripe__SubscriptionEnabled", stripeFullyConfigured ? "true" : "false")
+    .WithEnvironment("Stripe__ApiKey", stripeApiKey)
+    .WithEnvironment("Stripe__WebhookSecret", stripeWebhookSecret)
+    .WithEnvironment("Stripe__PublishableKey", stripePublishableKey)
+    .WithEnvironment("Stripe__AllowMockProvider", "true")
     .WaitFor(accountDatabase);
 
 var accountApi = builder
@@ -114,6 +122,10 @@
     .WithEnvironment("Stripe__WebhookSecret", stripeWebhookSecret)
     .WithEnvironment("Stripe__PublishableKey", stripePublishableKey)
     .WithEnvironment("Stripe__AllowMockProvider", "true")
+    .WithEnvironment("PUBLIC_GOOGLE_OAUTH_ENABLED", googleOAuthConfigured ? "true" : "false")
+    // Force-on so newcomers see the back-office billing UI without Stripe configured. Set to "false" (or
+    // change back to `stripeFullyConfigured ? "true" : "false"`) to hide all billing/revenue/Stripe data.
+    .WithEnvironment("PUBLIC_SUBSCRIPTION_ENABLED", "true")
     .WaitFor(accountWorkers);
 
 var mainDatabase = postgres

application/account/Api/Endpoints/BackOfficeEndpoints.cs → application/account/Api/BackOffice/BackOfficeEndpoints.cs

@@ -5,7 +5,7 @@
 using SharedKernel.Endpoints;
 using SharedKernel.OpenApi;
 
-namespace Account.Api.Endpoints;
+namespace Account.Api.BackOffice;
 
 public sealed class BackOfficeEndpoints : IEndpoints
 {
@@ -14,7 +14,7 @@ public sealed class BackOfficeEndpoints : IEndpoints
     public void MapEndpoints(IEndpointRouteBuilder routes)
     {
         // BackOffice:Host is required (validated at startup via ValidateOnStart in
-        // ApiDependencyConfiguration.AddBackOfficeHostOptions). PP-1149 must keep that validation in place
+        // ApiDependencyConfiguration.AddBackOfficeHostOptions). The startup validation must stay in place
         // so a missing/blank value fails loudly rather than silently 404-ing back-office endpoints.
         var backOfficeHost = routes.ServiceProvider.GetRequiredService<IOptions<BackOfficeHostOptions>>().Value.Host;
 

application/account/Api/BackOffice/BillingDriftEndpoints.cs

@@ -0,0 +1,37 @@
+using Account.Features.BackOffice.BillingDrift.Queries;
+using Microsoft.Extensions.Options;
+using SharedKernel.ApiResults;
+using SharedKernel.Authentication.BackOfficeIdentity;
+using SharedKernel.Endpoints;
+using SharedKernel.OpenApi;
+
+namespace Account.Api.BackOffice;
+
+public sealed class BillingDriftEndpoints : IEndpoints
+{
+    private const string RoutesPrefix = "/api/back-office/billing-drift";
+
+    public void MapEndpoints(IEndpointRouteBuilder routes)
+    {
+        var backOfficeHost = routes.ServiceProvider.GetRequiredService<IOptions<BackOfficeHostOptions>>().Value.Host;
+
+        var group = routes.MapGroup(RoutesPrefix)
+            .WithTags("BackOfficeBillingDrift")
+            .WithGroupName(OpenApiDocumentNames.BackOffice)
+            .RequireHost(backOfficeHost)
+            .RequireAuthorization(BackOfficeIdentityDefaults.PolicyName)
+            .ProducesValidationProblem();
+
+        group.MapGet("/summary", async Task<ApiResult<BillingDriftSummaryResponse>> ([AsParameters] GetBillingDriftSummaryQuery query, IMediator mediator)
+            => await mediator.Send(query)
+        ).Produces<BillingDriftSummaryResponse>();
+
+        group.MapGet("/unsynced-summary", async Task<ApiResult<UnsyncedSubscriptionsSummaryResponse>> ([AsParameters] GetUnsyncedSubscriptionsSummaryQuery query, IMediator mediator)
+            => await mediator.Send(query)
+        ).Produces<UnsyncedSubscriptionsSummaryResponse>();
+
+        group.MapGet("/mrr-consistency-summary", async Task<ApiResult<DashboardMrrConsistencySummaryResponse>> ([AsParameters] GetDashboardMrrConsistencySummaryQuery query, IMediator mediator)
+            => await mediator.Send(query)
+        ).Produces<DashboardMrrConsistencySummaryResponse>();
+    }
+}

application/account/Api/BackOffice/BillingEventsEndpoints.cs

@@ -0,0 +1,29 @@
+using Account.Features.BackOffice.BillingEvents.Queries;
+using Microsoft.Extensions.Options;
+using SharedKernel.ApiResults;
+using SharedKernel.Authentication.BackOfficeIdentity;
+using SharedKernel.Endpoints;
+using SharedKernel.OpenApi;
+
+namespace Account.Api.BackOffice;
+
+public sealed class BillingEventsEndpoints : IEndpoints
+{
+    private const string RoutesPrefix = "/api/back-office/billing-events";
+
+    public void MapEndpoints(IEndpointRouteBuilder routes)
+    {
+        var backOfficeHost = routes.ServiceProvider.GetRequiredService<IOptions<BackOfficeHostOptions>>().Value.Host;
+
+        var group = routes.MapGroup(RoutesPrefix)
+            .WithTags("BackOfficeBillingEvents")
+            .WithGroupName(OpenApiDocumentNames.BackOffice)
+            .RequireHost(backOfficeHost)
+            .RequireAuthorization(BackOfficeIdentityDefaults.PolicyName)
+            .ProducesValidationProblem();
+
+        group.MapGet("/", async Task<ApiResult<BillingEventsResponse>> ([AsParameters] GetBackOfficeBillingEventsQuery query, IMediator mediator)
+            => await mediator.Send(query)
+        ).Produces<BillingEventsResponse>();
+    }
+}