Juddges App — Open-Science & FAIR4RS Report¶

search and information extraction over Polish and England & Wales court judgments

Software-sustainability and reproducibility report for the Juddges App codebase, structured as direct answers to standard open-science evaluation criteria (FAIR4RS / EOSC software-sustainability).

Repository: https://github.com/pwr-ai/juddges-app Last verified against the repository: 2026-04-30.

Juddges App is the hosted web-app companion to the upstream JuDDGES research project, which supplies the underlying datasets and NLP methodology. Juddges App is a separate, independently deployable codebase released under its own Apache-2.0 license and its own Zenodo concept DOI (10.5281/zenodo.19911856).

1. Project context and purpose¶

Aspect Description

Briefly describe the context and purpose The Juddges App repository provides an end-to-end web application for hybrid search, retrieval-augmented chat, structured information extraction, and analytics over Polish and England & Wales court judgments. It is built for legal experts, legal-NLP researchers, and dataset annotators who need to interactively explore case-law corpora and extract structured artefacts from them. The application is composed of six tightly integrated capabilities. (1) Hybrid semantic + full-text search combining Supabase pgvector (embeddings on the judgments table) and Meilisearch (full-text), implemented under backend/packages/juddges_search/ and the search routers in backend/app/routers/. (2) Retrieval-augmented chat for legal research, grounded in retrieved judgments, exposed over LangServe via the chat chain in backend/packages/juddges_search/ (from juddges_search.chains.chat import chat_chain). (3) Schema-driven information extraction via a LangGraph agent under backend/packages/schema_generator_agent/, which generates a Pydantic schema and runs LLM extraction against a chosen corpus slice. (4) Research-agent workflows for multi-step legal investigations under backend/packages/research_agent/. (5) Annotation workspace with rich-text (TipTap) editing, persisted server-side and exposed through the frontend at frontend/. (6) Analytics dashboard for jurisdiction, court and decision-trend insights, served by the analytics router in backend/app/ and rendered by the Next.js frontend.

The repository was created so the JuDDGES research initiative can ship its datasets and models as an interactive product — and so that any third party can self-host the same stack against their own legal corpus. It can be reused by anyone wishing to (a) run a hybrid semantic + full-text search service over judgment-style legal documents, (b) ground a chat assistant on a curated legal corpus, (c) bootstrap structured-extraction pipelines on top of a Supabase + LangChain stack, or (d) build domain-specific annotation workflows on top of the same backend. Sample data is loaded with scripts/ingest_judgments.py against the public Hugging Face datasets at https://huggingface.co/JuDDGES — the Polish corpus is JuDDGES/pl-appealcourt-criminal (DOI 10.57967/hf/8772) and the UK corpus is JuDDGES/en-appealcourt (DOI 10.57967/hf/8773).

2. Evaluation criteria¶

