# adna1206/karaoke-toolkit architecture

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

- Interactive diagram: https://gitdiagram.com/adna1206/karaoke-toolkit
- Repository: https://github.com/adna1206/karaoke-toolkit

## Overview

Karaoke Toolkit is a local karaoke-file management product with an Avalonia desktop app plus CLI and MCP entry points. Users choose files or folders, select an operation, review options, and receive converted or managed files and a completion report. The Core execution layer dispatches operations into conversion, tagging, validation, recipes, and file-management workflows; staged transactions and recovery journals protect publication and support resuming interrupted work. The README documents the major capability branches; some GUI wiring and unsampled implementations are represented only where documented, rather than inferred from names.

Main entry points: [`KaraokeToolkit.Core/Execution/OperationExecutionService.cs`](https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Core/Execution/OperationExecutionService.cs) (Operation Dispatch), [`KaraokeToolkit.Core/Conversion/ConversionService.cs`](https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Core/Conversion/ConversionService.cs) (Conversion Engine), [`KaraokeToolkit.App/App.axaml.cs`](https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.App/App.axaml.cs) (Desktop App), [`KaraokeToolkit.Core/Tagging/KaraokeTaggingService.cs`](https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Core/Tagging/KaraokeTaggingService.cs) (Metadata Tagging)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_desktop["Desktop App<br/>[App.axaml.cs]"]
  node_cli["CLI<br/>[CliApplication.cs]"]
  node_mcp["MCP Tools<br/>[McpTools.cs]"]
end

subgraph group_orchestration["Workflow Execution"]
  node_dispatch["Operation Dispatch"]
  node_selection["Input Selection<br/>[InputSelection.cs]"]
  node_conversion["Conversion Workflow"]
  node_recipes["Recipes<br/>[RecipeRunner.cs]"]
end

subgraph group_media["Media Processing"]
  node_conversionengine["Conversion Engine"]
  node_archives["Karaoke Archives"]
  node_audio["Audio Encoding"]
  node_video["Video Encoding"]
  node_disc["Disc Ripping<br/>[DiscRipService.cs]"]
end

subgraph group_management["File Management"]
  node_tagging["Metadata Tagging"]
  node_validation["Karaoke Validation"]
  node_fileops["File Organization"]
  node_reports["Completion Reports"]
end

subgraph group_state["Settings and Recovery"]
  node_settings[("User Settings<br/>[SettingsStore.cs]")]
  node_transactions["File Transactions<br/>[FileTransaction.cs]"]
  node_recovery[("Recovery Store<br/>[RecoveryStore.cs]")]
  node_workflowstate[("Workflow Journal<br/>[WorkflowSession.cs]")]
end

node_user(("User"))

node_user -->|"chooses tools"| node_desktop
node_user -->|"runs commands"| node_cli
node_user -->|"invokes tools"| node_mcp
node_desktop -.->|"runs operations"| node_dispatch
node_cli -.->|"executes requests"| node_dispatch
node_mcp -->|"executes requests"| node_dispatch
node_dispatch -->|"expands inputs"| node_selection
node_dispatch -->|"dispatches conversions"| node_conversion
node_dispatch -->|"dispatches tagging"| node_tagging
node_dispatch -->|"dispatches validation"| node_validation
node_dispatch -->|"dispatches file tasks"| node_fileops
node_conversion -->|"runs batches"| node_conversionengine
node_conversionengine -->|"validates inputs"| node_validation
node_conversionengine -->|"publishes outputs"| node_transactions
node_conversionengine -->|"converts archives"| node_archives
node_conversionengine -->|"encodes audio"| node_audio
node_conversionengine -->|"creates video"| node_video
node_dispatch -.->|"runs workflows"| node_recipes
node_recipes -->|"saves progress"| node_workflowstate
node_dispatch -.->|"supports ripping"| node_disc
node_dispatch -->|"returns results"| node_reports
node_tagging -->|"stages updates"| node_transactions
node_transactions -->|"registers journals"| node_recovery
node_workflowstate -->|"registers journal"| node_recovery
node_desktop -.->|"stores preferences"| node_settings
node_user -->|"checks files"| node_validation
node_user -->|"edits metadata"| node_tagging
node_user -->|"organizes files"| node_fileops
node_user -.->|"rips discs"| node_disc
node_user -->|"resumes work"| node_recovery

