# goblindegook/musarrif architecture

> Architecture diagram of the GitHub repository goblindegook/musarrif, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/goblindegook/musarrif
- Repository: https://github.com/goblindegook/musarrif

## Overview

#### Purpose and runtime entry points
Muṣarrif is an offline-capable Arabic verb conjugator and recognition-drill PWA, with a Tauri 2 desktop wrapper. The browser UI starts at `src/ui/main.tsx`, composes application routing/state in `src/ui/app.tsx`, and is built from `index.html` through Vite. Desktop startup is Rust/Tauri at `src-tauri/src/main.rs`, configured by `src-tauri/tauri.conf.json`.

#### Lexicon and localization boundary
The curated lexical source is `src/data/roots.json`: roots, verb forms, vowel patterns, voice/nominal support, and related metadata. Human-facing root and verb labels are separate locale datasets in `src/ui/locales/en.verbs.json`, `src/ui/locales/it.verbs.json`, and `src/ui/locales/pt.verbs.json`. This separation lets deterministic grammar operate on transliterated lexical metadata while the UI renders localized text.

#### Conjugation engine
Pure TypeScript paradigm modules transform a selected root/verb plus grammatical dimensions into conjugated Arabic forms and explanatory annotations. Key orchestration and domain boundaries are `src/paradigms/conjugation.ts`, `src/paradigms/verbs.ts`, and `src/paradigms/roots.ts`; tense/voice implementations are partitioned under `src/paradigms/active/`, `src/paradigms/passive/`, and `src/paradigms/nominal/`. Search resolves user input into roots and verbs through `src/paradigms/search.ts`.

#### Reference-mode flow
Users navigate to lookup/conjugation views through `src/ui/routes.ts` and `src/ui/pages/ConjugationMode.tsx`. `src/ui/organisms/ConjugateBox.tsx` collects search and grammatical selections, invokes the paradigm/search layer, and presents output via `src/ui/organisms/ConjugationTable.tsx` plus insight panels. The UI is therefore a consumer of grammar-domain results, rather than embedding morphology rules.

#### Exercise and SRS flow
Exercise mode is coordinated in `src/ui/pages/ExerciseMode.tsx`. `src/exercises/exercises.ts` selects exercise types; focused generators in `src/exercises/generators/` create prompts, answers, and distractors from paradigm data. Answer outcomes feed scheduling and progress logic in `src/exercises/srs.ts`, `src/exercises/scheduler.ts`, and `src/exercises/mastery.ts`. This isolates learning policy from both UI rendering and conjugation rules.

#### Client persistence and device capabilities
Browser-facing hooks maintain local user state—SRS data, settings/dimensions, favorites, recents, and stats—behind `src/ui/hooks/useSrsStore.ts`, `src/ui/hooks/useDimensionStore.ts`, and `src/ui/user-data.ts`. Speech and speech recognition are optional browser capabilities via `src/ui/hooks/useSpeech.ts` and `src/ui/hooks/useSpeechRecognition.ts`. Optical transfer components (`src/ui/organisms/OpticalSend.tsx`, `src/ui/organisms/OpticalReceive.tsx`) support local data exchange without a backend.

#### External systems and maintenance pipeline
The deployed web target is a static Vite PWA; no application server or database is represented. Tauri supplies the desktop host. Node/TypeScript scripts maintain lexicon and validate external references: `scripts/verb.mts` edits lexical/localization data, while `scripts/lib/elixirfm.mts`, `scripts/lib/reverso.mts`, and `scripts/lib/wiktionary.mts` fetch external conjugation sources to generate regression expectations. CI is defined in `.github/workflows/ci.yml`.

