Skip to content

feat(ui): read-only Esmeralda console (React SPA + FastAPI BFF) - #237

Open
amenegola wants to merge 3 commits into
mainfrom
feat/esmeralda-ui
Open

amenegola wants to merge 3 commits into
mainfrom
feat/esmeralda-ui

Conversation

@amenegola

Copy link
Copy Markdown
Collaborator

Part of #171. Supersedes #223 and #226.

What

A read-only web console at apps/frontends/esmeralda-ui/ with three views (Service Catalog, FinOps & Audit, Traces):

  • web/: a React + TypeScript (strict) + Vite single-page app.
  • api/: a thin, read-only FastAPI backend-for-frontend (workspace member esmeralda-ui) that imports the esmeralda package. The platform logic stays in Python and exists in one place.

How

Area Approach
Catalog esmeralda.catalog.resolve() + show() (the same code as esmeralda catalog show). The output is checked against catalog/.resolved/<env>.json and returns 503 if the two don't match. There is no synthetic fallback.
Usage, audit, traces Fixed SELECTs on vw_monthly_agent_chargeback, vw_security_audit_trail, vw_usage_billable and usage_events. Every value is a typed query parameter and every job sets maximum_bytes_billed. The project and dataset come from configuration. Trace IDs must match ^[0-9a-f]{32}$ before any query runs.
Identity The IAP JWT is verified: ES256 signature against IAP's keys, issuer, configured audience and expiry. Anything else gets a generic 401, and there is no default identity. esmeralda ui --local uses a fixed dev identity, labels it in the UI, binds to loopback only and refuses to start on Cloud Run.
Hardening Strict CSP (no inline scripts or handlers, no external fonts or CDNs, frame-ancestors 'none'), plus nosniff, no-referrer and X-Frame-Options. Only GET/HEAD are accepted, request bodies are refused, and error messages are generic. There is no docs UI.
Honest data Demo data is served only with an explicit flag. Every response carries source, and the web shows a "Demo data" badge on every card. With no data source configured, the views show an error state.
Writes None. The BFF never emits esmeralda.usage and never forwards client credentials.
Contract openapi.json is generated from FastAPI, and web/src/api/schema.ts is generated from it with openapi-typescript. Each side's tests fail on drift.
CLI / Make esmeralda ui --local [--demo | --bigquery], make ui, make test-ui, make test-ui-api (also part of make test).
Image Multi-stage Dockerfile: a digest-pinned Node stage builds the web (lockfile, no install scripts), and a digest-pinned Python runtime runs as non-root with the catalog baked in. Built from the repo root through Dockerfile.dockerignore.
CI New Console workflow: BFF pytest, then npm ci, tsc --noEmit, Vitest and vite build. Nothing is skipped. Dependabot is added for npm and the image's base images.
Docs New page 2.7 Esmeralda Console, a CLI reference entry, and updates to llms.txt and the section index.

Not in this PR (follow-up)

  • The Terraform unit layer-5-workloads/frontends/esmeralda-ui: internal ingress through the direct entry point plus IAP, a least-privilege SA, iap_accessors limited to existing groups, and the live dev test.
  • Adding the image to esmeralda build and to promotion/verification.
  • Live invoke as a registered catalog caller.

Tests

  • BFF: 79 pytest tests (IAP JWT with throwaway keys, 401 paths, CSP and headers, method and body limits, parameterized queries against a fake BigQuery client, trace-ID injection attempts, catalog fail-closed, demo labelling, no usage emission, OpenAPI drift).
  • CLI: test_cli_ui.py.
  • Web: 24 Vitest + Testing Library tests (badges, error states, HTML rendered as text, trace-ID validation, source hygiene).
  • Strict tsc and the production build pass.
  • make test, make test-guards, make docs-build (strict) pass.
  • Tried locally with esmeralda ui --local --demo, and read-only against a dev BigQuery dataset with --bigquery. Nothing is deployed by this PR, so there is no dev deployment test yet (that comes with the Terraform unit).
  • uv.lock adds only the new workspace member; package-lock.json resolves only to the public npm registry.

…he esmeralda package)

Adds apps/frontends/esmeralda-ui: a React + TypeScript (strict) + Vite single-page app served by a
thin, read-only Python backend-for-frontend that imports the esmeralda package.

- BFF (workspace member esmeralda-ui): /api/me, /api/catalog[/{target}], /api/usage, /api/audit,
  /api/traces[/{trace_id}], /healthz. Catalog through esmeralda.catalog (resolve + show), checked
  against catalog/.resolved/<env>.json and failing closed on drift. Usage, audit and traces from the
  layer-4 BigQuery views with fixed SELECTs, typed query parameters and maximum_bytes_billed.
  Trace ids validated as 32 lowercase hex before any query. No writes, no usage emission.
- Identity: IAP JWT verified (ES256 signature, issuer, configured audience, expiry), generic 401
  otherwise, no default identity. Local mode (esmeralda ui --local) uses a labelled dev identity,
  binds to loopback and refuses to run on Cloud Run.
- Hardening: strict CSP (no inline scripts, no external origins, frame-ancestors 'none'),
  nosniff, referrer and frame headers, GET/HEAD only, request bodies refused, generic errors.
- Demo data only behind an explicit flag, labelled source=demo and badged in every view; with no
  data source the views show an error state.
- Contract: openapi.json generated from FastAPI, TypeScript types generated with
  openapi-typescript; both sides fail their tests on drift.
- esmeralda ui --local [--demo | --bigquery], make ui / test-ui / test-ui-api.
- Multi-stage Dockerfile (digest-pinned Node build stage and Python runtime, non-root).
- Console workflow: BFF pytest, npm ci, tsc --noEmit, Vitest, build. Dependabot for npm and the
  image base images.
- Docs: 2.7 Esmeralda Console. Deployment comes in a follow-up.
@amenegola
amenegola requested a review from duboc November 17, 2026 01:52

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant