language-learning-app/api/docs/design-doc-flashcard.md

# Design Doc: Flashcards

This is a technical design document for the Flashcard in the context of Language Learning App.

You may wish to read both [architecture.md](./architecture.md) and [domain](./domain.md) for an understanding of the components of this API codebase and the wider problem domain, respectively. 

## The Problem

Flashcards, in the physical world, are a common learning aid.  They are a  two-sided piece of paper with information on both sides.  The learner will view one side, and attempt to recall what is on the other.  They are a tool to improve a learner's ability to recall specific information (e.g. specific words), and therefore a tool to increase fluency.

Language Learning App relies on recognition and recall to improve learner fluency in a language.  To do so, learners must be presented with some kind of cue for which they must generate some kind of response.  It is important that we don't rely on learner's perceived fluency (e.g. present them with a a cue, then show them the response and ask them how right/confident they were in retrospect), because language learners will consistently over-estimate their fluency.

Providing opportunity for "meaning-focused input" (as researcher Paul Nation called it in their *Four Strands*) is one of the main focuses of Language Learning App.  That is - providing realistic text to read and listen to, and have them engage in the sustained act of making sense from it.

Flashcards are not meaning-focused input, because of how isolated they are.  Their benefit is in helping learners gain familiarity in isolated parts of language, e.g. specific words.  This comes in two flavours: recognition and generation.  Recognition of words can be seen, broadly, as "I see the word 'chat', I know that means 'cat'".  Generation is about producing the word for "cat" when it is needed. 

Pedagogically, Flashcards allow us to model the recognition and generation stepss at an artifically granular level: a single word looking for a single translation.  E.g. showing a French learner "banque" and expecting them to generate "bank".

This is the central problem that Flashcards solve: helping learners become familiar, and able to recall/generate specific language items (e.g. words).  This can include:

* a foreign language word they wish to become familiar with, 
* the conjugations of a specific verb

However there are numerous concerns, or limitations, with the simple idea of a two-sided piece of paper.  The first is that, philosophically, language learning is not about a one-to-one translation between words.  The second is that homonyms (i.e. the same literal words) can have multiple possible meanings or translations.  

Because langauge is not a one-to-one translation activity, we must accept that there are multiple possible correct (or semi-correct) answers to a single cue.  For example a single cue (e.g. "cold") may have multiple synonyms, e.g. "cold" or "chilly".  One of these responses might be the ideal target, but another would have the learner convey their meaning. 

From a product positioning perspective, Language Learning App wishes to be more than "just" a flashcard app, (e.g. anki).  Firstly because Anki is an exceptitonal tool that already exists, but also because its central philosophy of teaching and language learning is that it is more valuable to learn a language through exposure to longer-form content than *just* a single word on a flashcard.  Specifically it centres written articles and audio podcasts (both AI-generated) - and having the learner identify words from that content that they wish to retain or be familiar with.

This becomes apparent as Flashcards progress from being simple "cue" and "response" to having contextual text (i.e. natural language sentences) with gaps in them,

## Not in scope

There are a number of problems not in scope in the Flashcard model. 

The biggest category fall around the system that we will need to build to present users with words in an algorithmic, effective way that enhances learning.  We should bear these requirements in mind, but they are out of scope in the initial design of a Flashcard.

There will need to be a system which grades "familiarity" or "fluency" against a specific Flashcard, or against a specific wordbank item/sense (and also lemma).  

There will also need to be a system of "events" which records when a learner was last shown a specific flashcard, what they responded to it, and how correct their response was.

## Example Flashcards

The following examples all assume the learner is an English speaker learning French.

A simple one-way Flashcard would look like:

```txt
Cue: être
Answers: [to be, be]
```

In the above, the learner can respond "be" or "to be" and be considered correct.

Consider a simple two-way Flashcard, would look like:

```txt
Cue: to have (v. inf.)
Answer: [avoir]
---
Cue: avoir
Answer: [to have, have]
```

A flashcard with "contextual text" may look like the following:

```txt
Contextual text: Il souhaite d'_____ un chat
Cue: (He wishes [to have] a cat, He wises to have a cat)
Answer: [avoir]
```

Notice in the above that there are two forms of cue: one which [highlights] the word fill in, and one which does not.  This should be a configurable property, and the presentation of it should run both ways.

Let's consider a Flashcard with contextual text where there are multiple words to fill:

```txt
Contextual text: Il _______ _'_____ un chat
Cue: (He [wishes] [to have] a cat)
Answers: [[souhaite], [d], [avoir]]
```

And let's consider a Flashcard that encourages the learner to "guess" from context a word:

```txt
Contextual text: Il [souhaite] d'avoir un chat
Answers: [wishes]
```

In the above, the learning activity is having a learner "guess" a word, from context, which they may not have previously seen before.  Such activities focus on meaning-making from language.

## Requirements 

* Both the cue and the response(s) for a Flashcard need to be linked, in some way, to their underlying wordbank entries.  
  * There can be multiple Flashcards against the same wordbank entry and sense (e.g. "cat <-> chat"), and Flashcards against the same lemma (e.g. "lent,lente <-> slow").
  * There should be special attention paid to the modelling of verb conjugations.  Flashcards where the response is a verb's conjugation (e.g. 3rd person present tense of être) should be modelled as such
* It should be possible for Flashcards to go both one-way (e.g. En -> Fr) and two ways (e.g. En <-> Fr).  
* There needs to be many options for "grading" a response to a flashcard.  This may come from language be configured by the learner specifically (e.g. they may) flashcards needs to be considered (right/wrong), categorical (fully correct/), or some degree of percentage-ly correct (e.g. 75% word similarity).  
* Audible components (likely AI-generated text-to-speech) for both contextual text _and_ foreign language answers are an essential component.  There are a variety of scenarios these could play.  There could be Flashcards which are _just_ audio, or we could play the audio of the correct answer after the learner has answered, so that they know how the word sounds out loud.
* There needs to be a good interface for making Flashcards.  They can be made in a stand-alone "studio" (i.e. a CMS like interface) where they are constructed, but also they can be taken from the natural language content (e.g. articles) within Language Learning App.  This latter would allow us to extract the contextual text of the original sentence
  * For admins, there should be a more powerful Flashcard Studio which uses generative AI to suggest contextual texts and examples for words, so that the Admin user can specify the wordform (and find the right sense) and then have a pre-populated list of possible Flashcards with contextual texts.
  *