Main entry points: [`src/paradigms/conjugation.ts`](https://github.com/goblindegook/musarrif/blob/main/src/paradigms/conjugation.ts) (Conjugation orchestration), [`src/ui/pages/ExerciseMode.tsx`](https://github.com/goblindegook/musarrif/blob/main/src/ui/pages/ExerciseMode.tsx) (Exercise mode), [`src/ui/app.tsx`](https://github.com/goblindegook/musarrif/blob/main/src/ui/app.tsx) (Application shell), [`src/ui/routes.ts`](https://github.com/goblindegook/musarrif/blob/main/src/ui/routes.ts) (Routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Browser UI"]
  node_vite{{"Vite PWA build<br/>build entry<br/>[index.html]"}}
  node_ui_main["UI entry<br/>React entry<br/>[main.tsx]"]
  node_app["Application shell<br/>React composition<br/>[app.tsx]"]
  node_routes["Routes<br/>UI routing<br/>[routes.ts]"]
  node_reference_mode["Reference mode<br/>lookup page"]
  node_conjugate_box["Conjugation controls<br/>UI organism<br/>[ConjugateBox.tsx]"]
  node_conjugation_table["Conjugation output<br/>UI organism"]
  node_user_state[("Local user state<br/>browser persistence<br/>[user-data.ts]")]
end

subgraph group_grammar["Grammar domain"]
  node_grammar_orchestration["Conjugation orchestration<br/>grammar API<br/>[conjugation.ts]"]
  node_verb_root_domain["Verb and root domain<br/>lexical model<br/>[verbs.ts]"]
  node_paradigm_implementations["Tense and voice paradigms<br/>morphology implementations"]
  node_search["Lexicon search<br/>search resolver<br/>[search.ts]"]
end

subgraph group_learning["Exercises &amp; SRS"]
  node_exercise_mode["Exercise mode<br/>practice page<br/>[ExerciseMode.tsx]"]
  node_exercise_generation["Exercise generation<br/>prompt generators"]
  node_exercise_selection["Exercise selection<br/>exercise coordinator<br/>[exercises.ts]"]
  node_srs_policy["SRS &amp; mastery<br/>learning policy<br/>[srs.ts]"]
end

subgraph group_data["Lexicon &amp; locales"]
  node_roots_data[("Curated roots lexicon<br/>lexical dataset<br/>[roots.json]")]
  node_localized_labels["Localized verb labels<br/>locale datasets<br/>[en.verbs.json]"]
end

subgraph group_delivery["Desktop &amp; maintenance"]
  node_tauri_host{{"Tauri desktop host<br/>Rust desktop runtime<br/>[main.rs]"}}
  node_lexicon_maintenance["Lexicon maintenance<br/>Node/TypeScript scripts<br/>[verb.mts]"]
  node_ci["CI<br/>GitHub Actions workflow<br/>[ci.yml]"]
end

node_vite -->|"loads"| node_ui_main
node_ui_main -->|"mounts"| node_app
node_app -->|"uses"| node_routes
node_routes -->|"navigates to"| node_reference_mode
node_routes -->|"navigates to"| node_exercise_mode
node_reference_mode -->|"contains"| node_conjugate_box
node_conjugate_box -->|"resolves input"| node_search
node_conjugate_box -->|"requests forms"| node_grammar_orchestration
node_grammar_orchestration -->|"returns results to"| node_conjugation_table
node_search -->|"queries"| node_verb_root_domain
node_grammar_orchestration -->|"uses"| node_verb_root_domain
node_grammar_orchestration -->|"dispatches to"| node_paradigm_implementations
node_verb_root_domain -->|"reads"| node_roots_data
node_app -->|"renders"| node_localized_labels
node_exercise_mode -->|"coordinates"| node_exercise_selection
node_exercise_selection -->|"selects"| node_exercise_generation
node_exercise_generation -->|"derives answers from"| node_grammar_orchestration
node_exercise_mode -->|"records outcomes"| node_srs_policy
node_srs_policy -->|"persists progress"| node_user_state
node_exercise_mode -->|"reads learner state"| node_user_state
node_tauri_host -->|"hosts built UI"| node_vite
node_lexicon_maintenance -->|"edits and validates"| node_roots_data
node_lexicon_maintenance -->|"edits"| node_localized_labels
node_ci -->|"runs validation"| node_lexicon_maintenance

click node_vite "https://github.com/goblindegook/musarrif/blob/main/index.html"
click node_ui_main "https://github.com/goblindegook/musarrif/blob/main/src/ui/main.tsx"
click node_app "https://github.com/goblindegook/musarrif/blob/main/src/ui/app.tsx"
click node_routes "https://github.com/goblindegook/musarrif/blob/main/src/ui/routes.ts"
click node_reference_mode "https://github.com/goblindegook/musarrif/blob/main/src/ui/pages/ConjugationMode.tsx"
click node_conjugate_box "https://github.com/goblindegook/musarrif/blob/main/src/ui/organisms/ConjugateBox.tsx"
click node_conjugation_table "https://github.com/goblindegook/musarrif/blob/main/src/ui/organisms/ConjugationTable.tsx"
click node_exercise_mode "https://github.com/goblindegook/musarrif/blob/main/src/ui/pages/ExerciseMode.tsx"
click node_exercise_selection "https://github.com/goblindegook/musarrif/blob/main/src/exercises/exercises.ts"
click node_srs_policy "https://github.com/goblindegook/musarrif/blob/main/src/exercises/srs.ts"
click node_user_state "https://github.com/goblindegook/musarrif/blob/main/src/ui/user-data.ts"
click node_grammar_orchestration "https://github.com/goblindegook/musarrif/blob/main/src/paradigms/conjugation.ts"
click node_verb_root_domain "https://github.com/goblindegook/musarrif/blob/main/src/paradigms/verbs.ts"
click node_search "https://github.com/goblindegook/musarrif/blob/main/src/paradigms/search.ts"
click node_roots_data "https://github.com/goblindegook/musarrif/blob/main/src/data/roots.json"
click node_localized_labels "https://github.com/goblindegook/musarrif/blob/main/src/ui/locales/en.verbs.json"
click node_tauri_host "https://github.com/goblindegook/musarrif/blob/main/src-tauri/src/main.rs"
click node_lexicon_maintenance "https://github.com/goblindegook/musarrif/blob/main/scripts/verb.mts"
click node_ci "https://github.com/goblindegook/musarrif/blob/main/.github/workflows/ci.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_vite,node_ui_main,node_app,node_routes,node_reference_mode,node_conjugate_box,node_conjugation_table,node_user_state toneBlue
class node_grammar_orchestration,node_verb_root_domain,node_paradigm_implementations,node_search toneAmber
class node_exercise_mode,node_exercise_generation,node_exercise_selection,node_srs_policy toneMint
class node_roots_data,node_localized_labels toneRose
class node_tauri_host,node_lexicon_maintenance,node_ci toneIndigo
```

## Components

### Browser UI

- [Vite PWA build](https://github.com/goblindegook/musarrif/blob/main/index.html): build entry · Builds the browser application from the HTML entry point. · `index.html`
- [UI entry](https://github.com/goblindegook/musarrif/blob/main/src/ui/main.tsx): React entry · `src/ui/main.tsx`
- [Application shell](https://github.com/goblindegook/musarrif/blob/main/src/ui/app.tsx): React composition · `src/ui/app.tsx`
- [Routes](https://github.com/goblindegook/musarrif/blob/main/src/ui/routes.ts): UI routing · `src/ui/routes.ts`
- [Reference mode](https://github.com/goblindegook/musarrif/blob/main/src/ui/pages/ConjugationMode.tsx): lookup page · `src/ui/pages/ConjugationMode.tsx`
- [Conjugation controls](https://github.com/goblindegook/musarrif/blob/main/src/ui/organisms/ConjugateBox.tsx): UI organism · Collects lookup and grammatical selections. · `src/ui/organisms/ConjugateBox.tsx`
- [Conjugation output](https://github.com/goblindegook/musarrif/blob/main/src/ui/organisms/ConjugationTable.tsx): UI organism · `src/ui/organisms/ConjugationTable.tsx`
- [Local user state](https://github.com/goblindegook/musarrif/blob/main/src/ui/user-data.ts): browser persistence · Stores SRS, dimensions, favorites, recents, and stats locally. · `src/ui/user-data.ts`

### Grammar domain

- [Conjugation orchestration](https://github.com/goblindegook/musarrif/blob/main/src/paradigms/conjugation.ts): grammar API · Computes forms and explanatory annotations from lexical and grammatical input. · `src/paradigms/conjugation.ts`
- [Verb and root domain](https://github.com/goblindegook/musarrif/blob/main/src/paradigms/verbs.ts): lexical model · `src/paradigms/verbs.ts`
- **Tense and voice paradigms**: morphology implementations · Active, passive, and nominal transformations.
- [Lexicon search](https://github.com/goblindegook/musarrif/blob/main/src/paradigms/search.ts): search resolver · `src/paradigms/search.ts`

### Exercises & SRS

- [Exercise mode](https://github.com/goblindegook/musarrif/blob/main/src/ui/pages/ExerciseMode.tsx): practice page · `src/ui/pages/ExerciseMode.tsx`
- **Exercise generation**: prompt generators · Selects exercise types and creates prompts, answers, and distractors.
- [Exercise selection](https://github.com/goblindegook/musarrif/blob/main/src/exercises/exercises.ts): exercise coordinator · `src/exercises/exercises.ts`
- [SRS & mastery](https://github.com/goblindegook/musarrif/blob/main/src/exercises/srs.ts): learning policy · Schedules reviews and calculates learner progress. · `src/exercises/srs.ts`

### Lexicon & locales

- [Curated roots lexicon](https://github.com/goblindegook/musarrif/blob/main/src/data/roots.json): lexical dataset · Transliterated roots, forms, patterns, and grammatical metadata. · `src/data/roots.json`
- [Localized verb labels](https://github.com/goblindegook/musarrif/blob/main/src/ui/locales/en.verbs.json): locale datasets · English, Italian, and Portuguese display labels. · `src/ui/locales/en.verbs.json`

### Desktop & maintenance

- [Tauri desktop host](https://github.com/goblindegook/musarrif/blob/main/src-tauri/src/main.rs): Rust desktop runtime · `src-tauri/src/main.rs`
- [Lexicon maintenance](https://github.com/goblindegook/musarrif/blob/main/scripts/verb.mts): Node/TypeScript scripts · Edits lexical data and validates external conjugation references. · `scripts/verb.mts`
- [CI](https://github.com/goblindegook/musarrif/blob/main/.github/workflows/ci.yml): GitHub Actions workflow · `.github/workflows/ci.yml`

## Connections

- Vite PWA build → UI entry: loads
- UI entry → Application shell: mounts
- Application shell → Routes: uses
- Routes → Reference mode: navigates to
- Routes → Exercise mode: navigates to
- Reference mode → Conjugation controls: contains
- Conjugation controls → Lexicon search: resolves input
- Conjugation controls → Conjugation orchestration: requests forms
- Conjugation orchestration → Conjugation output: returns results to
- Lexicon search → Verb and root domain: queries
- Conjugation orchestration → Verb and root domain: uses
- Conjugation orchestration → Tense and voice paradigms: dispatches to
- Verb and root domain → Curated roots lexicon: reads
- Application shell → Localized verb labels: renders
- Exercise mode → Exercise selection: coordinates
- Exercise selection → Exercise generation: selects
- Exercise generation → Conjugation orchestration: derives answers from
- Exercise mode → SRS & mastery: records outcomes
- SRS & mastery → Local user state: persists progress
- Exercise mode → Local user state: reads learner state
- Tauri desktop host → Vite PWA build: hosts built UI
- Lexicon maintenance → Curated roots lexicon: edits and validates
- Lexicon maintenance → Localized verb labels: edits
- CI → Lexicon maintenance: runs validation