language-learning-app/frontend/docs/domain.md

# Language Learning - Domain Concpts

Language learning depends on two complementary processes: **exposure** (encountering words in real context) and **retrieval practice** (actively recalling what you have learned). This application uses flashcards as the retrieval primitive — the mechanism by which a word moves from "I have seen this" to "I know this".

Every flashcard in the system is anchored to a **sense**: a specific meaning of a word in the target language. This matters because languages are full of homonyms and polysemes. A learner who adds the French word *banque* to their word bank needs to know they are learning *bank (financial institution)*, not just the string of letters "banque". The sense link is what gives a flashcard its precision and what allows the system to build fluency models at the word-meaning level over time.

**For users**, the manual flashcard creator is the most direct route into the system: type a word, find its meaning in the dictionary, confirm it, and a two-sided card is created — one side prompting recognition (see the French word, recall the English meaning), the other prompting production (see the English meaning, produce the French word). The dictionary integration is what elevates this above a simple note-taking tool: it ties the card to a structured sense record, enabling future features like spaced repetition scheduling, fluency tracking, and cross-card grouping by topic or grammar class.

**For admins**, the WordBankPack CMS is the content pipeline. A pack is a curated, pre-linked set of words — "100 Most Common French Verbs", "Food and Drink Vocabulary" — that users can adopt wholesale into their own word bank. The quality of the sense-linking in a pack directly determines whether a user's flashcards are useful: an entry without a sense link cannot generate flashcards. The admin interface therefore needs dictionary search as a first-class feature, not an afterthought. Flashcard templates attached to pack entries define the *canonical* prompt/answer text for that word, which can be pushed down to users' individual cards as the pack evolves.
docs: [frontend] Add to docs for the frontend package 2026-04-15 20:01:31 +00:00			`# Language Learning - Domain Concpts`

			`Language learning depends on two complementary processes: exposure (encountering words in real context) and retrieval practice (actively recalling what you have learned). This application uses flashcards as the retrieval primitive — the mechanism by which a word moves from "I have seen this" to "I know this".`

			`Every flashcard in the system is anchored to a sense: a specific meaning of a word in the target language. This matters because languages are full of homonyms and polysemes. A learner who adds the French word banque to their word bank needs to know they are learning bank (financial institution), not just the string of letters "banque". The sense link is what gives a flashcard its precision and what allows the system to build fluency models at the word-meaning level over time.`

			For users, the manual flashcard creator is the most direct route into the system: type a word, find its meaning in the dictionary, confirm it, and a two-sided card is created — one side prompting recognition (see the French word, recall the English meaning), the other prompting production (see the English meaning, produce the French word). The dictionary integration is what elevates this above a simple note-taking tool: it ties the card to a structured sense record, enabling future features like spaced repetition scheduling, fluency tracking, and cross-card grouping by topic or grammar class.

			For admins, the WordBankPack CMS is the content pipeline. A pack is a curated, pre-linked set of words — "100 Most Common French Verbs", "Food and Drink Vocabulary" — that users can adopt wholesale into their own word bank. The quality of the sense-linking in a pack directly determines whether a user's flashcards are useful: an entry without a sense link cannot generate flashcards. The admin interface therefore needs dictionary search as a first-class feature, not an afterthought. Flashcard templates attached to pack entries define the canonical prompt/answer text for that word, which can be pushed down to users' individual cards as the pack evolves.