Feat/web v2 scaffold

.env.example

@@ -0,0 +1,26 @@
+# OntoloViz server environment variables. Copy to `.env` and adjust.
+# All values are optional — defaults are dev-safe.
+
+# Bind address. Use 0.0.0.0 to accept connections from outside the container.
+ONTOLOVIZ_HOST=127.0.0.1
+
+# TCP port the FastAPI server listens on.
+ONTOLOVIZ_PORT=8000
+
+# Number of uvicorn worker processes. Rule of thumb: 2*CPU + 1.
+# Ignored when ONTOLOVIZ_RELOAD=1.
+ONTOLOVIZ_WORKERS=1
+
+# Hot-reload on source changes. Dev only — must be 0 in production.
+ONTOLOVIZ_RELOAD=0
+
+# Trust X-Forwarded-* headers. Enable when behind nginx/Caddy/an LB.
+ONTOLOVIZ_PROXY_HEADERS=0
+
+# Uvicorn log level: critical | error | warning | info | debug | trace
+ONTOLOVIZ_LOG_LEVEL=info
+
+# Comma-separated list of allowed CORS origins. In a same-origin deployment
+# (SPA + API served by this process) CORS is unused; set it only when the
+# frontend is hosted elsewhere.
+ONTOLOVIZ_CORS_ORIGINS=http://localhost:5173,http://127.0.0.1:5173

.gitignore

@@ -14,8 +14,8 @@ dist/
 downloads/
 eggs/
 .eggs/
-lib/
-lib64/
+/lib/
+/lib64/
 parts/
 sdist/
 var/
@@ -128,4 +128,11 @@ dmypy.json
 # Pyre type checker
 .pyre/
 
-# custom
+# custom
+.idea/
+
+# Web frontend build artifact bundled into the wheel
+src/ontoloviz_server/web_dist/
+
+# Playwright MCP session output (console logs, page snapshots, screenshots)
+.playwright-mcp/

Dockerfile

