Skip to content

Lemma Editor Data Flow (Canonical)

Overview

This document defines the canonical data flow for the Lemma Editor across UI, API, and database layers.

The flow is constrained by the System Contract and schema snapshots. The editor operates as a multi-section orchestration layer, not as a flat CRUD screen.

Runtime flow

  1. LemmaEditorPage resolves lemma context (existing :id in edit mode).
  2. LemmaEditorProvider loads initial data required for all tabs:
  3. lemma detail
  4. editor metadata (taxonomy options and section config)
  5. section-specific datasets (senses, sentences, relations, translations, audio)
  6. LemmaEditorLayout renders shared shell and tab container.
  7. Each tab component performs focused mutations via dedicated endpoints.
  8. Save operations refresh server state and rehydrate provider state.

Read flow (edit mode)

Initial hydrate

  • GET /admin/content-bank/lemmas/:id
  • returns core lemma payload + aggregated editor payload
  • GET /admin/content-bank/lemmas/editor-metadata
  • returns taxonomy options by category + editor section metadata

Section reads

  • Senses: GET /admin/content-bank/lemmas/:id/senses
  • Sentences: GET /admin/content-bank/lemmas/:id/sentences
  • Relations: GET /admin/content-bank/lemmas/:id/relations
  • Translations: GET /admin/content-bank/lemmas/:id/translations
  • Pronunciation/TTS: GET /admin/content-bank/lemmas/:id/audio

Write flow by section

Core + Taxonomies (atomic save path)

  • POST /admin/content-bank/lemmas/:id/editor-save
  • Updates lemmas core fields.
  • Replaces taxonomy assignments via content_item_taxonomies (driven by IDs from taxonomy_values).

Senses

  • Create: POST /admin/content-bank/lemmas/:id/senses → senses
  • Update: PATCH /admin/content-bank/lemmas/:id/senses/:senseId → senses
  • Delete: DELETE /admin/content-bank/lemmas/:id/senses/:senseId → senses

Sentences

  • List: GET /admin/content-bank/lemmas/:id/sentences
  • Create example: POST /admin/content-bank/lemmas/:id/examples → sentences + sentence_lemmas
  • Delete example: DELETE /admin/content-bank/lemmas/:id/examples/:sentenceId → detaches lemma-sentence usage and/or removes sentence row according to controller policy

Semantic Relations

  • List: GET /admin/content-bank/lemmas/:id/relations
  • Create relation: POST /admin/content-bank/lemmas/:id/collocations → lexical_relations
  • Delete relation: DELETE /admin/content-bank/lemmas/:id/collocations/:relationId → lexical_relations

Translations

  • List translations: GET /admin/content-bank/lemmas/:id/translations → translations

Pronunciation / TTS

  • List pronunciation/audio assets: GET /admin/content-bank/lemmas/:id/audio → lemma_pronunciations + tts_assets

Canonical table mapping reference

  • Core → lemmas
  • Taxonomies → taxonomy_categories, taxonomy_values (with content_item_taxonomies linkage)
  • Morphology → lemma_forms
  • Senses → senses
  • Translations → translations
  • Sentences → sentences, sentence_lemmas
  • Semantic Relations → lexical_relations
  • Pronunciation/TTS → lemma_pronunciations, tts_assets
  • Chunks → chunk_components

Guardrails

  • Preserve tab-isolated flows; do not merge all writes into opaque full-document replacement.
  • Preserve explicit table boundaries above.
  • Preserve atomic save endpoint semantics for core + taxonomy updates.
  • Do not redesign the editor as a single-form CRUD replacement.