# UHRI+ — UN Human Rights Recommendations Dashboard (GitHub Pages)

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21319464.svg)](https://doi.org/10.5281/zenodo.21319464)
[![License: PolyForm Noncommercial](https://img.shields.io/badge/license-PolyForm%20Noncommercial-blue.svg)](LICENSE)
[![Dataset: Hugging Face](https://img.shields.io/badge/dataset-Hugging%20Face-yellow.svg)](https://huggingface.co/datasets/lszoszk/uhri-recommendations)

Static, zero-build dashboard for searching and analysing **272,502** cleaned
country-specific UN human-rights observations and recommendations (Treaty
Bodies, Universal Periodic Review, Special Procedures, 2006–2026), built on
the OHCHR Universal Human Rights Index.

**Live:** <https://lszoszk.github.io/UnitedNations_recommendations/>
**Dataset (HuggingFace):** <https://huggingface.co/datasets/lszoszk/uhri-recommendations>

**License:** [PolyForm Noncommercial 1.0.0](LICENSE) — research, education,
non-profit and personal use are permitted; redistribution must keep the
attribution notice; commercial use requires a separate licence from the
author. Bundled libraries retain their respective MIT / Apache 2.0
licences ([NOTICE](NOTICE)).

> **For engineering orientation see [ARCHITECTURE.md](ARCHITECTURE.md)** —
> module map, load order, cross-module surface, extraction conventions.

## What is included
- `index.html`: landing page
- `ai.html`: how to use the dataset from an AI assistant (hosted MCP connector), written for both the reader and the assistant
- `dashboard.html`: the dashboard application + 20 sibling `dashboard-*.js` modules (no bundler, classic `<script defer>` load order)
- `sw.js`: service worker (app-shell cache)
- `tests/`: Playwright suites — `smoke.spec.ts` (22 scenarios) plus `a11y`, `user-flows`, `contracts`, `tab-walk`, and others
- `scripts/`, `docs/`, `llms.txt`: count-sync tooling, methodology comparison, and an agent-friendly site summary

## How it works
The dashboard is fully static on GitHub Pages and reads data at runtime from a
FastAPI backend on a VM (SQLite + FTS5), with a 15-minute edge cache. Users can
also upload their own UHRI Excel/JSON export to browse it locally (no server
round-trip). There is no login.

VM API base: `https://150.254.115.204/uhri-api`. Main endpoints
(all under `/api/data/`):

| Endpoint | Purpose |
|---|---|
| `/health` | liveness probe |
| `/facets` | filter vocabularies (countries, bodies, themes, …) |
| `/records` | paginated, filtered records (full-text search via FTS5) |
| `/analytics` | aggregates for the current filter (trends, themes, SDGs) |
| `/map` | per-country counts for the hex / choropleth map |
| `/record/{annotation_id}` | a single record |
| `/export`, `/full` | bulk export of a filtered subset |
| `/feedback/report` | user-submitted data-quality reports |

Admin-only operations (`POST /mv/rebuild`, `DELETE /cache_status`) require an
`X-Admin-Key` header. The machine-readable `/openapi.json` is public; the
interactive Swagger UI is disabled in production.

## Query it from an AI assistant (MCP)
The dataset is also served over the Model Context Protocol by the companion
[`mcp-unhrdb`](https://github.com/lszoszk/mcp-unhrdb) server. The hosted
endpoint (Streamable HTTP, no token) is `https://150.254.115.204/unhrdb-mcp-rpc/mcp`; add it as a
custom connector in Claude or ChatGPT, or in Claude Code:

```bash
claude mcp add --transport http unhrdb https://150.254.115.204/unhrdb-mcp-rpc/mcp --scope user
```

Tools: `search_recommendations`, `lookup_recommendation`, `list_uhri_facets`
(this dataset) plus `search_paragraphs`, `lookup_by_citation` (General Comments,
jurisprudence, Special Procedures reports). `ai.html` is the non-technical
guide — paste its address into an assistant and it walks the user through.

## Deploy with GitHub Pages
1. Push this folder as its own GitHub repository.
2. In GitHub: `Settings` → `Pages`.
3. Set source to `Deploy from a branch`.
4. Select branch `gh-pages` and folder `/ (root)`.
5. Save and wait for the Pages URL to appear.

## Dataset & methodology
The cleaned dataset is produced by a transparent **5-stage pipeline** (OCR/HTML
repair → LLM-assisted residue review → AnnotationType normalisation → country
backfill from document symbols → artefact drop). Full detail is on the
dashboard's **Methodology** tab and in the HuggingFace dataset card. The
canonical record count is maintained in `scripts/counts.json` and synced across
the UI by `scripts/update-counts.mjs`.

## Citation

> Szoszkiewicz, Ł. (2026). *UHRI+ — UN Human Rights Recommendations
> Dashboard* (Version 1.0.0) [Computer software]. Zenodo.
> https://doi.org/10.5281/zenodo.21319464

GitHub exposes machine-readable citation metadata from
[`CITATION.cff`](CITATION.cff). When citing a specific query result, also
record the dataset version and exact query and filters.

The cleaned dataset is a separate research object distributed through
[Hugging Face](https://huggingface.co/datasets/lszoszk/uhri-recommendations)
under CC BY-NC 4.0. Its citation should be used when the data, rather than the
dashboard software, is the object of reuse.