Web UI (R3XA_API)

This section documents the optional web UI included in the repository.

Architecture choices

The web UI is split into two layers:

  • r3xa_api/webcore/: pure Python helpers used by the web API (validation reports, schema summary, SVG graph generation).

  • web/: FastAPI app + HTML/JS/CSS templates and static assets.

This keeps the core API (r3xa_api) as the single source of truth, while the web UI remains a thin consumer of that API.

Install & run

From the project root (using the .venv convention):

pip install -e ".[web,dev]"
python scripts/dev.py run-web --port 8002

Open: http://127.0.0.1:8002/

Note: SVG graph generation requires the Graphviz executable (dot) to be installed on your system. The schema viewer JS is vendored; no npm install is required for normal usage.

Graphviz requirement

The pip install -e ".[web]" command installs the Python wrapper, but not the Graphviz executable itself. For POST /api/graph and the SVG viewer/export to work, dot must be available on the system:

Quick check:

dot -V

What you can do

  • Editor (/edit)

    • Edit a JSON draft (header + settings + data_sources + data_sets).

    • Validate the JSON (inline report).

    • Save/load JSON to/from disk.

    • Draft state is stored locally (browser storage).

  • Registry editor (/registry)

    • Load, edit, validate, and save a single registry item JSON.

    • Optional kind override for strict item-level validation.

    • See dedicated page: Registry Web Editor.

  • Schema viewer (/schema)

    • Inspect the schema summary or the current draft.

    • Generate an SVG graph from the current draft.

    • Optional: hide node descriptions and keep titles only.

    • Export a fully inlined standalone HTML report (graph + JSON) shareable without server.

API endpoints

  • POST /api/validate → validation report

  • GET /api/schema → raw schema

  • GET /api/schema/summary → schema summary

  • POST /api/graph → SVG graph (Graphviz)