BFF Admin Overview Owner-Source Proof

Status: bounded SVC-002 proof accepted, not BFF or rollout completion.

This page records the owner-service source evidence, BFF aggregation test, and gateway route proof for the non-default admin overview rehearsal. It does not approve public dashboard promotion.

Owner-Service Source Evidence

admin-service is the named owner of the admin operations source contract:

Owner endpoint	Owner implementation	BFF field	Boundary
GET /v1/admin/operations/source-map	services/admin-service/internal/http/server.go -> AdminService.OperationsSourceMap	ownerSources	Read-only map of owner service/API, source type, and route status.
GET /v1/admin/operations/source-snapshots	services/admin-service/internal/http/server.go -> AdminService.OperationsSourceSnapshots	ownerSourceSnapshots	Read-only probe status; not dashboard totals.

The owner map test at services/admin-service/internal/usecase/admin_owner_source_test.go requires at least ten unique entries, explicit owner service/API fields, and routeStatus=legacy until a separate route proof exists. The map includes IAM-owned identity counts and profile-owned display/profile counts without moving either domain into BFF.

The BFF adapter is services/bff-service/internal/upstream/admin_source_map.go. It calls only the named admin-service endpoints, forwards actor/role/organization headers, and marks the optional metadata degraded when the owner endpoint fails. BFF does not read an owner database or synthesize canonical business metrics.

BFF Aggregation Test

services/bff-service/internal/http/owner_source_integration_test.go starts a real httptest owner endpoint and runs the BFF HTTP route through GET /v1/bff/admin/overview. The test verifies:

• actor, role, and organization headers reach admin-service;
• both owner source endpoints are called exactly once;
• the owner map and snapshots are decoded from the common success envelope;
• owner service/API metadata appears in the BFF response;
• the existing failure tests keep owner metadata degraded without failing the whole screen shell.

The BFF response remains screen-shaped aggregation. It does not become an admin-service replacement or a source of truth.

Gateway Route Proof

The route candidate is intentionally non-default:

• deploy/gateway/routes.bff-admin-overview-native-example.json
• deploy/gateway/routes.bff-admin-overview-native-localhost-example.json

Both tables route only exact GET /api/admin/overview to /v1/bff/admin/overview, require gateway authentication and ADMIN, and keep broad /api/admin and /api fallback routes on legacy_proxy.

deploy/gateway/routes.json remains the default table and does not activate the BFF route. The gateway test TestGatewayBFFAdminOverviewNativeRouteOnlyCapturesAdminOverview proves the native route rewrite and that non-matching/broad requests continue to the legacy backend. make test-bff-routes validates the default and both native route tables.

Admin-Web Opt-In Candidate (2026-07-14)

apps/admin-web now has a bounded consumer for the existing non-default BFF route. An authenticated ADMIN can opt in with ?adminOverviewGateway=native on /admin or /admin/dashboard. Only then, the dashboard calls the runtime API base at exact GET /api/admin/overview, with the existing Gateway bearer session and credentials: include.

The browser client reads only data.sources; it does not reinterpret the BFF screen shell as canonical dashboard totals. The existing overview fixture remains displayed and the candidate adds an accessible source-status line. A missing/non-ADMIN session, 8-second timeout, HTTP error, malformed success envelope, or invalid source entry leaves the fixture intact and reports the fallback state instead of issuing a second request or synthesizing data.

Focused frontend verification passed:

pnpm --filter @hoctapaz/admin-web test -- src/App.test.tsx

The 53-test run covers no request without the query opt-in, no request without an ADMIN Gateway session, the exact Gateway URL/authentication request and degraded source rendering on a valid response, and fixture fallback for a rejected request. This is a mocked browser-client contract check; it is not an authenticated live Gateway/browser rehearsal and does not promote the default route table.

Isolated Owner/BFF Runtime (2026-07-14)

BFF_ADMIN_OVERVIEW_ISOLATED_CONFIRM=bff-admin-overview-isolated make test-bff-admin-overview-isolated starts a disposable Compose project that exposes only bff-service, admin-service, and ai-classifier-service on temporary loopback ports. Their transitive service-owned dependencies may boot inside the disposable project. The base Compose ports are reset in deploy/docker-compose.bff-admin-overview-proof.yml; the runner creates its own project name, waits for readiness, and removes containers, networks, and volumes in its exit trap.

