language-learning-app/api/frontend-todo.md

Frontend TODO

---

Screen 1 — User: Manual Flashcard Creator

Route: /flashcards/new (and /flashcards/:id/edit for editing)

Purpose: Allow a user to create a flashcard for a word they want to learn, with optional dictionary linking to anchor it to a specific sense.

Layout

A single-page form divided into two sections:

Section A — Word lookup

• Text input: "Word or phrase" (surface_text). As the user types (debounced ~400ms), call GET /api/dictionary/wordforms?lang_code={target_lang}&text={input} and display results inline.
• Dictionary search results display as a list of candidate cards. Each card shows:
  • Lemma headword (bold), POS label (e.g. "verb", "noun"), gender if present (e.g. "m." / "f.")
  • Indented list of senses, each showing: sense index, gloss (= English translation), topics/tags as small chips
• User clicks a sense to select it. Selected state: the sense is highlighted, the sense id is stored, and Section B is pre-populated.
• If no results are found, show a "No dictionary match — you can still create a card manually" message. The form remains usable without a sense link.
• "Clear" button to deselect and start over.

Section B — Card content

Four text inputs, pre-populated from the selected sense but always editable:

Field	Pre-populated from	Label shown to user
prompt_text	lemma.headword (if sense selected, else blank)	Prompt (target language)
answer_text	sense.gloss (if sense selected, else blank)	Answer (English)
prompt_context_text	blank	Context for prompt (optional)
answer_context_text	blank	Context for answer (optional)

Card direction selector: two toggle options — Recognition (target → English) and Production (English → target). Defaults to both selected (generates two cards). User can deselect one.

Save action:

1. POST /api/vocab with { surface_text, language_pair_id, entry_pathway: "manual" } → returns a WordBankEntry with a bank_entry_id and disambiguation_status.
2. If a sense was selected and disambiguation_status != "auto_resolved": PATCH /api/vocab/{entry_id}/sense with { sense_id }.
3. POST /api/vocab/{entry_id}/flashcards with { direction } for each selected direction.
4. On success: navigate to the flashcard list or show a confirmation with a "Study now" shortcut.

Edit mode (/flashcards/:id/edit):

• Pre-populate all fields from the existing flashcard record.
• Sense search is pre-filled with the existing surface_text and the linked sense highlighted (if present).
• Save updates the flashcard. (Note: a PATCH /api/flashcards/:id endpoint does not yet exist — this needs to be added to the API.)

State notes

• language_pair_id must be known before this screen renders. Resolve it from the user's active language pair (stored in app state / from GET /api/learnable-languages).
• A user may have no dictionary match but still create a valid card manually. Do not block submission if the sense search returns nothing.

---

Screen 2 — Admin: WordBankPack List

Route: /admin/packs