Criterion	Sub-question	Answer
DOCUMENTATION — License & accessibility	How can the repository be accessed by third parties?	Public, registration-free GitHub at https://github.com/pwr-ai/juddges-app (default branch: `main`). A single Apache 2.0 license covers code and documentation — `frontend/package.json` and `backend/pyproject.toml` both declare `Apache-2.0`. A live demo is published at https://pwr-ai.github.io/juddges-app/ for the documentation site; the application itself is self-hostable via Docker Compose, with pre-built images on Docker Hub (`${DOCKER_USERNAME}/juddges-{frontend,backend}`) tagged with each `prod-v<semver>` release. External services that consumers must provision themselves (Supabase / pgvector + Auth, OpenAI-compatible LLM endpoint, Meilisearch, Redis, optional Langfuse) are all open-source or have free tiers. The persistent identifier for the v0.1.0 snapshot is the Zenodo concept DOI 10.5281/zenodo.19911856.
	What type of documentation is available, provided with the project and delivered under the same conditions?	Multi-layer documentation under the same Apache-2.0 license: (a) Top-level project overview, install steps, and quick-start in `README.md`, inlined verbatim into this report so it can be read standalone. (b) `docs/` directory organised under the Diátaxis framework — `tutorials/`, `how-to/`, `reference/`, `explanation/` — plus onboarding-oriented `getting-started/`, `architecture/`, `features/`, and `open-science/` sections. (c) Static documentation site config at `mkdocs.yml` (Material for MkDocs), built and deployed by `.github/workflows/docs.yml`, rendered at https://pwr-ai.github.io/juddges-app/. (d) Interactive backend API documentation generated by FastAPI from the typed Python schemas — Swagger UI at `http://localhost:8004/docs` and ReDoc at `http://localhost:8004/redoc` (an OpenAPI 3 specification). (e) Per-package READMEs under `backend/packages/` for `juddges_search`, `schema_generator_agent`, and `research_agent`. (f) Search-benchmark methodology at `docs/explanation/search-benchmark-methodology.md`.
	Does the documentation describe how to use/build/deploy/install the project?	Yes — and the project IS a hosted web application (it is the deployable companion to the JuDDGES research codebase). Coverage: (a) Install / quick start — `README.md` covers prerequisites, environment configuration (`cp .env.example .env`), Supabase migration with `npx supabase db push`, and Docker-based local startup (`docker compose -f docker-compose.dev.yml up --build`). Native (non-Docker) paths use Poetry for the backend (`poetry install && poetry run uvicorn app.server:app --reload --port 8004`) and npm for the frontend (`npm install && npm run dev`). (b) Build / lint / test targets are exposed via Poe-the-Poet on the backend (`backend/pyproject.toml` `[tool.poe.tasks]`, e.g. `poetry run poe check-all`) and npm scripts on the frontend (`frontend/package.json`, e.g. `npm run validate`, `npm run test`). (c) Build & deploy — production images are built manually via `scripts/build_and_push_prod.sh` (no Docker builds run in GitHub Actions). Deployment on the production host is handled by `scripts/deploy_prod.sh` (with `--rollback`). Detailed flow is documented at `docs/how-to/deployment.md`. (d) Data ingestion — `scripts/ingest_judgments.py` with `--polish N --uk N` flags for both quick smoke tests (`--polish 10 --uk 10`) and full populations (`--polish 3000 --uk 3000`); detailed walkthrough at `docs/how-to/data-ingestion.md`. (e) External services are pinned via `docker-compose.yml` (production) and `docker-compose.dev.yml` (development with hot reload).
