Repository navigation
Conversation
…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.
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 memberesmeralda-ui) that imports theesmeraldapackage. The platform logic stays in Python and exists in one place.How
esmeralda.catalog.resolve()+show()(the same code asesmeralda catalog show). The output is checked againstcatalog/.resolved/<env>.jsonand returns 503 if the two don't match. There is no synthetic fallback.SELECTs onvw_monthly_agent_chargeback,vw_security_audit_trail,vw_usage_billableandusage_events. Every value is a typed query parameter and every job setsmaximum_bytes_billed. The project and dataset come from configuration. Trace IDs must match^[0-9a-f]{32}$before any query runs.esmeralda ui --localuses a fixed dev identity, labels it in the UI, binds to loopback only and refuses to start on Cloud Run.frame-ancestors 'none'), plusnosniff,no-referrerandX-Frame-Options. Only GET/HEAD are accepted, request bodies are refused, and error messages are generic. There is no docs UI.source, and the web shows a "Demo data" badge on every card. With no data source configured, the views show an error state.esmeralda.usageand never forwards client credentials.openapi.jsonis generated from FastAPI, andweb/src/api/schema.tsis generated from it withopenapi-typescript. Each side's tests fail on drift.esmeralda ui --local [--demo | --bigquery],make ui,make test-ui,make test-ui-api(also part ofmake test).Dockerfile.dockerignore.npm ci,tsc --noEmit, Vitest andvite build. Nothing is skipped. Dependabot is added for npm and the image's base images.Not in this PR (follow-up)
layer-5-workloads/frontends/esmeralda-ui: internal ingress through thedirectentry point plus IAP, a least-privilege SA,iap_accessorslimited to existing groups, and the live dev test.esmeralda buildand to promotion/verification.Tests
test_cli_ui.py.tscand the production build pass.make test,make test-guards,make docs-build(strict) pass.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.lockadds only the new workspace member;package-lock.jsonresolves only to the public npm registry.