Gogaku

Japanese study companion.

Important

Consider this to be pre-alpha software. I make no guarantee of the stability of any documented APIs until the first official release.

Goal

This project aims to provide a fast, offline-first iOS experience for studying Japanese. Vocabulary lookup is powered by the standard community dictionaries (JMdict, KANJIDIC2, and friends), scheduling runs through the FSRS-6 algorithm, and the interface gradually shifts from English to Japanese as the user's vocabulary matures. Anything the user produces stays portable: cards, their scheduling, the review log and the settings are one SQLite file every frontend reads, which copies out as a backup and back in on another device.

Organization

The project is partitioned into the top-level gogaku Rust library, the SwiftUI iOS app, and the Swift bindings that bridge the two over the C ABI. A command-line frontend lives alongside as a workspace peer.

Workspace

Cargo (Rust's package manager) manages a workspace of several crates, specified within its manifest. The iOS app is consumed as an Xcode project under apps/ios/ that depends on the Swift package in bind/swift/, which links the C ABI in lib/gogaku/.

./
├── Cargo.lock           # cargo lockfile
├── Cargo.toml           # cargo manifest
├── LICENSE-APACHE       # apache 2.0 license
├── LICENSE-MIT          # mit license
├── README.md            # this document
├── apps/                # frontend apps
│  ├── cli/              # command-line app
│  ├── ios/              # SwiftUI iOS app
│  └── web/              # browser app
├── bind/                # language bindings
│  ├── swift/            # Swift package
│  └── wasm/             # WebAssembly bindings
├── crates/              # supporting crates
├── data/                # vendored source data
├── lib/                 # foreign function interfaces
│  └── gogaku/           # C ABI
├── sql/                 # database schema
├── src/                 # top-level gogaku library
└── xtask/               # build tasks

Modules

Main components of gogaku are outlined below.

• gogaku: top-level library that manages dictionary data and review state. pack is the container every lookup reads, memory-mapped where there is a filesystem. dict holds the records and the views that read them, one module per upstream source behind those, and dict::pkg, which downloads and builds packs. find is the search engine over them, and base is the study state behind the optional base feature: table holds a module per table, and study runs study sessions over them. deck shares decks (word lists) as files, and makes decks from the charts. Moving a deck in and out of a base needs the base feature, and the rest does not.

Frontends

• gogaku-cli: a command-line interface for dictionary lookup, charts, study, and settings.
• gogaku-ios: a native iOS application built with SwiftUI.
• gogaku-web: a browser application, served as static files.

Bindings

• libgogaku: the C ABI for the Swift bindings.
• GogakuKit: Swift package wrapping that ABI.
• gogaku-wasm: WebAssembly bindings, dictionaries and database.

Supporting

• bfmt: human-readable byte size formatting and parsing.
• rune: visual fingerprints for identifiers.
• tui: terminal screens in an inline viewport.
• tests: scheduling parity, checked against Anki and against the FSRS crate the model was transcribed from.
• xtask: build tasks, run as cargo xtask. cargo xtask pack builds the packs the browser app serves.

Testing

Rust unit tests live alongside each crate's source and run via cargo test --workspace. The browser app's tests run with bun run test from apps/web.

Credits

Gogaku would not be possible without the community dictionaries it depends on. The dictionary files are fetched on-device from upstream. The one exception is the JLPT level list, vendored under data/src and compiled into the library.

• JMdict and JMnedict by the Electronic Dictionary Research and Development Group.
• KANJIDIC2 by the EDRDG.
• RADKFILE and KRADFILE by Jim Breen and the EDRDG.
• JLPT levels by David Gouveia, MIT licensed.
• Tatoeba sentence pairs.

License

This project is dual-licensed under both the MIT License and the Apache License 2.0. You have permission to use this code under the conditions of either license pursuant to the rights granted by the chosen license.