# maddylaneeee/shengji architecture

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

- Interactive diagram: https://gitdiagram.com/maddylaneeee/shengji
- Repository: https://github.com/maddylaneeee/shengji

## Overview

LocalScribe is a native, local-first macOS speech-to-text and transcript-editing app. The main workflow is to choose a recognition source and engine, transcribe audio into editable segments, optionally translate or enhance the transcript, then export it; long tasks can be paused and recovered. The graph also includes the distinct live-caption path and transcript import. The tree and README establish product capabilities, while the sampled excerpts directly support only some internal call relationships, so uncertain wiring is omitted.

Main entry points: [`LocalScribe/Services/TranscriptionSessionModel.swift`](https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Services/TranscriptionSessionModel.swift) (Transcription session), [`LocalScribe/Views/TranscriptionView.swift`](https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Views/TranscriptionView.swift) (Transcription view), [`LocalScribe/Views/RootView.swift`](https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Views/RootView.swift) (Root view), [`LocalScribe/Services/LiveCaptionController.swift`](https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Services/LiveCaptionController.swift) (Live captions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["App interface"]
  node_root_view["Root view<br/>[RootView.swift]"]
  node_start_view["Start view<br/>[StartView.swift]"]
  node_transcription_view["Transcription view"]
  node_live_panel["Caption panel"]
  node_settings["Settings<br/>[SettingsView.swift]"]
end

subgraph group_recognition["Audio recognition"]
  node_session["Transcription session"]
  node_audio_pipeline["Audio pipeline"]
  node_audio_capture["Realtime capture"]
  node_whisper["Whisper engine"]
  node_sherpa["Sherpa ONNX engine"]
  node_speech_models[("Speech model store")]
  node_live_controller["Live captions"]
end

subgraph group_transcripts["Transcript workflow"]
  node_transcript_editor["Transcript editor"]
  node_transcript_import["Transcript import"]
  node_export["Transcript export"]
end

subgraph group_language_ai["Translation and AI"]
  node_translation["Translation"]
  node_nllb["NLLB translation"]
  node_gemma["Gemma enhancement"]
  node_gemma_models[("Gemma model manager")]
end

subgraph group_persistence["State and storage"]
  node_long_task[("Long-task journal")]
  node_recovery[("Recovery store")]
end

node_user(("User"))
node_microphone(("Microphone"))
node_media(("Audio/video files"))
node_system_audio(("Mac audio"))
node_local_speech["Apple Speech"]

node_user -->|"uses"| node_root_view
node_root_view -->|"shows"| node_start_view
node_root_view -->|"shows"| node_transcription_view
node_root_view -->|"shows"| node_settings
node_start_view -->|"configures"| node_session
node_transcription_view -->|"controls"| node_session
node_microphone -->|"supplies audio"| node_audio_capture
node_media -->|"supplies media"| node_audio_pipeline
node_system_audio -->|"supplies audio"| node_live_controller
node_session -->|"prepares media"| node_audio_pipeline
node_session -->|"transcribes"| node_whisper
node_session -->|"transcribes"| node_sherpa
node_session -.->|"transcribes"| node_local_speech
node_audio_capture -->|"streams audio"| node_session
node_speech_models -->|"provides models"| node_whisper
node_speech_models -->|"provides models"| node_sherpa
node_live_panel -->|"controls captions"| node_live_controller
node_live_controller -.->|"recognizes audio"| node_local_speech
node_session -->|"journals progress"| node_long_task
node_session -->|"recovers tasks"| node_recovery
node_transcription_view -->|"imports transcript"| node_transcript_import
node_transcription_view -->|"edits transcript"| node_transcript_editor
node_transcription_view -->|"requests translation"| node_translation
node_transcription_view -.->|"requests translation"| node_nllb
node_transcription_view -->|"enhances transcript"| node_gemma
node_gemma -->|"loads model"| node_gemma_models
node_transcription_view -->|"exports transcript"| node_export

click node_root_view "https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Views/RootView.swift"
click node_start_view "https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Views/StartView.swift"
click node_transcription_view "https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Views/TranscriptionView.swift"
click node_live_panel "https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Views/LiveCaptionPanelView.swift"
click node_settings "https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Views/SettingsView.swift"
click node_session "https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Services/TranscriptionSessionModel.swift"
click node_audio_pipeline "https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Services/AudioPipeline.swift"
click node_audio_capture "https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Services/RealtimeAudioCapture.swift"
click node_whisper "https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Services/WhisperEngine.swift"
click node_sherpa "https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Services/SherpaOnnxEngine.swift"
click node_speech_models "https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Services/SpeechModelStore.swift"
click node_live_controller "https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Services/LiveCaptionController.swift"
click node_transcript_editor "https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Views/TranscriptEditingView.swift"
click node_transcript_import "https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Services/TranscriptImport.swift"
click node_export "https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Services/ExportService.swift"
click node_translation "https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Services/AppleTranslation.swift"
click node_nllb "https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Services/NLLBTranslation.swift"
click node_gemma "https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Services/GemmaOptimization.swift"
click node_gemma_models "https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Services/GemmaModelManager.swift"
click node_long_task "https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Services/LongTaskStorage.swift"
click node_recovery "https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Services/RecoveryStore.swift"

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_root_view,node_start_view,node_transcription_view,node_live_panel,node_settings,node_user toneBlue
class node_session,node_audio_pipeline,node_audio_capture,node_whisper,node_sherpa,node_speech_models,node_live_controller toneAmber
class node_transcript_editor,node_transcript_import,node_export toneMint
class node_translation,node_nllb,node_gemma,node_gemma_models toneRose
class node_long_task,node_recovery,node_microphone,node_media,node_system_audio,node_local_speech toneIndigo
```

## Components

### App interface

- [Root view](https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Views/RootView.swift): `LocalScribe/Views/RootView.swift`
- [Start view](https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Views/StartView.swift): `LocalScribe/Views/StartView.swift`
- [Transcription view](https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Views/TranscriptionView.swift): `LocalScribe/Views/TranscriptionView.swift`
- [Caption panel](https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Views/LiveCaptionPanelView.swift): `LocalScribe/Views/LiveCaptionPanelView.swift`
- [Settings](https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Views/SettingsView.swift): `LocalScribe/Views/SettingsView.swift`

### Audio recognition

- [Transcription session](https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Services/TranscriptionSessionModel.swift): `LocalScribe/Services/TranscriptionSessionModel.swift`
- [Audio pipeline](https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Services/AudioPipeline.swift): `LocalScribe/Services/AudioPipeline.swift`
- [Realtime capture](https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Services/RealtimeAudioCapture.swift): `LocalScribe/Services/RealtimeAudioCapture.swift`
- [Whisper engine](https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Services/WhisperEngine.swift): `LocalScribe/Services/WhisperEngine.swift`
- [Sherpa ONNX engine](https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Services/SherpaOnnxEngine.swift): `LocalScribe/Services/SherpaOnnxEngine.swift`
- [Speech model store](https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Services/SpeechModelStore.swift): `LocalScribe/Services/SpeechModelStore.swift`
- [Live captions](https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Services/LiveCaptionController.swift): `LocalScribe/Services/LiveCaptionController.swift`

### Transcript workflow

- [Transcript editor](https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Views/TranscriptEditingView.swift): `LocalScribe/Views/TranscriptEditingView.swift`
- [Transcript import](https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Services/TranscriptImport.swift): `LocalScribe/Services/TranscriptImport.swift`
- [Transcript export](https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Services/ExportService.swift): `LocalScribe/Services/ExportService.swift`

### Translation and AI

- [Translation](https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Services/AppleTranslation.swift): `LocalScribe/Services/AppleTranslation.swift`
- [NLLB translation](https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Services/NLLBTranslation.swift): `LocalScribe/Services/NLLBTranslation.swift`
- [Gemma enhancement](https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Services/GemmaOptimization.swift): `LocalScribe/Services/GemmaOptimization.swift`
- [Gemma model manager](https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Services/GemmaModelManager.swift): `LocalScribe/Services/GemmaModelManager.swift`

### State and storage

- [Long-task journal](https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Services/LongTaskStorage.swift): `LocalScribe/Services/LongTaskStorage.swift`
- [Recovery store](https://github.com/maddylaneeee/shengji/blob/main/LocalScribe/Services/RecoveryStore.swift): `LocalScribe/Services/RecoveryStore.swift`

### Other components

- **User**
- **Microphone**
- **Audio/video files**
- **Mac audio**
- **Apple Speech**

## Connections

- User → Root view: uses
- Root view → Start view: shows
- Root view → Transcription view: shows
- Root view → Settings: shows
- Start view → Transcription session: configures
- Transcription view → Transcription session: controls
- Microphone → Realtime capture: supplies audio
- Audio/video files → Audio pipeline: supplies media
- Mac audio → Live captions: supplies audio
- Transcription session → Audio pipeline: prepares media
- Transcription session → Whisper engine: transcribes
- Transcription session → Sherpa ONNX engine: transcribes
- Transcription session → Apple Speech: transcribes
- Realtime capture → Transcription session: streams audio
- Speech model store → Whisper engine: provides models
- Speech model store → Sherpa ONNX engine: provides models
- Caption panel → Live captions: controls captions
- Live captions → Apple Speech: recognizes audio
- Transcription session → Long-task journal: journals progress
- Transcription session → Recovery store: recovers tasks
- Transcription view → Transcript import: imports transcript
- Transcription view → Transcript editor: edits transcript
- Transcription view → Translation: requests translation
- Transcription view → NLLB translation: requests translation
- Transcription view → Gemma enhancement: enhances transcript
- Gemma enhancement → Gemma model manager: loads model
- Transcription view → Transcript export: exports transcript