# coconut-e/music_nano architecture

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

- Interactive diagram: https://gitdiagram.com/coconut-e/music_nano
- Repository: https://github.com/coconut-e/music_nano

## Overview

music_nano is an ESP32 microSD music player: the user browses scanned media, selects a track, and sends decoded audio over Bluetooth A2DP to headphones. The firmware also offers lyrics, novel reading, device settings and power management, plus Wi-Fi OTA updates. The graph follows the documented startup and playback workflow and preserves these major feature branches. Some subsystems are represented by tree-supported implementation paths but were not sampled; their links are included only where the README documents them.

Main entry points: [`main/main.c`](https://github.com/coconut-e/music_nano/blob/main/main/main.c) (Firmware Startup), [`main/audio/audio_task.cpp`](https://github.com/coconut-e/music_nano/blob/main/main/audio/audio_task.cpp) (Audio Decode), [`main/ui/ui_player.c`](https://github.com/coconut-e/music_nano/blob/main/main/ui/ui_player.c) (Music Player UI), [`main/ui/ui_settings_wifi.c`](https://github.com/coconut-e/music_nano/blob/main/main/ui/ui_settings_wifi.c) (Wi-Fi Settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_media["Media and Audio"]
  node_media_scan["Media Scan<br/>[media_scan.c]"]
  node_media_index[("Media Index<br/>[sys_monitor.c]")]
  node_audio["Audio Decode<br/>[audio_task.cpp]"]
  node_decoders["Format Decoders<br/>[decoder_mp3.cpp]"]
  node_pcm["PCM Conversion<br/>[pcm_pipeline.cpp]"]
  node_cover["Cover Decode<br/>[cover.cpp]"]
end

subgraph group_interface["User Interface"]
  node_browser["Media Browser<br/>[menu_browser.c]"]
  node_player["Music Player UI<br/>[ui_player.c]"]
  node_lyrics["Lyrics View<br/>[ui_lyrics.c]"]
  node_novel["Novel Reader<br/>[ui_novel.c]"]
  node_settings["Settings UI<br/>[ui_settings.c]"]
  node_wifi_settings["Wi-Fi Settings<br/>[ui_settings_wifi.c]"]
end

subgraph group_connectivity["Connectivity and Updates"]
  node_bluetooth["Bluetooth Audio<br/>[bt_a2dp.c]"]
  node_wifi["Wi-Fi Manager<br/>[wifi_mgr.c]"]
  node_ota["OTA Updates<br/>[ota.c]"]
end

subgraph group_device["Device Services"]
  node_firmware["Firmware Startup<br/>[main.c]"]
  node_power["Power Management<br/>[power_mgr.c]"]
  node_battery["Battery Monitor<br/>[power_batt.c]"]
  node_display["Display Driver<br/>[drv_display.c]"]
  node_touch["Touch Input<br/>[touch.c]"]
end

node_user(("User"))
node_headphones(("Headphones"))

node_user -->|"browses media"| node_browser
node_firmware -->|"starts services"| node_media_scan
node_media_scan -->|"builds index"| node_media_index
node_media_index -->|"provides listings"| node_browser
node_browser -->|"selects track"| node_player
node_player -->|"sends commands"| node_audio
node_audio -->|"decodes formats"| node_decoders
node_audio -->|"converts PCM"| node_pcm
node_audio -->|"streams PCM"| node_bluetooth
node_bluetooth -->|"plays audio"| node_headphones
node_audio -->|"extracts artwork"| node_cover
node_cover -->|"supplies cover"| node_player
node_player -->|"opens lyrics"| node_lyrics
node_user -->|"reads novels"| node_novel
node_user -->|"configures device"| node_settings
node_settings -->|"opens Wi-Fi"| node_wifi_settings
node_wifi_settings -->|"manages Wi-Fi"| node_wifi
node_wifi_settings -->|"starts updates"| node_ota
node_firmware -->|"initializes OTA"| node_ota
node_firmware -->|"initializes Bluetooth"| node_bluetooth
node_firmware -->|"initializes power"| node_power
node_firmware -->|"checks battery"| node_battery
node_firmware -->|"initializes display"| node_display
node_firmware -.->|"starts input"| node_touch

click node_firmware "https://github.com/coconut-e/music_nano/blob/main/main/main.c"
click node_media_scan "https://github.com/coconut-e/music_nano/blob/main/main/storage/media_scan.c"
click node_media_index "https://github.com/coconut-e/music_nano/blob/main/main/storage/sys_monitor.c"
click node_browser "https://github.com/coconut-e/music_nano/blob/main/main/ui/menu/menu_browser.c"
click node_player "https://github.com/coconut-e/music_nano/blob/main/main/ui/ui_player.c"
click node_audio "https://github.com/coconut-e/music_nano/blob/main/main/audio/audio_task.cpp"
click node_decoders "https://github.com/coconut-e/music_nano/blob/main/main/audio/decoder_mp3.cpp"
click node_pcm "https://github.com/coconut-e/music_nano/blob/main/main/audio/pcm_pipeline.cpp"
click node_cover "https://github.com/coconut-e/music_nano/blob/main/main/audio/cover.cpp"
click node_bluetooth "https://github.com/coconut-e/music_nano/blob/main/main/bt/bt_a2dp.c"
click node_lyrics "https://github.com/coconut-e/music_nano/blob/main/main/ui/ui_lyrics.c"
click node_novel "https://github.com/coconut-e/music_nano/blob/main/main/ui/ui_novel.c"
click node_settings "https://github.com/coconut-e/music_nano/blob/main/main/ui/ui_settings.c"
click node_wifi_settings "https://github.com/coconut-e/music_nano/blob/main/main/ui/ui_settings_wifi.c"
click node_wifi "https://github.com/coconut-e/music_nano/blob/main/main/app/wifi_mgr.c"
click node_ota "https://github.com/coconut-e/music_nano/blob/main/main/app/ota.c"
click node_power "https://github.com/coconut-e/music_nano/blob/main/main/power/power_mgr.c"
click node_battery "https://github.com/coconut-e/music_nano/blob/main/main/power/power_batt.c"
click node_display "https://github.com/coconut-e/music_nano/blob/main/main/drivers/drv_display.c"
click node_touch "https://github.com/coconut-e/music_nano/blob/main/main/drivers/touch.c"

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_media_scan,node_media_index,node_audio,node_decoders,node_pcm,node_cover,node_user toneBlue
class node_browser,node_player,node_lyrics,node_novel,node_settings,node_wifi_settings toneAmber
class node_bluetooth,node_wifi,node_ota toneMint
class node_firmware,node_power,node_battery,node_display,node_touch toneRose
class node_headphones toneIndigo
```

## Components

### Media and Audio

- [Media Scan](https://github.com/coconut-e/music_nano/blob/main/main/storage/media_scan.c): `main/storage/media_scan.c`
- [Media Index](https://github.com/coconut-e/music_nano/blob/main/main/storage/sys_monitor.c): `main/storage/sys_monitor.c`
- [Audio Decode](https://github.com/coconut-e/music_nano/blob/main/main/audio/audio_task.cpp): `main/audio/audio_task.cpp`
- [Format Decoders](https://github.com/coconut-e/music_nano/blob/main/main/audio/decoder_mp3.cpp): `main/audio/decoder_mp3.cpp`
- [PCM Conversion](https://github.com/coconut-e/music_nano/blob/main/main/audio/pcm_pipeline.cpp): `main/audio/pcm_pipeline.cpp`
- [Cover Decode](https://github.com/coconut-e/music_nano/blob/main/main/audio/cover.cpp): `main/audio/cover.cpp`

### User Interface

- [Media Browser](https://github.com/coconut-e/music_nano/blob/main/main/ui/menu/menu_browser.c): `main/ui/menu/menu_browser.c`
- [Music Player UI](https://github.com/coconut-e/music_nano/blob/main/main/ui/ui_player.c): `main/ui/ui_player.c`
- [Lyrics View](https://github.com/coconut-e/music_nano/blob/main/main/ui/ui_lyrics.c): `main/ui/ui_lyrics.c`
- [Novel Reader](https://github.com/coconut-e/music_nano/blob/main/main/ui/ui_novel.c): `main/ui/ui_novel.c`
- [Settings UI](https://github.com/coconut-e/music_nano/blob/main/main/ui/ui_settings.c): `main/ui/ui_settings.c`
- [Wi-Fi Settings](https://github.com/coconut-e/music_nano/blob/main/main/ui/ui_settings_wifi.c): `main/ui/ui_settings_wifi.c`

### Connectivity and Updates

- [Bluetooth Audio](https://github.com/coconut-e/music_nano/blob/main/main/bt/bt_a2dp.c): `main/bt/bt_a2dp.c`
- [Wi-Fi Manager](https://github.com/coconut-e/music_nano/blob/main/main/app/wifi_mgr.c): `main/app/wifi_mgr.c`
- [OTA Updates](https://github.com/coconut-e/music_nano/blob/main/main/app/ota.c): `main/app/ota.c`

### Device Services

- [Firmware Startup](https://github.com/coconut-e/music_nano/blob/main/main/main.c): `main/main.c`
- [Power Management](https://github.com/coconut-e/music_nano/blob/main/main/power/power_mgr.c): `main/power/power_mgr.c`
- [Battery Monitor](https://github.com/coconut-e/music_nano/blob/main/main/power/power_batt.c): `main/power/power_batt.c`
- [Display Driver](https://github.com/coconut-e/music_nano/blob/main/main/drivers/drv_display.c): `main/drivers/drv_display.c`
- [Touch Input](https://github.com/coconut-e/music_nano/blob/main/main/drivers/touch.c): `main/drivers/touch.c`

### Other components

- **User**
- **Headphones**

## Connections

- User → Media Browser: browses media (evidence: `README.md`)
- Firmware Startup → Media Scan: starts services (evidence: `main/main.c`)
- Media Scan → Media Index: builds index (evidence: `README.md`)
- Media Index → Media Browser: provides listings (evidence: `README.md`)
- Media Browser → Music Player UI: selects track (evidence: `main/ui/menu/menu_browser.c`)
- Music Player UI → Audio Decode: sends commands (evidence: `README.md`)
- Audio Decode → Format Decoders: decodes formats (evidence: `README.md`)
- Audio Decode → PCM Conversion: converts PCM
- Audio Decode → Bluetooth Audio: streams PCM (evidence: `README.md`)
- Bluetooth Audio → Headphones: plays audio (evidence: `README.md`)
- Audio Decode → Cover Decode: extracts artwork (evidence: `README.md`)
- Cover Decode → Music Player UI: supplies cover (evidence: `main/ui/ui_player.c`)
- Music Player UI → Lyrics View: opens lyrics (evidence: `README.md`)
- User → Novel Reader: reads novels (evidence: `README.md`)
- User → Settings UI: configures device (evidence: `README.md`)
- Settings UI → Wi-Fi Settings: opens Wi-Fi (evidence: `main/ui/ui_settings_wifi.c`)
- Wi-Fi Settings → Wi-Fi Manager: manages Wi-Fi (evidence: `main/ui/ui_settings_wifi.c`)
- Wi-Fi Settings → OTA Updates: starts updates (evidence: `README.md`)
- Firmware Startup → OTA Updates: initializes OTA (evidence: `main/main.c`)
- Firmware Startup → Bluetooth Audio: initializes Bluetooth (evidence: `main/main.c`)
- Firmware Startup → Power Management: initializes power (evidence: `main/main.c`)
- Firmware Startup → Battery Monitor: checks battery (evidence: `main/main.c`)
- Firmware Startup → Display Driver: initializes display (evidence: `main/main.c`)
- Firmware Startup → Touch Input: starts input
