Skip to content

Add web frontend#4

Draft
gaurav wants to merge 7 commits intobasic-implementation-in-uvfrom
add-nodenorm-frontend
Draft

Add web frontend#4
gaurav wants to merge 7 commits intobasic-implementation-in-uvfrom
add-nodenorm-frontend

Conversation

@gaurav
Copy link
Collaborator

@gaurav gaurav commented Feb 16, 2026

This PR adds a web interface to babel-explorer, exposing all four tools — NodeNorm, XRefs, IDs, and Test Concordance — through a browser UI, a JSON REST API, and CSV downloads. It also includes the full CLI implementation, core query engine, and comprehensive test suite that the web frontend builds on.

Why FastAPI?

We considered several options for the web framework:

  • Streamlit — Easy to prototype with, but its re-run-the-whole-script model doesn't map well to babel-explorer's architecture (shared BabelDownloader/BabelXRefs instances with LRU caches, lazy multi-GB file downloads). It also wouldn't give us a clean REST API for programmatic access.
  • Flask — A solid choice, but we'd need to bolt on separate API documentation (Swagger/OpenAPI) and pick additional libraries for request validation.
  • Django — Too heavyweight for a tool with no database models or user auth.
  • FastAPI was the best fit because:
    • It auto-generates Swagger docs at /docs, giving us a REST API with interactive documentation for free.
    • It runs synchronous route handlers in a threadpool automatically, which is exactly what we need — the core code uses synchronous requests and DuckDB, and some queries trigger multi-GB Parquet downloads that would block an async event loop.
    • Jinja2 templating is a first-class integration, so we get server-rendered HTML without a JS build system.
    • Combined with htmx, forms submit via AJAX and swap in HTML fragments without writing any frontend JavaScript framework code.

What's included

  • Web app (src/babel_explorer/web/) — FastAPI app factory, routes, Jinja2 templates with Bootstrap 5 + htmx
  • Four tool pages with forms that return results as HTML tables via htmx
  • JSON REST API (/api/nodenorm, /api/xrefs, /api/ids, /api/test-concord) with query parameter interface
  • CSV downloads for all tools (/api/*/csv)
  • NodeNorm instance dropdown populated from NodeNorm.URLs with a "Custom URL..." option
  • CLI command babel-explorer web with --host, --port, --reload options
  • Navbar with links to all tools, Swagger docs, and GitHub repo
  • 25 unit tests (tests/test_web.py) covering HTML pages, htmx partials, JSON API, CSV endpoints, and helper functions — all mocked, no network needed
  • Core modules: BabelDownloader, BabelXRefs, NodeNorm, Click CLI, and 80+ tests across test_downloader.py, test_babel_xrefs.py, test_nodenorm.py

How to test

uv sync --group dev
uv run babel-explorer web          # http://127.0.0.1:8000
uv run pytest tests/test_web.py -v # 25 tests, ~0.4s

gaurav and others added 7 commits February 16, 2026 17:22
Adds a web UI (FastAPI + Jinja2 + htmx + Bootstrap 5) exposing NodeNorm,
XRefs, IDs, and Test Concordance via browser forms, a JSON REST API, and
CSV downloads. Launched with `babel-explorer web`.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The NodeNorm and Test Concordance pages now show a select dropdown
populated from NodeNorm.URLs (defaulting to NodeNorm Dev), with a
"Custom URL..." option that reveals a free-text input.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
CLI args are forwarded via environment variables so the reloaded
subprocess picks up the same config.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add web route table and NodeNorm dropdown details to CLAUDE.md. Add web
frontend section to README.md covering startup, REST API examples, and
CSV download endpoints.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
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

Comments