# 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):

```bash
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:

- Linux: `sudo apt-get install graphviz`
- macOS: `brew install graphviz`
- Windows: install from <https://graphviz.org/download/> and ensure `dot` is in `PATH`

Quick check:

```bash
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](registry_web.md).
- **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.

## Links

- Source repo: <https://github.com/jeffwitz/R3XA_API>
- Original upstream repository: <https://gitlab.com/photomecanics/r3xa>
- Documentation: <https://r3xa-api.readthedocs.io/en/latest/>

## API endpoints

- `POST /api/validate` → validation report
- `GET /api/schema` → raw schema
- `GET /api/schema/summary` → schema summary
- `POST /api/graph` → SVG graph (Graphviz)