click node_desktop "https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.App/App.axaml.cs"
click node_cli "https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Cli/CliApplication.cs"
click node_mcp "https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Mcp/McpTools.cs"
click node_dispatch "https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Core/Execution/OperationExecutionService.cs"
click node_selection "https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Core/Conversion/InputSelection.cs"
click node_conversion "https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Core/Conversion/SelectionConversionService.cs"
click node_recipes "https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Core/Recipes/RecipeRunner.cs"
click node_conversionengine "https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Core/Conversion/ConversionService.cs"
click node_archives "https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Core/Archives/ArchiveZipConverter.cs"
click node_audio "https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Core/Audio/AudioEncoderService.cs"
click node_video "https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Core/Video/VideoEncoderService.cs"
click node_disc "https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Core/DiscRipping/DiscRipService.cs"
click node_tagging "https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Core/Tagging/KaraokeTaggingService.cs"
click node_validation "https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Core/Validation/ValidationService.cs"
click node_fileops "https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Core/FileOperations/TrackGroupingPlanner.cs"
click node_reports "https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Core/Reporting/CompletionReport.cs"
click node_settings "https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Core/Settings/SettingsStore.cs"
click node_transactions "https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Core/Recovery/FileTransaction.cs"
click node_recovery "https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Core/Recovery/RecoveryStore.cs"
click node_workflowstate "https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Core/Recovery/WorkflowSession.cs"

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_desktop,node_cli,node_mcp,node_user toneBlue
class node_dispatch,node_selection,node_conversion,node_recipes toneAmber
class node_conversionengine,node_archives,node_audio,node_video,node_disc toneMint
class node_tagging,node_validation,node_fileops,node_reports toneRose
class node_settings,node_transactions,node_recovery,node_workflowstate toneIndigo
```

## Components

### User Interfaces

- [Desktop App](https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.App/App.axaml.cs): `KaraokeToolkit.App/App.axaml.cs`
- [CLI](https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Cli/CliApplication.cs): `KaraokeToolkit.Cli/CliApplication.cs`
- [MCP Tools](https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Mcp/McpTools.cs): `KaraokeToolkit.Mcp/McpTools.cs`

### Workflow Execution

- [Operation Dispatch](https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Core/Execution/OperationExecutionService.cs): `KaraokeToolkit.Core/Execution/OperationExecutionService.cs`
- [Input Selection](https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Core/Conversion/InputSelection.cs): `KaraokeToolkit.Core/Conversion/InputSelection.cs`
- [Conversion Workflow](https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Core/Conversion/SelectionConversionService.cs): `KaraokeToolkit.Core/Conversion/SelectionConversionService.cs`
- [Recipes](https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Core/Recipes/RecipeRunner.cs): `KaraokeToolkit.Core/Recipes/RecipeRunner.cs`

### Media Processing

- [Conversion Engine](https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Core/Conversion/ConversionService.cs): `KaraokeToolkit.Core/Conversion/ConversionService.cs`
- [Karaoke Archives](https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Core/Archives/ArchiveZipConverter.cs): `KaraokeToolkit.Core/Archives/ArchiveZipConverter.cs`
- [Audio Encoding](https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Core/Audio/AudioEncoderService.cs): `KaraokeToolkit.Core/Audio/AudioEncoderService.cs`
- [Video Encoding](https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Core/Video/VideoEncoderService.cs): `KaraokeToolkit.Core/Video/VideoEncoderService.cs`
- [Disc Ripping](https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Core/DiscRipping/DiscRipService.cs): `KaraokeToolkit.Core/DiscRipping/DiscRipService.cs`

### File Management

- [Metadata Tagging](https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Core/Tagging/KaraokeTaggingService.cs): `KaraokeToolkit.Core/Tagging/KaraokeTaggingService.cs`
- [Karaoke Validation](https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Core/Validation/ValidationService.cs): `KaraokeToolkit.Core/Validation/ValidationService.cs`
- [File Organization](https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Core/FileOperations/TrackGroupingPlanner.cs): `KaraokeToolkit.Core/FileOperations/TrackGroupingPlanner.cs`
- [Completion Reports](https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Core/Reporting/CompletionReport.cs): `KaraokeToolkit.Core/Reporting/CompletionReport.cs`

### Settings and Recovery

- [User Settings](https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Core/Settings/SettingsStore.cs): `KaraokeToolkit.Core/Settings/SettingsStore.cs`
- [File Transactions](https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Core/Recovery/FileTransaction.cs): `KaraokeToolkit.Core/Recovery/FileTransaction.cs`
- [Recovery Store](https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Core/Recovery/RecoveryStore.cs): `KaraokeToolkit.Core/Recovery/RecoveryStore.cs`
- [Workflow Journal](https://github.com/adna1206/karaoke-toolkit/blob/master/KaraokeToolkit.Core/Recovery/WorkflowSession.cs): `KaraokeToolkit.Core/Recovery/WorkflowSession.cs`

### Other components

- **User**

## Connections

- User → Desktop App: chooses tools (evidence: `README.md`)
- User → CLI: runs commands (evidence: `README.md`)
- User → MCP Tools: invokes tools (evidence: `README.md`)
- Desktop App → Operation Dispatch: runs operations
- CLI → Operation Dispatch: executes requests
- MCP Tools → Operation Dispatch: executes requests
- Operation Dispatch → Input Selection: expands inputs (evidence: `KaraokeToolkit.Core/Execution/OperationExecutionService.cs`)
- Operation Dispatch → Conversion Workflow: dispatches conversions (evidence: `KaraokeToolkit.Core/Execution/OperationExecutionService.cs`)
- Operation Dispatch → Metadata Tagging: dispatches tagging (evidence: `KaraokeToolkit.Core/Execution/OperationExecutionService.cs`)
- Operation Dispatch → Karaoke Validation: dispatches validation (evidence: `KaraokeToolkit.Core/Execution/OperationExecutionService.cs`)
- Operation Dispatch → File Organization: dispatches file tasks (evidence: `KaraokeToolkit.Core/Execution/OperationExecutionService.cs`)
- Conversion Workflow → Conversion Engine: runs batches (evidence: `KaraokeToolkit.Core/Conversion/SelectionConversionService.cs`)
- Conversion Engine → Karaoke Validation: validates inputs (evidence: `KaraokeToolkit.Core/Conversion/ConversionService.cs`)
- Conversion Engine → File Transactions: publishes outputs (evidence: `KaraokeToolkit.Core/Conversion/ConversionService.cs`)
- Conversion Engine → Karaoke Archives: converts archives (evidence: `KaraokeToolkit.Core/Conversion/ConversionService.cs`)
- Conversion Engine → Audio Encoding: encodes audio (evidence: `KaraokeToolkit.Core/Conversion/ConversionService.cs`)
- Conversion Engine → Video Encoding: creates video (evidence: `KaraokeToolkit.Core/Conversion/ConversionService.cs`)
- Operation Dispatch → Recipes: runs workflows (evidence: `KaraokeToolkit.Core/Execution/OperationExecutionService.cs`)
- Recipes → Workflow Journal: saves progress (evidence: `KaraokeToolkit.Core/Recovery/WorkflowSession.cs`)
- Operation Dispatch → Disc Ripping: supports ripping
- Operation Dispatch → Completion Reports: returns results (evidence: `KaraokeToolkit.Core/Execution/OperationExecutionService.cs`)
- Metadata Tagging → File Transactions: stages updates (evidence: `KaraokeToolkit.Core/Tagging/KaraokeTaggingService.cs`)
- File Transactions → Recovery Store: registers journals (evidence: `KaraokeToolkit.Core/Recovery/RecoveryStore.cs`)
- Workflow Journal → Recovery Store: registers journal (evidence: `KaraokeToolkit.Core/Recovery/WorkflowSession.cs`)
- Desktop App → User Settings: stores preferences
- User → Karaoke Validation: checks files (evidence: `README.md`)
- User → Metadata Tagging: edits metadata (evidence: `README.md`)
- User → File Organization: organizes files (evidence: `README.md`)
- User → Disc Ripping: rips discs (evidence: `README.md`)
- User → Recovery Store: resumes work (evidence: `README.md`)