Auth: Admin token required. All calls go to /api/admin/packs/*.

Purpose: Entry point to the pack CMS. Shows all packs (published and draft) and allows creation of new ones.

Layout

• Page header: "Word Packs" + "New Pack" button (opens Screen 3).
• Table with columns: Name (source lang), Name (target lang), Language pair, Proficiencies, Entries, Status (Published / Draft), Actions (Edit, Publish).
• "Publish" action: POST /api/admin/packs/{id}/publish. Disabled if pack is already published. Show a confirmation modal before calling — publishing is not reversible via the API.
• Row click → navigate to Screen 3 (edit mode).

Fetch: GET /api/admin/packs?source_lang={}&target_lang={} (filter controls optional).

---

Screen 3 — Admin: WordBankPack Detail / Editor

Route: /admin/packs/new and /admin/packs/:id

Purpose: Create or edit a pack, manage its entries, and add flashcard templates to each entry.

Layout

Three vertical sections on the same page:

---

Section A — Pack metadata

Fields mapping directly to CreatePackRequest / UpdatePackRequest:

Field	Input type	Notes
name	text	Pack name in source language (English)
name_target	text	Pack name in target language (e.g. French)
description	textarea	Description in source language
description_target	textarea	Description in target language
source_lang	select (ISO 639-1)	Disabled after creation
target_lang	select (ISO 639-1)	Disabled after creation
proficiencies	multi-select	CEFR values: A1, A2, B1, B2, C1, C2

Save: POST /api/admin/packs (new) or PATCH /api/admin/packs/{id} (edit). After creation, the page transitions to edit mode with the new pack ID in the URL.

---

Section B — Pack entries

A table/list of the pack's word entries. Each row expands to show flashcard templates (Screen 3B).

Adding an entry:

Inline form above the list (always visible):

• Text input: "Word or phrase" (surface_text). As the user types, call GET /api/dictionary/wordforms?lang_code={target_lang}&text={input} and display results in a dropdown.
• Dropdown shows: headword + POS + gender + each sense's gloss. User selects a specific sense.
• Selected state shows a summary pill: e.g. "aller (verb) — to go". Clear button to deselect.
• "Add entry" button → POST /api/admin/packs/{id}/entries with { surface_text, sense_id }.
  • sense_id is included if a sense was selected; omitted otherwise (entry is created without a sense link — this is valid but means no flashcards can be generated from it until a sense is linked).

Entry row (collapsed):

• Surface text (bold)
• Sense gloss if linked, or a "⚠ No sense linked" warning badge
• Template count (e.g. "2 templates")
• Delete button → DELETE /api/admin/packs/{id}/entries/{entry_id} with confirmation.
• Expand toggle.

Entry row (expanded) — Section 3B:

Shows the flashcard template sub-list for this entry. See Section C below.

---

Section C — Flashcard templates (per entry)

Rendered inside the expanded entry row.

A flashcard template defines the canonical prompt/answer for this word when a user adopts the pack. Fields map to AddFlashcardTemplateRequest:

Field	Input type	Notes
card_direction	select	target_to_source (Recognition) / source_to_target (Production)
prompt_text	text	Pre-populated from sense: headword for target_to_source, gloss for source_to_target
answer_text	text	Opposite of prompt
prompt_context_text	text	Optional — example sentence or grammatical cue
answer_context_text	text	Optional — corresponding target-language context

"Add template" button → POST /api/admin/packs/{id}/entries/{entry_id}/flashcards.

Existing templates are listed below the form, each showing all four fields read-only, with a delete button → DELETE /api/admin/packs/{id}/entries/{entry_id}/flashcards/{template_id}.

(Note: there is no PATCH endpoint for templates — delete and re-create to edit.)

Pre-population hint for admins: When a sense is linked to the entry, the "Add template" form should auto-fill prompt_text and answer_text based on the selected card_direction:

• target_to_source: prompt = lemma.headword, answer = sense.gloss
• source_to_target: prompt = sense.gloss, answer = lemma.headword

These are editable before submitting.

---

API reference summary

Endpoint	Used by
GET /api/dictionary/wordforms?lang_code=&text=	Screen 1 (live search), Screen 3 (entry add)
POST /api/vocab	Screen 1 (save)
PATCH /api/vocab/{id}/sense	Screen 1 (save, when sense selected)
POST /api/vocab/{id}/flashcards	Screen 1 (save)
GET /api/admin/packs	Screen 2
POST /api/admin/packs	Screen 3 (new pack)
GET /api/admin/packs/{id}	Screen 3 (edit pack)
PATCH /api/admin/packs/{id}	Screen 3 (update metadata)
POST /api/admin/packs/{id}/publish	Screen 2
POST /api/admin/packs/{id}/entries	Screen 3 (add entry)
DELETE /api/admin/packs/{id}/entries/{entry_id}	Screen 3 (remove entry)
POST /api/admin/packs/{id}/entries/{entry_id}/flashcards	Screen 3 (add template)
DELETE /api/admin/packs/{id}/entries/{entry_id}/flashcards/{template_id}	Screen 3 (remove template)

API gaps (need to be added before frontend is complete)

• PATCH /api/flashcards/{id} — update prompt/answer/context text on an existing user flashcard (needed for Screen 1 edit mode)
• GET /api/flashcards/{id} — fetch a single flashcard by ID (needed to pre-populate Screen 1 edit mode)
• GET /api/dictionary/lemmas?lang_code=&headword= or similar — a headword-level search returning all senses for a lemma directly, useful as a fallback when the wordform search returns no results but the user typed a known headword