enyalien

enyalien is a historical browser and dataset builder for the ChGK A-rating.

It preserves authoritative historical rating releases, enriches their surrounding domain data from the documented ChGK API, materializes an immutable SQLite snapshot, and serves read-only JSON and HTML views.

Name

The name enyalien is based on Quenya enyalië, “memory, (lit.) recalling”, and its dative enyalien, “in memory [of]” / “for the re-calling, to recall or commemorate [the glory]”.

The cited references are Unfinished Tales (UT/305, UT/317). The documented elements are #enyal- “to recall”, -ië “gerund suffix, -ing”, en- “re-, again”, and yal- “to summon”.

The attested example is:

vanda sina termaruva Elenna-nóreo alcar enyalien — “This oath shall stand in memory of the glory of the Land of the Star”.

The software name changes to enyalien, but the application's domain terminology remains unchanged: rating, release, team, player, tournament, base roster, tournament roster, and so on.

Development

The project uses Clojure on Java 21+ and Babashka for project tasks.

bb lint
bb test
bb test:conv
bb test:docs
bb conv /path/to/output.sqlite /path/to/source.sql
bb fetch --source /path/to/source.sqlite --cache-dir target/enyalien-cache
bb build-database --source /path/to/source.sqlite --cache-dir target/enyalien-cache --output target/rating-a.sqlite
bb docs:api
bb server
bb uber

The initial uberjar is written to:

target/enyalien.jar

The runtime and collector are deliberately separate: runtime namespaces live under src/enyalien, while acquisition/materialization tooling lives under src/collector.

Documentation

See docs/spec.md for the normative specification, docs/mysql-dump-conversion.md for the MySQL-to-SQLite conversion workflow, and docs/tickets/00-milestones.md for the implementation roadmap.

Data workflow

The complete data workflow has three distinct stages:

1. bb conv OUTPUT.sqlite DUMP.sql... converts one or more MySQL dumps into the authoritative SQLite source dataset.
2. bb fetch --source SOURCE.sqlite --cache-dir CACHE recursively acquires the external API data into a resumable cache. --until DATE bounds historical acquisition and --refresh permits refetching cached resources.
3. bb build-database --source SOURCE.sqlite --cache-dir CACHE --output DATASET.sqlite materializes a new immutable runtime snapshot from the source dataset and cache.

The runtime can then be started with bb server. The packaged distribution is built with bb uber. The bb ci task runs linting, Clojure tests, conversion tests, documentation checks, packaging, and the clean-distribution smoke test.

Babashka passes task arguments directly to the task; this project does not use -- as a separator between Babashka arguments and task arguments.

Collector API client

A single resource can be fetched or repaired with:

bb fetch --type teams --id 1
bb fetch --type tournaments --id 123 --refresh

The recursive collector is implemented in collector.core:

bb fetch --source SOURCE.sqlite --cache-dir target/enyalien-cache

It is sequential and resumable, and discovers typed API identities recursively from the authoritative source tables. If the external API requires authentication, set ENYALIEN_API_TOKEN; it is sent as a Bearer token.

Documentation generation

The runtime API contract is executable Malli data in src/enyalien/api_schema.clj. Generate its checked-in contract reference with:

bb docs:api

bb test:docs verifies that the generated page is synchronized with the source contract.