# davimatosms/arara-voice architecture

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

- Interactive diagram: https://gitdiagram.com/davimatosms/arara-voice
- Repository: https://github.com/davimatosms/arara-voice

## Overview

Arara is a desktop voice-dictation app for Brazilian Portuguese: the user triggers recording with a global shortcut, speaks, reviews live text, then receives a locally transcribed result pasted at the cursor and saved in local history. The core separates audio capture and speech detection from transcription and delivery; app screens provide onboarding, settings, dictionary/history access, themes, and updates. README and source-index references establish the main workflow and module relationships; unsampled implementation details are not expanded into additional call paths.

Main entry points: [`core/src/main/java/br/arara/core/DefaultDictationEngine.java`](https://github.com/davimatosms/arara-voice/blob/main/core/src/main/java/br/arara/core/DefaultDictationEngine.java) (Dictation engine), [`core/src/main/java/br/arara/core/AraraCore.java`](https://github.com/davimatosms/arara-voice/blob/main/core/src/main/java/br/arara/core/AraraCore.java) (Core assembly), [`app/src/main/java/br/arara/app/SettingsPage.java`](https://github.com/davimatosms/arara-voice/blob/main/app/src/main/java/br/arara/app/SettingsPage.java) (Settings screen), [`app/src/main/java/br/arara/app/Main.java`](https://github.com/davimatosms/arara-voice/blob/main/app/src/main/java/br/arara/app/Main.java) (App startup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop app"]
  node_entry["App startup<br/>[Main.java]"]
  node_onboarding["First-run guide<br/>[Onboarding.java]"]
  node_settingsui["Settings screen<br/>[SettingsPage.java]"]
  node_dictationui["Recording popup"]
  node_theme["Themes and macaw<br/>[Theme.java]"]
  node_historyui["History screen<br/>[HistoryPage.java]"]
  node_dictionaryui["Dictionary screen"]
end

subgraph group_dictation["Dictation runtime"]
  node_hotkey["Global shortcut<br/>[GlobalHotkey.java]"]
  node_core["Core assembly<br/>[AraraCore.java]"]
  node_engine["Dictation engine"]
  node_audio["Mic and VAD<br/>[Microphone.java]"]
  node_transcriber["Whisper transcription"]
  node_preview["Live preview"]
  node_paste["Clipboard paste"]
end

subgraph group_data["Local data"]
  node_dictionary[("Correction dictionary")]
  node_history[("Dictation history")]
  node_settings[("Settings store")]
end

subgraph group_operations["Setup and updates"]
  node_modeldownload["Model download<br/>[ModelDownload.java]"]
  node_modelhost["Model host"]
  node_updates["Update checker<br/>[UpdateChecker.java]"]
  node_updateui["Update interface<br/>[UpdateUi.java]"]
  node_manifest["Version manifest"]
end

node_user(("User"))
node_target["Focused app"]

node_user -->|"presses"| node_hotkey
node_hotkey -->|"toggles"| node_engine
node_engine -->|"captures speech"| node_audio
node_engine -->|"transcribes"| node_transcriber
node_engine -->|"emits live text"| node_preview
node_engine -->|"uses terms"| node_dictionary
node_engine -->|"saves result"| node_history
node_engine -->|"pastes text"| node_paste
node_paste -->|"inserts text"| node_target
node_core -->|"creates"| node_engine
node_core -->|"registers"| node_hotkey
node_core -->|"loads and saves"| node_settings
node_core -->|"opens store"| node_history
node_core -->|"opens store"| node_dictionary
node_engine -->|"notifies"| node_dictationui
node_entry -->|"starts"| node_core
node_entry -->|"opens first run"| node_onboarding
node_entry -->|"opens"| node_settingsui
node_settingsui -->|"updates preferences"| node_settings
node_settingsui -->|"opens"| node_historyui
node_historyui -->|"reads entries"| node_history
node_dictionaryui -.->|"edits terms"| node_dictionary
node_settingsui -->|"selects appearance"| node_theme
node_onboarding -->|"requests model"| node_modeldownload
node_modeldownload -->|"downloads model"| node_modelhost
node_settingsui -->|"checks updates"| node_updates
node_updates -->|"fetches version"| node_manifest
node_updates -->|"reports update"| node_updateui

click node_entry "https://github.com/davimatosms/arara-voice/blob/main/app/src/main/java/br/arara/app/Main.java"
click node_onboarding "https://github.com/davimatosms/arara-voice/blob/main/app/src/main/java/br/arara/app/Onboarding.java"
click node_settingsui "https://github.com/davimatosms/arara-voice/blob/main/app/src/main/java/br/arara/app/SettingsPage.java"
click node_dictationui "https://github.com/davimatosms/arara-voice/blob/main/app/src/main/java/br/arara/app/RecordingPopup.java"
click node_theme "https://github.com/davimatosms/arara-voice/blob/main/app/src/main/java/br/arara/app/Theme.java"
click node_hotkey "https://github.com/davimatosms/arara-voice/blob/main/core/src/main/java/br/arara/core/GlobalHotkey.java"
click node_core "https://github.com/davimatosms/arara-voice/blob/main/core/src/main/java/br/arara/core/AraraCore.java"
click node_engine "https://github.com/davimatosms/arara-voice/blob/main/core/src/main/java/br/arara/core/DefaultDictationEngine.java"
click node_audio "https://github.com/davimatosms/arara-voice/blob/main/core/src/main/java/br/arara/core/Microphone.java"
click node_transcriber "https://github.com/davimatosms/arara-voice/blob/main/core/src/main/java/br/arara/core/WhisperTranscriber.java"
click node_preview "https://github.com/davimatosms/arara-voice/blob/main/core/src/main/java/br/arara/core/DefaultDictationEngine.java"
click node_paste "https://github.com/davimatosms/arara-voice/blob/main/core/src/main/java/br/arara/core/ClipboardPaster.java"
click node_dictionary "https://github.com/davimatosms/arara-voice/blob/main/core/src/main/java/br/arara/core/JsonDictionaryStore.java"
click node_history "https://github.com/davimatosms/arara-voice/blob/main/core/src/main/java/br/arara/core/JsonlHistoryStore.java"
click node_settings "https://github.com/davimatosms/arara-voice/blob/main/core/src/main/java/br/arara/core/JsonSettingsStore.java"
click node_historyui "https://github.com/davimatosms/arara-voice/blob/main/app/src/main/java/br/arara/app/HistoryPage.java"
click node_dictionaryui "https://github.com/davimatosms/arara-voice/blob/main/app/src/main/java/br/arara/app/DictionaryPage.java"
click node_modeldownload "https://github.com/davimatosms/arara-voice/blob/main/app/src/main/java/br/arara/app/ModelDownload.java"
click node_updates "https://github.com/davimatosms/arara-voice/blob/main/core/src/main/java/br/arara/core/UpdateChecker.java"
click node_updateui "https://github.com/davimatosms/arara-voice/blob/main/app/src/main/java/br/arara/app/UpdateUi.java"

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_entry,node_onboarding,node_settingsui,node_dictationui,node_theme,node_historyui,node_dictionaryui,node_user toneBlue
class node_hotkey,node_core,node_engine,node_audio,node_transcriber,node_preview,node_paste toneAmber
class node_dictionary,node_history,node_settings toneMint
class node_modeldownload,node_modelhost,node_updates,node_updateui,node_manifest toneRose
class node_target toneIndigo
```

## Components

### Desktop app

- [App startup](https://github.com/davimatosms/arara-voice/blob/main/app/src/main/java/br/arara/app/Main.java): `app/src/main/java/br/arara/app/Main.java`
- [First-run guide](https://github.com/davimatosms/arara-voice/blob/main/app/src/main/java/br/arara/app/Onboarding.java): `app/src/main/java/br/arara/app/Onboarding.java`
- [Settings screen](https://github.com/davimatosms/arara-voice/blob/main/app/src/main/java/br/arara/app/SettingsPage.java): `app/src/main/java/br/arara/app/SettingsPage.java`
- [Recording popup](https://github.com/davimatosms/arara-voice/blob/main/app/src/main/java/br/arara/app/RecordingPopup.java): `app/src/main/java/br/arara/app/RecordingPopup.java`
- [Themes and macaw](https://github.com/davimatosms/arara-voice/blob/main/app/src/main/java/br/arara/app/Theme.java): `app/src/main/java/br/arara/app/Theme.java`
- [History screen](https://github.com/davimatosms/arara-voice/blob/main/app/src/main/java/br/arara/app/HistoryPage.java): `app/src/main/java/br/arara/app/HistoryPage.java`
- [Dictionary screen](https://github.com/davimatosms/arara-voice/blob/main/app/src/main/java/br/arara/app/DictionaryPage.java): `app/src/main/java/br/arara/app/DictionaryPage.java`

### Dictation runtime

- [Global shortcut](https://github.com/davimatosms/arara-voice/blob/main/core/src/main/java/br/arara/core/GlobalHotkey.java): `core/src/main/java/br/arara/core/GlobalHotkey.java`
- [Core assembly](https://github.com/davimatosms/arara-voice/blob/main/core/src/main/java/br/arara/core/AraraCore.java): `core/src/main/java/br/arara/core/AraraCore.java`
- [Dictation engine](https://github.com/davimatosms/arara-voice/blob/main/core/src/main/java/br/arara/core/DefaultDictationEngine.java): `core/src/main/java/br/arara/core/DefaultDictationEngine.java`
- [Mic and VAD](https://github.com/davimatosms/arara-voice/blob/main/core/src/main/java/br/arara/core/Microphone.java): `core/src/main/java/br/arara/core/Microphone.java`
- [Whisper transcription](https://github.com/davimatosms/arara-voice/blob/main/core/src/main/java/br/arara/core/WhisperTranscriber.java): `core/src/main/java/br/arara/core/WhisperTranscriber.java`
- [Live preview](https://github.com/davimatosms/arara-voice/blob/main/core/src/main/java/br/arara/core/DefaultDictationEngine.java): `core/src/main/java/br/arara/core/DefaultDictationEngine.java`
- [Clipboard paste](https://github.com/davimatosms/arara-voice/blob/main/core/src/main/java/br/arara/core/ClipboardPaster.java): `core/src/main/java/br/arara/core/ClipboardPaster.java`

### Local data

- [Correction dictionary](https://github.com/davimatosms/arara-voice/blob/main/core/src/main/java/br/arara/core/JsonDictionaryStore.java): `core/src/main/java/br/arara/core/JsonDictionaryStore.java`
- [Dictation history](https://github.com/davimatosms/arara-voice/blob/main/core/src/main/java/br/arara/core/JsonlHistoryStore.java): `core/src/main/java/br/arara/core/JsonlHistoryStore.java`
- [Settings store](https://github.com/davimatosms/arara-voice/blob/main/core/src/main/java/br/arara/core/JsonSettingsStore.java): `core/src/main/java/br/arara/core/JsonSettingsStore.java`

### Setup and updates

- [Model download](https://github.com/davimatosms/arara-voice/blob/main/app/src/main/java/br/arara/app/ModelDownload.java): `app/src/main/java/br/arara/app/ModelDownload.java`
- **Model host**
- [Update checker](https://github.com/davimatosms/arara-voice/blob/main/core/src/main/java/br/arara/core/UpdateChecker.java): `core/src/main/java/br/arara/core/UpdateChecker.java`
- [Update interface](https://github.com/davimatosms/arara-voice/blob/main/app/src/main/java/br/arara/app/UpdateUi.java): `app/src/main/java/br/arara/app/UpdateUi.java`
- **Version manifest**

### Other components

- **User**
- **Focused app**

## Connections

- User → Global shortcut: presses (evidence: `README.md`)
- Global shortcut → Dictation engine: toggles
- Dictation engine → Mic and VAD: captures speech (evidence: `core/src/main/java/br/arara/core/DefaultDictationEngine.java`)
- Dictation engine → Whisper transcription: transcribes (evidence: `core/src/main/java/br/arara/core/DefaultDictationEngine.java`)
- Dictation engine → Live preview: emits live text (evidence: `core/src/main/java/br/arara/core/DefaultDictationEngine.java`)
- Dictation engine → Correction dictionary: uses terms (evidence: `core/src/main/java/br/arara/core/DefaultDictationEngine.java`)
- Dictation engine → Dictation history: saves result (evidence: `core/src/main/java/br/arara/core/DefaultDictationEngine.java`)
- Dictation engine → Clipboard paste: pastes text (evidence: `core/src/main/java/br/arara/core/DefaultDictationEngine.java`)
- Clipboard paste → Focused app: inserts text (evidence: `README.md`)
- Core assembly → Dictation engine: creates (evidence: `core/src/main/java/br/arara/core/AraraCore.java`)
- Core assembly → Global shortcut: registers (evidence: `core/src/main/java/br/arara/core/AraraCore.java`)
- Core assembly → Settings store: loads and saves (evidence: `core/src/main/java/br/arara/core/AraraCore.java`)
- Core assembly → Dictation history: opens store (evidence: `core/src/main/java/br/arara/core/AraraCore.java`)
- Core assembly → Correction dictionary: opens store (evidence: `core/src/main/java/br/arara/core/AraraCore.java`)
- Dictation engine → Recording popup: notifies
- App startup → Core assembly: starts (evidence: `app/src/main/java/br/arara/app/Main.java`)
- App startup → First-run guide: opens first run (evidence: `app/src/main/java/br/arara/app/Main.java`)
- App startup → Settings screen: opens (evidence: `app/src/main/java/br/arara/app/Main.java`)
- Settings screen → Settings store: updates preferences (evidence: `app/src/main/java/br/arara/app/SettingsPage.java`)
- Settings screen → History screen: opens (evidence: `app/src/main/java/br/arara/app/SettingsPage.java`)
- History screen → Dictation history: reads entries
- Dictionary screen → Correction dictionary: edits terms
- Settings screen → Themes and macaw: selects appearance (evidence: `app/src/main/java/br/arara/app/SettingsPage.java`)
- First-run guide → Model download: requests model (evidence: `app/src/main/java/br/arara/app/Onboarding.java`)
- Model download → Model host: downloads model (evidence: `README.md`)
- Settings screen → Update checker: checks updates (evidence: `app/src/main/java/br/arara/app/SettingsPage.java`)
- Update checker → Version manifest: fetches version (evidence: `core/src/main/java/br/arara/core/UpdateChecker.java`)
- Update checker → Update interface: reports update (evidence: `app/src/main/java/br/arara/app/UpdateUi.java`)