TESTING — Sample data & parameters	Are sample data and/or parameters that can be used to test the project available with the source code?	Yes, in four categories. (a) Automated tests. Backend uses `pytest` with `@pytest.mark.unit` and `@pytest.mark.integration` markers under `backend/tests/`; integration tests require live Supabase, Redis, and an OpenAI-compatible endpoint. The aggregate target is `poetry run poe check-all` (`backend/pyproject.toml` `[tool.poe.tasks]`). Frontend uses Jest for unit tests and Playwright for end-to-end browser tests, runnable via `npm run test` and `npm run validate` (`frontend/package.json`). (b) Sample data is not committed to the repository (judgments would dwarf the source tree). Instead it is fetched on demand from the public JuDDGES Hugging Face datasets at https://huggingface.co/JuDDGES by the ingestion CLI — Polish: JuDDGES/pl-appealcourt-criminal (DOI 10.57967/hf/8772); UK: JuDDGES/en-appealcourt (DOI 10.57967/hf/8773). (c) Use-case example scripts under `scripts/` — most notably `scripts/ingest_judgments.py` (with `--polish` / `--uk` sample-size flags), `scripts/build_and_push_prod.sh`, and `scripts/deploy_prod.sh`. (d) Reference configurations / runnable examples. Each runnable script ships matching configuration: `.env.example` for application config, the two `docker-compose*.yml` files for the service topology, and the search-benchmark methodology in `docs/explanation/search-benchmark-methodology.md` describes how to evaluate the search stack against a known corpus.
INTEROPERABILITY — Standard I/O formats	Do you use existing and standard input/output formats?	Yes. HTTP REST API with JSON request/response bodies is the primary external surface, fully described by an auto-generated OpenAPI 3 specification at `/docs` (Swagger UI) and `/redoc` — importable into any standards-compliant client generator. A GraphQL surface (Strawberry) is available for selected query endpoints. PostgreSQL via Supabase is the primary store; vector embeddings live in standard `vector(768)` columns indexed with HNSW through pgvector. The full-text search service is Meilisearch. Markdown is used for all documentation; YAML for compose files and the MkDocs configuration; JSON for ingestion artefacts and frontend configuration. Citation metadata is published in CFF v1.2.0 (`CITATION.cff`) and CodeMeta v3.0 JSON-LD (`codemeta.json`). LLM access goes through OpenAI-compatible REST (so any provider supporting that spec — OpenAI, vLLM, Ollama, LiteLLM, self-hosted endpoints — can drop in). Dependency manifests are themselves standard formats: `backend/pyproject.toml` + `backend/poetry.lock` (Python, Poetry) and `frontend/package.json` + `frontend/package-lock.json` (Node, npm).
VERSIONING — Source-code version control	Do you use a version control system?	Yes. Git + GitHub at https://github.com/pwr-ai/juddges-app. Two-branch model: `main` is production and only accepts `develop → main` release PRs and `hotfix/` PRs; `develop`* is the integration branch where feature/fix branches are reviewed via pull request. Commit messages follow Conventional Commits. Backend code quality is enforced with Ruff (format + lint, `poetry run poe check-all`); frontend is enforced with ESLint + Next.js config and TypeScript strict mode (`npm run validate`). Production releases are marked by annotated Git tags `prod-v<semver>` (e.g. `prod-v0.1.3`); the script `scripts/build_and_push_prod.sh` keeps `VERSION`, `backend/pyproject.toml`, `frontend/package.json`, and `.env.example` in sync. The repository runs one GitHub Actions workflow at present — `.github/workflows/docs.yml`, which builds and deploys the MkDocs Material site to GitHub Pages. Test/quality CI is run locally via the Poe and npm targets above; a dedicated CI workflow for them is on the backlog. Docker images are built manually, not in GitHub Actions — see § REPRODUCIBILITY.
REPRODUCIBILITY — Releases	Do you provide releases of your software?	Yes — three layers. (a) Annotated Git tags of the form `prod-v<semver>` on `main` (e.g. `prod-v0.1.3`) — see https://github.com/pwr-ai/juddges-app/tags. (b) Docker images on Docker Hub at `${DOCKER_USERNAME}/juddges-{frontend,backend}`, tagged with the matching version and `latest`. The `backend-worker` and `backend-beat` services reuse the `juddges-backend` image with different commands. Image builds run manually through `scripts/build_and_push_prod.sh` (which auto-bumps from the latest `prod-v` tag, syncs version files, builds + pushes, then tags); no GHA Docker pipeline exists. Deployment uses `scripts/deploy_prod.sh` (with `--rollback`). (c) Zenodo persistent DOI* archive for citation: concept DOI `10.5281/zenodo.19911856` (always-latest). The application does not use DVC / Snakemake / Nextflow pipelines — datasets are pulled from public Hugging Face datasets at ingestion time, not committed as DVC pointer files.
	How do you define language-specific dependencies of your project and their version?	Per-language manifests at the root of each subtree, all committed: - Python (backend, 3.12+) — `backend/pyproject.toml` declares the package and optional install groups; `backend/poetry.lock` pins every transitive dependency to an exact version (managed by Poetry). Reusable Poetry packages `juddges_search`, `schema_generator_agent`, and `research_agent` are installed editable (`develop = true`). - JavaScript / TypeScript (frontend, Node 18+) — `frontend/package.json` declares dependencies; `frontend/package-lock.json` pins every transitive dependency. Frontend is Next.js 15 (App Router) on React 19 with Tailwind 4, Zustand, and TanStack Query. - Container runtime — Dockerfiles in `backend/Dockerfile` and `frontend/Dockerfile`; orchestration in `docker-compose.yml` (production) and `docker-compose.dev.yml` (development with hot reload). External services (Supabase, Meilisearch, Redis, optional Langfuse) are pinned through these Compose files so reconstructing the stack does not pollute the host system. The image tag is controlled by the `JUDDGES_IMAGE_TAG` environment variable (default `latest`).
