Open consequence graph and public Clarvia monorepo for source-backed administrative workflows
Status: CI passing · OpenSSF Best Practices: passing · OpenSSF Scorecard · REUSE compliant · Codecov · SonarCloud · Code: EUPL-1.2 · Data: CC-BY-4.0 · DOI: 10.5281/zenodo.20572455 · FAIR: 4/5
Clarvia Graph is reusable public-interest digital infrastructure. While it serves as the technical engine behind the consumer-facing checklist at clarvia.org, it is designed as an open, source-backed administrative workflow repository. It structures official rules, deadlines, and requirements for bereavement paperwork so that any application, civic-tech portal, research project, or public service can consume and adapt them automatically.
This repository is Clarvia’s public monorepo: the consequence graph, the clarvia.org website, legislation data for agents (lex/), and the public-safe Lex email service (services/lex/) live here under path-filtered CI. See docs/MONOREPO.md for layout, licenses, and deploy boundaries.
Requires Node 22+ and pnpm 9.x (see root packageManager / .node-version). Python 3.12+ is needed for lex/ and services/lex/.
git clone https://github.com/clarvia-org/clarvia-graph.git
cd clarvia-graph
pnpm install
pnpm validate # graph
pnpm export-and-sync-web # refresh website checklist data
pnpm web:dev # clarvia.org locallyWorking on one area only? See sparse-checkout notes in docs/MONOREPO.md and CONTRIBUTING.md. Package READMEs: apps/web, lex/, services/lex/.
Clarvia Graph is being prepared for submission to the Digital Public Goods Alliance Registry as open, source-backed administrative workflow infrastructure for bereavement administration. See DPG.md for the DPG Standard mapping, open-license information, privacy and do-no-harm boundaries, SDG alignment, and reuse documentation.
📸 Alpha checklist preview
The living demo at clarvia.org/en/checklist consumes a static JSON export generated from this graph. See
exports/example-bereavement-lu.jsonfor the exact shape.
Technically, Clarvia Graph is a structured, versioned, source-backed knowledge graph for cross-border administrative consequences. It models what happens after a life event (starting with bereavement), what steps may be required, which authorities are involved, what documents are needed, and where the official source says so.
In this monorepo:
| Path | Role | Runtime |
|---|---|---|
graph/, schemas/, vocab/, sources/, packages/* |
Consequence graph + validation/export tooling | Git + CI exports |
apps/web |
Public website (clarvia.org) | Coolify / GCE |
lex/ |
Normalized national legislation for AI agents | Git + local CLI |
services/lex/ |
Lex email automation (public-safe code) | Cloud Run (europe-west1) |
clarvia-graph/
├── apps/
│ └── web/ # Next.js site (clarvia.org) — Coolify/GCE
├── services/
│ └── lex/ # Lex email service (public-safe; Cloud Run)
├── lex/ # Legislation dataset + CLI
├── schemas/ # JSON Schema definitions (v0.1)
├── vocab/ # Controlled vocabularies
├── graph/ # Consequence graph data (YAML)
│ ├── authorities/
│ ├── conditions/
│ ├── consequences/
│ ├── task_templates/
│ └── …
├── sources/ # Source registry, snapshots, and assertions
├── translations/ # Locale overlay files
├── tests/ # Scenario tests and unit tests
├── exports/ # Generated output (JSON, JSON-LD, web bundles)
├── packages/ # Workspace packages
│ ├── cli/ # @clarvia/cli — validation, build, and export tooling
│ └── generator/ # @clarvia/generator — checklist generation engine
├── docs/ # Foundation specification and guides (see MONOREPO.md)
└── build/ # Build output (git-ignored)
The root package.json is a pnpm workspace for packages/* and apps/*. Run pnpm install from the repository root. Website checklist data is synced in-repo via pnpm export-and-sync-web (not a cross-repo release pin). Python projects under lex/ and services/lex/ use their own uv / pip workflows.
🔒 Foundation specification locked — The foundation spec defines the complete data architecture, standards alignment, editorial governance, and extensibility model.
🚧 Early implementation in progress — Proof-of-concept, alpha, and beta work is proceeding with internal resources to validate the foundation before funded hardening, validation, and scale-up phases.
Clarvia Graph is being developed as the technical foundation for source-backed bereavement checklists and related administrative workflows across Europe.
The project is moving through rapid proof-of-concept, alpha, and beta phases. Early versions are built with internal resources so that the data model, graph structure, validation approach, and export pipeline can be tested before larger funding cycles conclude.
This early implementation work is not intended to replace funded development. It is intended to de-risk the technical foundation and demonstrate that the architecture can move from specification to working infrastructure.
Future funded phases will focus on raising the foundation to production quality: schema refinement, validation tooling, source provenance, test coverage, interoperability, documentation, governance, security hardening, maintainability, and support for multiple jurisdictions.
The intended path is to build quickly, learn from real implementation, and then use funded phases to validate, harden, document, and scale the graph responsibly.
flowchart LR
Source --> Snapshot --> Assertion --> Consequence --> Task["Task template"] --> Item["Checklist item"]
Every checklist item traces back to an official source. No legal consequence publishes without an approved source assertion.
- Source-backed: Every published claim traces to a captured official source
- Three-valued logic: Conditions evaluate to
true,false, orunknown— never hides uncertainty - Cross-border: Jurisdiction roles (death_place, habitual_residence, work_state, asset_situs) compose layered checklists
- Static exports: Consumer apps load generated JSON at build time — no runtime API dependency
- Privacy-first checklist: Checklist conditions are evaluated client-side, so personal circumstances are not sent to Clarvia’s servers for checklist generation. Separate services such as Lex process information as described in Clarvia’s Privacy & Cookie Policy.
- Public/private fence: Production secrets and live Lex prompts stay out of this repository (see
docs/MONOREPO.md)
This repository uses automated quality checks for tests, linting, static analysis, dependency and security scanning, documented installation, reproducible examples, citation metadata, licensing information, and archived releases. Path-filtered CI runs graph, web, legislation, and Lex email checks on every relevant pull request and release.
Clarvia maintains internal Clarvia-native schemas and generates compatibility views for:
- CPSV-AP — Core Public Service Vocabulary Application Profile
- CCCEV — Core Criterion and Core Evidence Vocabulary
- ELI — European Legislation Identifier
- PROV-O — W3C Provenance Ontology
Planned for next release: integrate
provPython library for PROV-O exports.Planned: use
SEMICeu/CPSV-APandSEMICeu/CCCEVofficial SHACL shapes as validation targets for CPSV-AP and CCCEV exports.
v0.1 technical validation scope: Bereavement workflows, Luxembourg proof dataset, and minimal cross-border fixtures for France/Germany/EU concepts where needed to test jurisdiction composition.
Designed for extension to: Additional jurisdictions (Belgium, Netherlands, ...) and life events (birth, relocation, ...) without schema changes.
Clarvia Graph is an open, source-backed knowledge graph for administrative consequences — designed so that others can study the architecture, adapt the schemas, and fork for their own regulatory domains.
The provenance chain, three-valued condition logic, publication gate, and EU standards alignment are domain-agnostic patterns. The bereavement/Luxembourg dataset is a working reference implementation. If you are building source-backed regulatory workflows for a different life event or jurisdiction, this repository provides a tested starting point.
Clarvia Graph is maintained by Clarvia ASBL, a Luxembourg-registered nonprofit.
Our current funding needs and contribution channels are published in the project's funding.json manifest.
Current priority: an adoption-ready first release covering stable versioning, documentation, reproducible examples, validation, automated testing, governance, and independent technical review.
Licenses are path-scoped (REUSE-compliant):
| Area | License |
|---|---|
Graph code & tooling (packages/, most root tooling) |
EUPL-1.2 |
| Graph data, vocab, schemas, docs | CC-BY-4.0 (see REUSE.toml) |
Website (apps/web) |
Apache-2.0 |
Legislation project code (lex/ authored code) |
Apache-2.0 |
| Official legislation corpus files | Source-specific (not relicensed; see lex/NOTICE) |
Lex email public-safe code (services/lex/) |
Apache-2.0 |
| Captured government HTML snapshots | LicenseRef-Gov-PublicDomain |
See CONTRIBUTING.md for how to get involved. Package-level notes live under apps/web/, lex/, and services/lex/.
We are grateful for the support of ecosystem partners who have endorsed Clarvia’s public-interest mission, including Trauerwee ASBL, which has expressed its intention to support a future pilot, and TSC Real Estate, which has endorsed our public-interest goals.
| Path / link | Role |
|---|---|
docs/MONOREPO.md |
Monorepo map, CI, deploy boundaries |
apps/web |
Website package (formerly workflow-web) |
lex/ |
Legislation dataset + CLI (formerly standalone clarvia-org/lex) |
services/lex/ |
Lex email service (public-safe) |
| workflow-data | Archived — legacy checklist data superseded by this graph |
| clarvia-org/.github | Organization community health files |
HirenGajjar built the original cross-border bereavement dataset in workflow-data — source records, institution registries, and corridor documentation for Belgium, France, Germany, and Portugal. That work materially accelerated the graph's cross-border coverage and now lives here as migrated authority, source, and condition records.