Before Docker is started, run BFF_ADMIN_OVERVIEW_ISOLATED_SELF_TEST=1 make test-bff-admin-overview-isolated to verify the three dynamic public ports, internal dependency closure, and the two owner-source target URLs. The self-test rejects any accidental host port for storage, database, gateway, identity, content, or monetization services.

The runtime smoke calls direct owner/BFF routes with a synthetic ADMIN actor header, verifies the missing-role rejection, BFF health of admin-service, owner source-map ownership of ai.providers, and an HTTP 200 provider-status snapshot made by admin-service to the real ai-classifier-service endpoint. It records response latency, with a configurable local ceiling of 2000 ms, in output/qa/bff-admin-overview-runtime-*/summary.json.

This direct owner/BFF portion does not itself authenticate through api-gateway; headers are injected only for that service proof. The separate browser candidate below proves the authenticated Gateway boundary. Neither proof promotes the public/default route table.

Authenticated Admin Browser Candidate (2026-07-15)

BFF_ADMIN_OVERVIEW_ISOLATED_CONFIRM=bff-admin-overview-isolated make test-bff-admin-overview-browser extends the same disposable Compose project with temporary local processes only: a locally built api-gateway in the frontend-approved loopback range, a short-lived HS256 ADMIN proof token, and Vite Admin. It generates a temporary candidate table that points only exact GET /api/admin/overview at the disposable BFF port; the committed deploy/gateway/routes.json is read to assert that it remains inactive.

Playwright opens /admin?adminOverviewGateway=native, injects the Gateway session before navigation, and requires exactly one browser-observed request. It verifies the bearer header, 200 response, bff-admin-overview and native_read Gateway headers, the existing fixture dashboard, and the rendered admin-service: ổn định source-status line. The successful local artifact is output/qa/bff-admin-overview-browser-2026-07-14T22-52-43-276Z/summary.json: the browser-to-Gateway request took 16 ms and the owner source was ok.

The smoke catches a duplicate opt-in request. Its first implementation exposed React StrictMode starting the same effect twice, so the Admin overview now reuses an in-flight request per runtime API base. This retains fixture fallback while avoiding a second Gateway/BFF owner fan-out.

Rollback Notes

Rollback is returning the gateway to the default table:

GATEWAY_ROUTE_TABLE=deploy/gateway/routes.json make run-gateway
make test-bff-routes
BFF_ADMIN_OVERVIEW_ISOLATED_CONFIRM=bff-admin-overview-isolated make test-bff-admin-overview-isolated
BFF_ADMIN_OVERVIEW_ISOLATED_CONFIRM=bff-admin-overview-isolated make test-bff-admin-overview-browser

The route coverage guard requires the exact BFF entry to be absent or inactive in the default table and preserves broad admin/fallback legacy routes. No default route table was modified in this slice.

Promotion Boundary

• owner-service source evidence: complete for this bounded read adapter;
• gateway route proof: complete for static/native rehearsal;
• BFF aggregation test: complete, including real HTTP owner adapter;
• authenticated browser/runtime candidate proof: complete for the isolated non-default route; rollback after candidate review remains required before any public /api/admin/overview promotion;
• broad admin dashboard parity and remaining health-only snapshots: still open.

Verification

GOTOOLCHAIN=go1.25.11 go test ./services/bff-service/...
make test-bff-routes
GOTOOLCHAIN=go1.25.11 go test ./services/api-gateway/internal/gateway -run BFF -count=1
BFF_ADMIN_OVERVIEW_ISOLATED_CONFIRM=bff-admin-overview-isolated make test-bff-admin-overview-browser
ruby -e 'require "yaml"; ARGV.each { |path| YAML.load_file(path) }' services/bff-service/api/openapi.yaml contracts/openapi/services/bff-service.yaml
diff -u services/bff-service/api/openapi.yaml contracts/openapi/services/bff-service.yaml
docker compose -f deploy/docker-compose.yml config --quiet
GOTOOLCHAIN=go1.25.11 go test ./services/admin-service/internal/usecase -run TestOperationsSourceMapRequiresExplicitOwnerApis -count=1

All commands passed on 2026-07-10.