📜 Know the Law

An open, schema-validated dataset of legal-literacy questions and a privacy-first quiz game that runs entirely in your browser — no server, no accounts, no tracking, works offline.

▶ Live demo: https://goshrum.github.io/zakon-quest/

• Why this project
• Features
• The open dataset
• Quick start
• Install & offline
• Project scripts
• Architecture
• Contributing
• Governance & maintainers
• Security
• Roadmap
• License

Legal-literacy material is scarce, fragmented, and rarely available as open, machine-readable, citable data. Know the Law tackles both halves of that problem:

1. An open dataset of legal-literacy questions — every entry carries a citation to a verifiable, stable source, validated by a JSON Schema in CI, and published under CC BY 4.0 so anyone can reuse it.
2. A delightful way to learn it — a fast, accessible, offline-capable quiz game that turns the dataset into practice, with scoring, streaks, levels, spaced repetition, and a study/browse mode.

The quiz engine is deliberately jurisdiction-agnostic: the current dataset covers the Russian legal system (in English), and the project is structured so contributors can add other jurisdictions as separate datasets. See docs/adding-a-jurisdiction.md.

⚖️ Educational only — not legal advice. Norms change over time; every question cites its source so you can verify it. See docs/CONTENT_POLICY.md.

• 🎯 Four question types — pick the governing code, guess the article, true/false legal myths, and short case scenarios.
• 🔥 Game feel — combo multipliers, optional timer + speed bonus, XP, ranks, and a results screen.
• 🧠 Spaced repetition — questions you miss come back; a dedicated review your mistakes mode.
• 📚 Study mode — searchable, pressure-free browse of every question with its answer, explanation, and citation.
• 📊 Lifetime stats — accuracy overall and per legal branch.
• ♿ Accessible — keyboard support, focus management, ARIA live regions, reduced-motion support, skip link.
• 🔒 Private & offline — 100% client-side, installable PWA, progress stored only in your browser.

The question bank is a first-class artifact, not hard-coded strings:

• Canonical data: src/data/questions.json
• Contract: src/data/questions.schema.json (JSON Schema, draft 2020-12)
• Docs: docs/data-schema.md
• License: CC BY 4.0 — LICENSE-DATA

Validate it anytime:

npm run validate:data

Reuse it in your own project, cite it (see CITATION.cff), and contribute corrections — citation-backed fixes are fast-tracked.

Requires Node 18, 20, or 22 (see .nvmrc).

git clone https://github.com/goshrum/zakon-quest.git
cd zakon-quest
npm install
npm run dev        # start the dev server

Build and preview a production bundle:

npm run build
npm run preview

The app is a Progressive Web App. Open the live demo and use your browser's Install action to add it to your device. Once loaded, it works fully offline — the service worker precaches the app shell, and there are no network calls at runtime.

A pure, unit-tested core (src/lib) with a thin DOM shell (src/main.ts) over an open dataset (src/data). Full write-up in docs/ARCHITECTURE.md; decisions are recorded as ADRs in docs/adr/.

Contributions of all kinds are welcome — code, accessibility, docs, and especially citation-backed question fixes and additions. Start with CONTRIBUTING.md and the Code of Conduct. We use Conventional Commits and automate releases with release-please.

This project has documented governance and a maintainers list describing roles, decision-making, releases, and how to become a maintainer.

Found a vulnerability? Please report it privately — see SECURITY.md. Dependencies are monitored with Dependabot and the code is scanned with CodeQL.

See ROADMAP.md for what's planned and where help is most useful.

• Code: MIT
• Question dataset: CC BY 4.0