BUG REPORTING (software users)	Do you state how to report bugs and/or usability problems by the software user(s)?	Yes. Developers and operators are directed to the GitHub Issues tracker at https://github.com/pwr-ai/juddges-app/issues. Four templated issue forms ship under `.github/ISSUE_TEMPLATE/`: `bug_report.yml`, `feature_request.yml`, `documentation.yml`, and a `config.yml` that disables blank issues and links to GitHub Discussions and Security Advisories. Pull requests are reviewed against `.github/PULL_REQUEST_TEMPLATE.md`. Contribution conventions are summarised in the root `CONTRIBUTING.md` and detailed in `docs/contributing/CONTRIBUTING.md`. Conduct expectations live in a project-specific `CODE_OF_CONDUCT.md`. Coordinated vulnerability disclosure is handled via `SECURITY.md`.
BUG REPORTING (web-app users)	Do you state how to report bugs and/or usability problems by the web app user(s)?	Yes — Juddges App is a hosted web application, and end-user feedback is collected through two channels. (a) In-app feedback widget. Each search result and chat response includes a thumbs-up / thumbs-down control. The signal is persisted by the backend `feedback` router under `backend/app/`, so usability problems and quality regressions are captured directly from the deployment without requiring a GitHub account. (b) GitHub Issues. Public-facing bug reports for hosted deployments are also accepted at https://github.com/pwr-ai/juddges-app/issues, using the same four issue templates listed above. Sensitive vulnerability reports go through `SECURITY.md`, not the public tracker.
RECOGNITION — Citation information	Do you include citation information (i.e. how to cite your software in the form of citation.cff, codemeta.json or bibtex)?	Yes — all three canonical formats are shipped, all carrying the same author roster and pointing at the same Zenodo deposit. 1. `CITATION.cff` — Citation File Format v1.2.0 at the repository root. Consumed by GitHub's "Cite this repository" widget, Zenodo, Zotero, Mendeley, OpenAIRE. 2. `codemeta.json` — CodeMeta v3.0 JSON-LD (`@context: https://w3id.org/codemeta/3.0`, `@type: SoftwareSourceCode`). Consumed by HAL, OpenAIRE, Software Heritage, re3data. 3. Zenodo persistent DOI — concept DOI `10.5281/zenodo.19911856` (always-latest, v0.1.0). 4. Copy-pasteable BibTeX — see the block immediately below this table. Software-author roster (seven authors across three institutions): Łukasz Augustyniak, Jakub Binkowski, Albert Sawczyn, Kamil Tagowski, Tomasz Kajdanowicz (Wrocław University of Science and Technology); Michał Bernaczyk (University of Wrocław); Krzysztof Kamiński (Court of Appeal, Wrocław). Juddges App builds on, but is independent from, the upstream JuDDGES research project at https://github.com/pwr-ai/JuDDGES — the latter is the canonical source of the underlying datasets and methodology.

BibTeX¶