@@ -0,0 +1,52 @@
+# syntax=docker/dockerfile:1.7
+
+# --- Stage 1: build the web frontend ---------------------------------------
+FROM node:20-bookworm-slim AS web-builder
+
+WORKDIR /web
+RUN corepack enable
+
+COPY web/package.json web/pnpm-lock.yaml* ./
+RUN pnpm install --frozen-lockfile || pnpm install
+
+COPY web/ ./
+RUN pnpm build
+
+# --- Stage 2: assemble the Python wheel ------------------------------------
+FROM python:3.12-slim-bookworm AS wheel-builder
+
+WORKDIR /src
+RUN pip install --no-cache-dir build
+
+COPY pyproject.toml MANIFEST.in VERSION README.md LICENSE ./
+COPY src/ ./src/
+COPY --from=web-builder /web/dist/ ./src/ontoloviz_server/web_dist/
+
+RUN python -m build --wheel --outdir /wheels
+
+# --- Stage 3: lean runtime --------------------------------------------------
+FROM python:3.12-slim-bookworm AS runtime
+
+# Run as non-root.
+RUN useradd --create-home --uid 10001 ontoloviz
+WORKDIR /home/ontoloviz
+
+COPY --from=wheel-builder /wheels/*.whl /tmp/
+RUN pip install --no-cache-dir /tmp/*.whl && rm -rf /tmp/*.whl
+
+USER ontoloviz
+
+ENV ONTOLOVIZ_HOST=0.0.0.0 \
+    ONTOLOVIZ_PORT=8000 \
+    ONTOLOVIZ_WORKERS=4 \
+    ONTOLOVIZ_PROXY_HEADERS=1 \
+    ONTOLOVIZ_LOG_LEVEL=info \
+    PYTHONUNBUFFERED=1
+
+EXPOSE 8000
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+    CMD python -c "import urllib.request,sys; \
+sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:8000/api/health',timeout=3).status==200 else 1)"
+
+ENTRYPOINT ["ontoloviz-server"]

MANIFEST.in

@@ -0,0 +1,3 @@
+include VERSION
+include LICENSE
+include README.md

Makefile

@@ -0,0 +1,91 @@
+.PHONY: dev dev-web dev-server install test test-web test-server lint typecheck build build-web build-wheel clean parity-fixtures version set-version
+
+# --- Top-level dev loop ----------------------------------------------------
+
+dev:
+	@echo "Starting frontend (web/) and backend (ontoloviz-server) concurrently..."
+	@trap 'kill 0' INT TERM; \
+	$(MAKE) -s dev-server & \
+	$(MAKE) -s dev-web & \
+	wait
+
+dev-web:
+	cd web && pnpm dev
+
+# Backend runs out of the unified repo-root package. Editable installs do NOT
+# auto-rebuild the JS bundle — Vite's dev server is the source of truth for
+# the frontend in development; the SPA mount in main.py stays dormant when
+# src/ontoloviz_server/web_dist/ is empty.
+dev-server:
+	uv run ontoloviz-server --dev
+
+# --- Install ---------------------------------------------------------------
+
+install:
+	cd web && pnpm install
+	uv sync --extra dev
+
+# --- Tests -----------------------------------------------------------------
+
+test: test-web test-server
+
+test-web:
+	cd web && pnpm test
+
+test-server:
+	uv run pytest -q
+
+# --- Quality ---------------------------------------------------------------
+
+lint:
+	cd web && pnpm lint
+	uv run ruff check .
+
+typecheck:
+	cd web && pnpm typecheck
+
+# --- Build -----------------------------------------------------------------
+
+# Full release build: compile the web frontend, embed it into the Python
+# package, and produce wheel + sdist under ./dist/.
+build: build-web build-wheel
+
+build-web:
+	cd web && pnpm build
+	rm -rf src/ontoloviz_server/web_dist
+	mkdir -p src/ontoloviz_server/web_dist
+	cp -r web/dist/. src/ontoloviz_server/web_dist/
+
+build-wheel:
+	uv build
+
+# --- Parity ----------------------------------------------------------------
+
+# Regenerate JSON fixtures under web/tests/fixtures/parity/ from the
+# Python reference (src/ontoloviz/core.py + tests/parity logic). Run after
+# changing the propagation semantics in either language.
+parity-fixtures:
+	uv run python tests/parity/generate_fixtures.py
+
+# --- Version ---------------------------------------------------------------
+
+# Print the canonical version (root VERSION file is the source of truth).
+# Both the wheel and web/package.json read it (statically or dynamically);
+# pyproject.toml picks it up via [tool.setuptools.dynamic].
+version:
+	@cat VERSION
+
+# Usage: make set-version VERSION=3.0.1
+set-version:
+	@if [ -z "$(VERSION)" ]; then echo "Usage: make set-version VERSION=X.Y.Z"; exit 1; fi
+	@echo "$(VERSION)" > VERSION
+	@node -e "const f='web/package.json';const j=require('fs').readFileSync(f,'utf8');const o=JSON.parse(j);o.version='$(VERSION)';require('fs').writeFileSync(f,JSON.stringify(o,null,2)+'\n')"
+	@echo "Version set to $(VERSION) (VERSION + web/package.json). pyproject.toml picks it up dynamically."
+
+# --- Cleanup ---------------------------------------------------------------
+
+clean:
+	rm -rf web/dist web/node_modules/.vite
+	rm -rf src/ontoloviz_server/web_dist
+	rm -rf dist build src/ontoloviz.egg-info
+	rm -rf .pytest_cache .ruff_cache .mypy_cache

README.md

@@ -23,23 +23,72 @@ Quickstart
 **Install OntoloViz**
 - Using pip:
   ```bash
-  pip install ontoloviz        # Classic UI
-  pip install ontoloviz[web]   # With experimental web interface
+  pip install ontoloviz        # Classic desktop UI (Tkinter)
   ```
 - Using uv:
   ```bash
   git clone https://github.com/Delta4AI/OntoloViz.git
   cd OntoloViz
-  uv sync                      # Classic UI
-  uv sync --extra web          # With experimental web interface
+  uv sync                      # Classic desktop UI
   ```
 
 **Run OntoloViz**
 ```bash
 ontoloviz       # Launch classic UI
-ontoloviz-web   # Launch web interface
 ```
 
+> **Linux note (desktop GUI only):** uv's prebuilt CPython ships a Tk build
+> that crashes the file dialog on some distros (e.g. Fedora) with
+> `[xcb] Aborting, sorry about that.` Use the distro's Python for the GUI:
+> ```bash
+> uv sync --python /usr/bin/python3
+> uv run --python /usr/bin/python3 ontoloviz
+> ```
+> Building wheels (`uv build`) and running the web app are unaffected and
+> work with either Python.
+
+**Web app**
+
+A browser-based version lives in `web/` (Vite + React + TS + D3 + Canvas)
+backed by a FastAPI server packaged alongside the GUI in `src/ontoloviz_server/`.
+
+Development (Vite + reloading FastAPI):
+```bash
+make install   # one-time: installs frontend and backend deps
+make dev       # runs Vite on :5173 and FastAPI on :8000
+```
+
+End-user install (bundled SPA served by the FastAPI process):
+```bash
+pip install ontoloviz
+ontoloviz-server   # serves the web UI at http://127.0.0.1:8000
+ontoloviz          # launches the legacy desktop GUI
+```
+
+Production launch:
+```bash
+ontoloviz-server --host 0.0.0.0 --port 8000 --workers 4 --proxy-headers
+# or via env vars — see .env.example
+```
+All flags have `ONTOLOVIZ_*` env-var fallbacks. Behind nginx/Caddy on the
+public edge, `--proxy-headers` makes FastAPI trust forwarded client IPs.
+
+Container:
+```bash
+docker build -t ontoloviz .
+docker run --rm -p 8000:8000 ontoloviz
+```
+The image bundles the web build, exposes :8000, runs as a non-root user,
+and ships a `/api/health` healthcheck.
+
+Another application can push a fully-built ontology to the server and hand the
+user a link that renders it live (`POST /api/ontology` → open `?session=<id>`).
+See [docs/ontology-handoff.md](docs/ontology-handoff.md).
+
+Docs: [web/README.md](web/README.md) (frontend) ·
+[docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) (dev setup + commands) ·
+[docs/RUNBOOK.md](docs/RUNBOOK.md) (deploy, env vars, API surface, reverse proxy).
+
 
 
 **Pre-built Windows Binaries**  
@@ -190,15 +239,13 @@ Templates and Examples
 
 | Filename                                                                                                                                                     | Description                                                                                                                                                                                                                                                       |
 |--------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| [atc_example_covid_drugs_experimental.tsv](https://raw.githubusercontent.com/Delta4AI/OntoloViz/master/templates/atc_example_covid_drugs_experimental.tsv)   | ATC-based example with data from the [DrugBank](https://go.drugbank.com) indicating experimental drugs related to COVID-19.                                                                                                                                       |
-| [atc_example_covid_drugs_trial_summary.tsv](https://raw.githubusercontent.com/Delta4AI/OntoloViz/master/templates/atc_example_covid_drugs_trial_summary.tsv) | ATC-based example with data from [publicly available clinical trial data](https://clinicaltrials.gov/) indicating drugs tested in clinical studies, one count represents usage in one study.                                                                      |
-| [atc_template.tsv](https://raw.githubusercontent.com/Delta4AI/OntoloViz/master/templates/atc_template.tsv)                                         | ATC-based empty template of the [ATC](https://www.who.int/tools/atc-ddd-toolkit/atc-classification) tree based on the manually curated chemical database of bioactive molecules [ChEMBL v29](https://chembl.gitbook.io/chembl-interface-documentation/downloads). |
-| [custom_template_parent_based.tsv](https://raw.githubusercontent.com/Delta4AI/OntoloViz/master/templates/custom_template_parent_based.tsv)                   | Template for creating your own ontology based on any child and parent terms.                                                                                                                                                                                      |
-| [custom_template_separator_based.tsv](https://raw.githubusercontent.com/Delta4AI/OntoloViz/master/templates/custom_template_separator_based.tsv)             | Template to create your own ontology based on a separator-based tree structure - for this template the underscore character `_` has been used.                                                                                                                    |
-| [mesh_example_pubmed_mapped.tsv](https://raw.githubusercontent.com/Delta4AI/OntoloViz/master/templates/mesh_example_pubmed_mapped.tsv)                       | MeSH-based example with data from the publicly available [PubMed](https://pubmed.ncbi.nlm.nih.gov/) database of publications (title + abstract), where disease-related MeSH terms were extracted and mapped to the MeSH-tree.                                     |
-| [mesh_template.tsv](https://raw.githubusercontent.com/Delta4AI/OntoloViz/master/templates/mesh_template.tsv)                                                 | MeSH-based empty template of the [MeSH](https://meshb.nlm.nih.gov/treeView) tree `C` and `F03`. Terms are unique and mapped to all related parent nodes.                                                                                                          |
-| [atc_example.html](https://raw.githubusercontent.com/Delta4AI/OntoloViz/master/templates/atc_example.html)                                                   | ATC-based sample plot generated with the provided `covid_drugs_trial_summary.tsv` file.                                                                                                                                                                           |
-| [mesh_example.html](https://raw.githubusercontent.com/Delta4AI/OntoloViz/master/templates/mesh_example.html)                                                 | MeSH-based sample plot generated with the provided `covid_drugs_trial_summary.tsv` file.                                                                                                                                                                          |
+| [atc_template.tsv](https://raw.githubusercontent.com/Delta4AI/OntoloViz/master/web/public/templates/atc_template.tsv)                                                                 | Empty [ATC](https://www.who.int/tools/atc-ddd-toolkit/atc-classification) drug-hierarchy template, prefilled from the curated chemical database [ChEMBL v29](https://chembl.gitbook.io/chembl-interface-documentation/downloads). |
+| [mesh_template.tsv](https://raw.githubusercontent.com/Delta4AI/OntoloViz/master/web/public/templates/mesh_template.tsv)                                                               | Empty [MeSH](https://meshb.nlm.nih.gov/treeView) `C` and `F03` subject-hierarchy template; terms are unique and mapped to all related parent nodes.                                                                              |
+| [atc_example_covid_drugs_experimental.tsv](https://raw.githubusercontent.com/Delta4AI/OntoloViz/master/web/public/templates/atc_example_covid_drugs_experimental.tsv)                 | ATC-based example with [DrugBank](https://go.drugbank.com) data marking experimental drugs related to COVID-19.                                                                                                                  |
+| [atc_example_covid_drugs_trial_summary.tsv](https://raw.githubusercontent.com/Delta4AI/OntoloViz/master/web/public/templates/atc_example_covid_drugs_trial_summary.tsv)               | ATC-based example with [publicly available clinical trial data](https://clinicaltrials.gov/) — one count per study a drug was tested in.                                                                                         |
+| [mesh_example_pubmed_mapped.tsv](https://raw.githubusercontent.com/Delta4AI/OntoloViz/master/web/public/templates/mesh_example_pubmed_mapped.tsv)                                     | MeSH-based example from [PubMed](https://pubmed.ncbi.nlm.nih.gov/) titles + abstracts; disease-related MeSH terms extracted and mapped onto the MeSH tree.                                                                       |
+
+All five files also ship inside the wheel and are reachable at `/templates/*.tsv` from the bundled web app.
 
 ---
 

VERSION

@@ -0,0 +1 @@
+3.0.1