mdanielseo/soma

Offline-first decodable literacy toolkit for African languages: spec, CLI, reader PWA, and Swahili starter packs. # Soma **Offline-first decodable literacy toolkit for African languages.** Soma (Kiswahili for "read") is an open-source toolkit that turns structured phonics lessons into a single HTML file that teaches children to read, fully offline, on the devices families actually have: low-end Android phones, school tablets, SD cards, and USB sticks. ## Why this exists - In sub-Saharan Africa, roughly **9 in 10 children cannot read and understand a simple text by age 10** (World Bank learning poverty estimate, 2024-2025). - African languages written in Latin script have largely **transparent orthographies** (regular letter-sound mappings), which makes systematic phonics the evidence-based route to early reading - yet nearly all open-source phonics tooling is English-only and assumes an internet connection. - Content authoring and distribution for local languages is manual, offline-hostile, and non-portable. Soma provides a small standard for that. See RESEARCH.md for the evidence base with sources and docs/DESIGN.md for the benchmarked reader design decisions. ## What is in this repo | Package | What it does | | --- | --- | | `packages/soma-core` | Zero-dependency JavaScript library: orthography profiles (sw, en, zul, nya), syllabification, decodable word generation, decodability checking, pack validation, difficulty analysis | | `packages/soma-cli` | Zero-dependency Node.js CLI: `init`, `validate`, `build`, `stats`, `serve` | | `packages/soma-reader` | The offline reader: a single-file web app that runs from `file://`, an SD card, or any static host, with a service worker for offline use | | `packs/sw-grade1` | Starter pack: Kiswahili Grade 1 phonics, 12 lessons (real, curated content) | | `packs/en-grade1` | Starter pack: English Grade 1 synthetic phonics, 12 lessons (satpin sequence) | | `packs/zul-draft1` | Draft isiZulu starter, 5 lessons (awaiting native-speaker review) | | `packs/nya-draft1` | Draft Chinyanja (Chichewa) starter, 5 lessons (awaiting native-speak …