# habu-kagumba/music-library architecture

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

- Interactive diagram: https://gitdiagram.com/habu-kagumba/music-library
- Repository: https://github.com/habu-kagumba/music-library

## Overview

This is a command-line music catalog: users can list songs, artists, and genres, play a selected song, or browse songs by artist or genre. The controller imports the configured MP3 directory, then dispatches interactive commands against in-memory Song, Artist, and Genre collections. Song filename parsing and relationship wiring form the key domain layer; the shared Findable concern supports name-based lookup. Importer and CLI implementation excerpts are incomplete, so the graph only shows their documented and directly evidenced relationships; “play” is presented as output, not audio playback.

Main entry points: [`lib/music_importer_controller.rb`](https://github.com/habu-kagumba/music-library/blob/master/lib/music_importer_controller.rb) (Command controller), [`lib/song.rb`](https://github.com/habu-kagumba/music-library/blob/master/lib/song.rb) (Song catalog), [`lib/artist.rb`](https://github.com/habu-kagumba/music-library/blob/master/lib/artist.rb) (Artist catalog), [`lib/genre.rb`](https://github.com/habu-kagumba/music-library/blob/master/lib/genre.rb) (Genre catalog)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["CLI interface"]
  node_cli["CLI launcher"]
  node_controller["Command controller"]
end

subgraph group_catalog["Catalog domain"]
  node_song["Song catalog<br/>[song.rb]"]
  node_artist["Artist catalog<br/>[artist.rb]"]
  node_genre["Genre catalog<br/>[genre.rb]"]
  node_findable["Name lookup<br/>[findable.rb]"]
end

subgraph group_import["Library import"]
  node_importer["MP3 importer<br/>[music_importer.rb]"]
  node_mp3dir["MP3 directory"]
end

node_user(("Library user"))

node_user -->|"runs"| node_cli
node_cli -.->|"starts"| node_controller
node_user -->|"enters commands"| node_controller
node_controller -->|"imports"| node_importer
node_importer -.->|"reads files"| node_mp3dir
node_controller -->|"lists and plays"| node_song
node_controller -->|"finds artist"| node_artist
node_controller -->|"finds genre"| node_genre
node_song -->|"assigns artist"| node_artist
node_song -->|"assigns genre"| node_genre
node_artist -->|"collects songs"| node_song
node_genre -->|"collects songs"| node_song
node_song -->|"uses lookup"| node_findable
node_artist -->|"uses lookup"| node_findable
node_genre -->|"uses lookup"| node_findable

click node_cli "https://github.com/habu-kagumba/music-library/blob/master/bin/musiclibrary"
click node_controller "https://github.com/habu-kagumba/music-library/blob/master/lib/music_importer_controller.rb"
click node_importer "https://github.com/habu-kagumba/music-library/blob/master/lib/music_importer.rb"
click node_mp3dir "https://github.com/habu-kagumba/music-library/tree/master/db/mp3s"
click node_song "https://github.com/habu-kagumba/music-library/blob/master/lib/song.rb"
click node_artist "https://github.com/habu-kagumba/music-library/blob/master/lib/artist.rb"
click node_genre "https://github.com/habu-kagumba/music-library/blob/master/lib/genre.rb"
click node_findable "https://github.com/habu-kagumba/music-library/blob/master/lib/concerns/findable.rb"

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_cli,node_controller,node_user toneBlue
class node_song,node_artist,node_genre,node_findable toneAmber
class node_importer,node_mp3dir toneMint
```

## Components

### CLI interface

- [CLI launcher](https://github.com/habu-kagumba/music-library/blob/master/bin/musiclibrary): `bin/musiclibrary`
- [Command controller](https://github.com/habu-kagumba/music-library/blob/master/lib/music_importer_controller.rb): `lib/music_importer_controller.rb`

### Catalog domain

- [Song catalog](https://github.com/habu-kagumba/music-library/blob/master/lib/song.rb): `lib/song.rb`
- [Artist catalog](https://github.com/habu-kagumba/music-library/blob/master/lib/artist.rb): `lib/artist.rb`
- [Genre catalog](https://github.com/habu-kagumba/music-library/blob/master/lib/genre.rb): `lib/genre.rb`
- [Name lookup](https://github.com/habu-kagumba/music-library/blob/master/lib/concerns/findable.rb): `lib/concerns/findable.rb`

### Library import

- [MP3 importer](https://github.com/habu-kagumba/music-library/blob/master/lib/music_importer.rb): `lib/music_importer.rb`
- [MP3 directory](https://github.com/habu-kagumba/music-library/tree/master/db/mp3s): `db/mp3s`

### Other components

- **Library user**

## Connections

- Library user → CLI launcher: runs (evidence: `README.md`)
- CLI launcher → Command controller: starts
- Library user → Command controller: enters commands (evidence: `lib/music_importer_controller.rb`)
- Command controller → MP3 importer: imports (evidence: `lib/music_importer_controller.rb`)
- MP3 importer → MP3 directory: reads files
- Command controller → Song catalog: lists and plays (evidence: `lib/music_importer_controller.rb`)
- Command controller → Artist catalog: finds artist (evidence: `lib/music_importer_controller.rb`)
- Command controller → Genre catalog: finds genre (evidence: `lib/music_importer_controller.rb`)
- Song catalog → Artist catalog: assigns artist (evidence: `lib/song.rb`)
- Song catalog → Genre catalog: assigns genre (evidence: `lib/song.rb`)
- Artist catalog → Song catalog: collects songs (evidence: `lib/artist.rb`)
- Genre catalog → Song catalog: collects songs (evidence: `lib/genre.rb`)
- Song catalog → Name lookup: uses lookup (evidence: `lib/song.rb`)
- Artist catalog → Name lookup: uses lookup (evidence: `lib/artist.rb`)
- Genre catalog → Name lookup: uses lookup (evidence: `lib/genre.rb`)