Hayeren
An Eastern Armenian learning studio that connects a graded course, canonical grammar, an inflection-aware dictionary, an inspectable reader, spaced repetition, notebooks, tutoring, and classrooms.01
Three boundaries, one learning system.
Switch between the contracts that keep Armenian language data, reusable product logic, and collaborative writing coherent across the platform.
What the learner saw remains visible.
The surface form is useful evidence; the lemma is the stable identity. Hayeren keeps both instead of making the interface choose between them.
packages/core/src/morphology.tssurface: շուկայումReader · Eastern ArmeniancleanToken → analyzeBest@hayeren/core · locative -ումdictionary_forms → dictionaryhye · reformed · ranked provenance{ word: "շուկա", surface: "շուկայում", kind: "reading" }Append-only by learner and lemma. The source label and source ID keep the meeting attached to where it happened.
- Eastern entries · lexicon-v2
- 188,001
- Eastern forms · lexicon-v2
- 713,312
- Resolution order
- reformed · attested · search rank · frequency
Verified against the maintained architecture documents and implementation for morphology, dictionary resolution, package transport, mobile scope, collaborative notes, and projection reconciliation.
What was missing
Eastern Armenian resources are often useful in isolation—a grammar, a word list, a reader—but learners still have to bridge between them. Hayeren treats those transitions as the product.
What was built
The public web platform includes a CEFR-graded course, canonical grammar, a dictionary where inflected forms resolve to lemmas, a reader where every word can be inspected, spaced repetition, a linked notebook, an AI tutor, and classroom collaboration.
The wider system includes an Expo client, a separate Swift implementation, reusable content and API packages, authored grammar and reading pipelines, lexicon import and validation tooling, and generated pronunciation audio kept in private Vercel Blob storage. The current Expo client deliberately proves the package split through authentication and a 399-word offline dictionary; it does not claim feature parity with the web application.
Technical shape
React and Vite power the web client. Vercel functions connect Neon Postgres and Neon Auth, Liveblocks/Yjs note rooms, OpenAI tutoring and speech, and private generated-audio storage.
The application does not let each client invent its own learning model. @hayeren/core carries morphology, spaced-repetition scheduling, mastery, and permission rules; @hayeren/api-client provides the typed transport boundary. Reviewed Markdown and source data generate the content package, while shared design values generate the token package used across web and native surfaces.
Authentication stays first-party at the browser boundary. /api/auth/* proxies Neon Auth so the session cookie remains first-party; authenticated API calls carry a bearer token verified against Neon Auth JWKS. Durable progress, note projections, comments, memberships, and coursework live in Postgres rather than browser storage. Active shared Y.Doc state lives in Liveblocks, while private generated audio lives in Vercel Blob.
The lexicon retains the relationship between an encountered surface form and its stable lemma. A dictionary_forms mapping can therefore return the same entry—with lect, provenance, normalized senses, frequency, pronunciation, and valency—from the reader, direct dictionary search, review queues, and authoring tools. The maintained lexicon-v2 measurement records 188,001 Eastern entries and 713,312 Eastern inflected forms; those are branch-scoped dataset counts, not usage metrics.
Realtime is deliberately narrower than collaboration. An unshared owner and every read-only visitor render the Neon projection without opening a paid room. When a page is shared and the caller has edit access, api/collab.ts authorizes a Liveblocks room, presence elects one browser to persist the projection, and a ten-minute Vercel Cron reconciles shared rooms back into Neon. The room is the live editing representation; the lossless projection is the durable read and recovery representation.
Guard scripts check content, SQL, package boundaries, CSP, tokens, and component conventions as part of the build.
Product principle
The interface makes Armenian text primary. Explanations appear at the point of need, and the same lexical record supports reading, dictionary lookup, review, authoring, and teaching.
Current work
The active direction joins individual learning and institutional teaching: shared notebooks, classrooms, reusable course content, and a language-data layer that can improve as source coverage grows.
Design and implementation
- Visual decision
- One instrument switches between lexical resolution, package boundaries, and collaborative persistence. Each view exposes a real contract instead of simulating an application dashboard.
- Access decision
- The three architecture modes use an accessible tab pattern with arrow-key navigation. Armenian forms remain real language-labelled text, and every animated route has a complete static reading order.
- Delivery constraint
- The instrument is isolated HTML, CSS, and a small tab controller derived from maintained public architecture records. It requests no account state, room, learning history, or private lexical source.