ILR toolkit for apprenticeship data submission
Iris converts learner data from CSV exports into ILR-compliant XML for ESFA submission, with explicit validation and cross-submission consistency checking.
- Full-screen interactive terminal interface (primary UX)
- Parses CSV exports using header-based matching (tolerates column reordering)
- Generates ILR-compliant XML for ESFA submission
- Interactive error exploration and validation workflows
- Semantic validation beyond structural XML checks
- Cross-submission consistency checking using historical data
- Direct commands for automation and scripting
- Desktop app for users who prefer GUI
# Install dependencies
bun install
# Run TUI locally
bun run src/cli.ts
# Link globally and use TUI
bun link
iris # Launch full-screen TUI
# Direct command invocation (not yet implemented)
iris convert file.csv # Direct command (scriptable)
iris --help
# Run tests
bun test
# Desktop app
bun tauri devBuilt on a shared TypeScript core with multiple interfaces:
- TUI (primary): @opentui/core, full-screen interactive interface
- Direct Commands: Scriptable automation with beautiful output
- Desktop: Tauri + SvelteKit, cross-platform native app (macOS, Windows, Linux)
All interfaces use identical transformation and validation logic from src/lib/.
See docs/adrs/ for architectural decisions and docs/technical/tui-ux-design.md for TUI design details.
iris/
├── src/
│ ├── lib/ # Shared core (parser, validator, generator, storage)
│ ├── tui/ # TUI interface (screens, components, workflows)
│ ├── commands/ # Direct command implementations
│ ├── cli.ts # Entry point (routes to TUI or commands)
│ └── routes/ # SvelteKit desktop UI
├── src-tauri/ # Tauri Rust backend
├── docs/ # Documentation, roadmaps, ADRs, technical specs
└── tests/ # Vitest tests
See .claude/CLAUDE.md for detailed development conventions and commands. Primary runtime/tooling and test commands are exposed in package.json scripts.
The Tauri desktop app (bun tauri dev / bun tauri build) compiles a Rust backend, so it needs a Rust toolchain on top of Bun:
rustup updatesrc-tauri/Cargo.toml pins rust-version = "1.88.0"; bun tauri build fails with an opaque cargo error on an older toolchain.
Terminal recordings for the README and docs are scripted with Charm VHS. Tapes live in tapes/ and share settings from tapes/_common.tape (dimensions, font, and a theme mirroring Iris' brand palette).
New to Iris? Start with the quickstart tutorial: a non-technical, first-launch-to-submission walkthrough.
A walkthrough of each recording, with fuller commentary, lives in docs/tutorials/workflows.md.
Convert: CSV to ILR XML
Validate: check a submitted XML file
Cross-Submission Check: compare current against previous
Mapping Builder: browse and duplicate CSV→XSD mappings
Prerequisites (macOS/Homebrew):
brew install vhs ttyd ffmpeg
bun linkSee the VHS repo for other platforms. bun link puts the iris command on PATH; the tapes launch the app the same way a real user would, not via bun run cli.
Regenerate all recordings:
bun run demosThis renders every tapes/*.tape file (skipping shared includes prefixed with _) into docs/assets/. The recording font (Fira Code) is bundled at assets/fonts/ and installed automatically on first run.