jpn_word_trainer_data/README.md

Japanese Word Trainer Deck Registry

This repository is the public word-deck data registry for the 0.3 package model. It keeps JSON as the source of truth and publishes zip package artifacts that the app can download and verify.

Layout

• registry.json is the root registry file read by the app.
• sources/official/<slug>/ contains editable official deck package JSON.
• sources/custom/<slug>/ contains editable published custom deck package JSON.
• packages/*.zip contains generated app-installable package artifacts.
• scripts/build_packages.py builds packages and refreshes registry checksums.
• scripts/validate_registry.py validates source JSON, packages, and checksums.

Each package zip contains exactly:

manifest.json
words.json
refs.json

Build

Run from the repository root:

python3 scripts/build_packages.py
python3 scripts/validate_registry.py

build_packages.py fills each word contentHash, creates deterministic zip files in packages/, and updates registry.json with wordCount, packageUrl, and sha256.

By default, generatedAt is left unchanged to avoid noisy rebuild diffs. Use --update-generated-at when intentionally publishing a freshly generated registry:

python3 scripts/build_packages.py --update-generated-at

Package Rules

• Stable deck keys use {registryId}:deck:{slug}.
• Stable word keys use {registryId}:word:{slug-or-id}.
• versionCode changes when package content changes.
• contentHash is computed from a word record excluding contentHash.
• refs.json owns deck membership and display order. A ref may point to a word supplied by the same package or to an already installed dependency such as an official deck word.
• The same package shape is used for official, registry custom, imported, and local-exported decks.

Current Samples

• official:deck:jlpt-n5 is a tiny official sample based lightly on the app seed vocabulary. It is not the full JLPT N5 set.

The sample data is intentionally small so app migration, import, and checksum handling can be tested before the full public deck corpus is populated.