@software{augustyniak2026juddgesapp,
  author    = {Lukasz Augustyniak and Jakub Binkowski and Albert Sawczyn and
               Kamil Tagowski and Michal Bernaczyk and Krzysztof Kaminski and
               Tomasz Jan Kajdanowicz},
  title     = {Juddges App: AI-powered judicial decision search and analysis
               for Polish and England \& Wales court judgments},
  year      = {2026},
  version   = {0.1.0},
  doi       = {10.5281/zenodo.19911856},
  url       = {https://github.com/pwr-ai/juddges-app},
  publisher = {Zenodo}
}

3. Open-science checklist — current status¶

The verifications above against the repository as of 2026-04-30 identified twelve open-science items beyond the FAIR4RS / EOSC software-sustainability baseline. 10 of 12 are now in place (including a Zenodo-minted persistent DOI and a project-specific CODE_OF_CONDUCT.md); one requires an off-repo action on an account the project owner controls (Software Heritage); one is intentionally deferred until a community-stable production release.

#	Item	Principle	Status	Where it lives
1	`CITATION.cff` (CFF v1.2.0)	FAIR4RS R1.2 — machine-readable citation metadata	✅ Done	`CITATION.cff`
2	`codemeta.json` (CodeMeta v3.0 JSON-LD)	FAIR4RS R1.2 — cross-platform research-software metadata	✅ Done	`codemeta.json`
3	GitHub Release + Zenodo DOI	FAIR4RS F1 — globally unique persistent identifier	✅ Done	Concept DOI `10.5281/zenodo.19911856`; badge in `README.md`
4	`CONTRIBUTING.md`	EOSC sustainability — contributor onboarding	✅ Done	`CONTRIBUTING.md` (root, brief) + `docs/contributing/CONTRIBUTING.md` (detailed)
5	`CODE_OF_CONDUCT.md`	EOSC community-health	✅ Done	`CODE_OF_CONDUCT.md` — project-specific code of conduct adapted for the JuDDGES App's cross-disciplinary, cross-jurisdictional research community
6	`SECURITY.md`	EOSC sustainability — coordinated vulnerability disclosure	✅ Done	`SECURITY.md`
7	`.github/ISSUE_TEMPLATE/` (4 files)	EOSC sustainability — triage hygiene	✅ Done	`bug_report.yml`, `feature_request.yml`, `documentation.yml`, `config.yml`
8	`.github/PULL_REQUEST_TEMPLATE.md`	EOSC sustainability — PR review hygiene	✅ Done	`PULL_REQUEST_TEMPLATE.md`
9	Software Heritage SWHID	FAIR4RS F1 — archival permanence beyond GitHub	⚠ Pending — external action (see below)	n/a
10	Domain-specific runnable examples (each ships matching schema + form/config)	Reproducibility — symmetric reference assets	✅ Done	`scripts/ingest_judgments.py` (`--polish` / `--uk` flags) + tests under `backend/tests/` and `frontend/__tests__/` + benchmark methodology at `docs/explanation/search-benchmark-methodology.md`
11	`docs/index.md` landing page	Documentation accessibility — clears `mkdocs build --strict` warning	✅ Done	`docs/index.md`, rendered at https://pwr-ai.github.io/juddges-app/
12	OpenSSF Best Practices badge / Scorecard	Third-party software-sustainability indicator	⏭ Intentionally deferred	Will be revisited after the first stable production release

Pending external actions¶

One item can only be closed off-repo on accounts the project owner controls. It is not a blocker; it materially improves archival permanence.

Software Heritage SWHID (#9). Steps: (a) open https://archive.softwareheritage.org/save/, (b) submit https://github.com/pwr-ai/juddges-app, (c) wait for the archival job to complete (typically minutes), (d) copy the resulting swh:1:dir:… SWHID and add it to CITATION.cff under the existing identifiers: block (with type: swh), and to codemeta.json as an additional identifier. Effort: ≈ 10 minutes.

Items already met (no action required)¶

Public hosting on GitHub with permissive Apache-2.0 license covering both code and documentation.
Diátaxis-organised docs/ directory plus a published Material for MkDocs site at https://pwr-ai.github.io/juddges-app/.
Auto-generated OpenAPI 3 specification (Swagger UI + ReDoc) for the backend HTTP API.
Per-language dependency lockfiles (backend/poetry.lock, frontend/package-lock.json) and Docker Compose files pinning all external services.
pytest (with unit / integration markers), Jest, and Playwright test suites runnable through poetry run poe check-all and npm run validate && npm run test.
Annotated prod-v<semver> Git tags + Docker Hub images + Zenodo concept DOI for every release.
Standard interoperable I/O formats (JSON, OpenAPI 3, GraphQL, PostgreSQL + pgvector, Markdown, YAML, CFF v1.2.0, CodeMeta JSON-LD).
Issue and pull-request templates, contributor guide, security policy, and an in-app feedback widget for end users of the hosted application.
Citation triple — CITATION.cff, codemeta.json, and a copy-pasteable BibTeX block — all minted to the same Zenodo concept DOI.

This list also doubles as the project's open-science evidence summary for funder reports.