Unified Morphology Architecture & Data Standard1. System OverviewThe app uses a Declarative, Config-Driven Architecture to parse and display grammatical forms (morphology). Instead of writing language-specific code (e.g., GermanNounParser, FrenchVerbParser), the system uses a single generic engine driven by JSON configuration.The Engine (Kotlin): UnifiedMorphologyParser knows how to build data structures (Grids, Lists, Verb Paradigms) but not what to build.The Blueprint (JSON Config): Language files (e.g., fr.json, de.json) define the dimensions (Rows/Columns for grids, Tenses for verbs).The Data (Dictionary JSON): The raw word forms tagged with grammatical features.2. Configuration Standard (LanguageConfig)The configuration file defines the "rules" for the parser. It tells the engine which strategy to use for a given Part of Speech (POS).A. The Grid Strategy (Nouns & Adjectives)Used for any 2D data structure (Case × Number, Gender × Number).Requirement: The category object MUST contain declension_display.Example (fr.json - Adjectives):"adjective": {
"declension_display": {
"cases_order": ["masculine", "feminine"],  // <--- Defined ROWS
"numbers_order": ["singular", "plural"]    // <--- Defined COLUMNS
}
}
Note: The keys cases_order and numbers_order are generic. For adjectives, they conceptually represent "Genders" and "Numbers".B. The Verb Strategy (Conjugations)Used for verb paradigms.Requirement: The category object MUST contain conjugation_display.Example (de.json - Verbs):"verb": {
"conjugation_display": {
"pronouns": ["ich", "du", "er/sie/es", "wir", "ihr", "sie"], // Required for mapping ordered forms
"tense_labels": {
"present": "Präsens",       // Internal Tag -> Display Label
"past": "Präteritum",
"subjunctive_i": "Konjunktiv I"
}
}
}
3. Data Input Standard (DictionaryEntryData)The dictionary entry provides the raw forms. The parser supports two input formats.Format A: The Standard List (Recommended)A flat list of objects. Each object contains the form string and a list of tags.Constraint: The tags values MUST match the keys defined in the Configuration (e.g., "masculine", "present")."forms": [
   { "form": "beau", "tags": ["masculine", "singular"] },
   { "form": "belle", "tags": ["feminine", "singular"] },
   { "form": "beaux", "tags": ["masculine", "plural"] },
   { "form": "belles", "tags": ["feminine", "plural"] }
   ]
   Format B: The Structured Object (Legacy/German Verbs)Some entries group forms by tense keys instead of tags.Parser Behavior: The DictionaryJsonParser detects this object and flattens it into Format A automatically.Mapping: Keys like present become tags. Arrays are preserved in order.// Input (Dictionary JSON)
   "forms": {
   "present": ["laufe", "läufst", "läuft", "laufen", "lauft", "laufen"],
   "auxiliary": "sein"
   }

// Internal Representation after Flattening:
// [
//   { "form": "laufe", "tags": ["present"] },
//   { "form": "läufst", "tags": ["present"] },
//   ...
//   { "form": "sein", "tags": ["auxiliary"] }
// ]
4. The Parsing AlgorithmThe UnifiedMorphologyParser follows this specific decision tree:Step 1: NormalizationInputs: Lemma (e.g., "beau"), POS (e.g., "adj"), Config.Normalize POS: Maps short tags to standard keys:adj, adjectif -> adjectivenom, substantive -> nounverbe -> verbAbort: If forms list is empty.Step 2: Rule SelectionCheck JSON Config: Does config.categories[pos] exist?Yes: Does it have declension_display? -> Build Grid Rule.Yes: Does it have conjugation_display? -> Build Verb Rule.Fallback: If JSON config is missing, check MorphologyRegistry.kt for a hardcoded default rule (e.g., generic fallback).Step 3: Execution (Grid Strategy)Applies to Nouns and Adjectives.Index Forms: Creates a fast lookup map: Set<Tags> -> Form.Iterate: Loops through row_tags (from Config) × col_tags (from Config).Match: For cell [row, col], looks for a form containing BOTH tags.Example: Looking for form with tags ["masculine", "plural"].Fallback (The Lemma Rule): If a match is not found:Adjective Special Case: If the cell being built is masculine + singular, the parser defaults to using the Lemma (Headword). This handles dictionary data that omits the base form.Output: Returns UnifiedMorphology.Grid (Rendered as a table).Step 4: Execution (Verb Strategy)Applies to Verbs.Iterate: Loops through tense_labels keys (from Config).Filter: Finds all forms tagged with that tense key (e.g., "present").Truncate: Takes the first $N$ forms, where $N$ is the length of the pronouns list in Config.Auxiliary: Scans for a form tagged auxiliary.Output: Returns UnifiedMorphology.Verb (Rendered as conjugation lists).5. Validating Your JSONTo ensure your JSON renders correctly in the UI, check these constraints:ComponentConstraintWhy?Configcases_order must be non-null for Nouns/Adjectives.Without row definitions, the grid cannot be built.Configtense_labels keys must match Dictionary tags."present" in config must match "present" tag in data.DataTags must be lowercase in forms.The parser normalizes tags to lowercase, but consistency prevents bugs.DataVerb arrays must be ordered by person (1st->3rd).The parser maps forms to pronouns by index position (0=I, 1=You, etc.).Example: A Valid Adjective Setuppt.json (Config):"adjective": {
   "declension_display": {
   "cases_order": ["masculine", "feminine"],
   "numbers_order": ["singular", "plural"]
   }
   }
   Dictionary Entry (Data):"word": "lindo",
   "forms": [
   // Note: "lindo" (masc/sing) is MISSING here.
   // The Parser will automatically insert the word "lindo" into the [masculine, singular] cell.
   { "form": "linda", "tags": ["feminine", "singular"] },
   { "form": "lindos", "tags": ["masculine", "plural"] },
   { "form": "lindas", "tags": ["feminine", "plural"] }
   ]
   Resulting UI:| | Singular | Plural || :--- | :--- | :--- || Masculine | lindo (Lemma) | lindos || Feminine | linda | lindas |