# taclab/music-box architecture

> Architecture diagram of the GitHub repository taclab/music-box, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/taclab/music-box
- Repository: https://github.com/taclab/music-box

## Overview

##### Project Type & Purpose
- This is an embedded, hardware-software system built on an ESP8266 (Adafruit Feather HUZZAH) that reads NFC cards (via a PN532 module) to control playback on a DFPlayer Mini audio module.
- It is *not* a web or full-stack app, but an interactive, standalone device.

##### File Structure
- Top level:
- platformio.ini (build & deployment)
- src/ (application code: main.cpp, cards.h)
- lib/ (third-party or in-repo libraries)
- lib/NDEF: handles NDEF-format NFC payload parsing
- lib/PN532: low-level NFC driver (I2C, SPI, HSU transports + LLCP/SNEP)
- Documentation: docs/circuit.png and 3D case STL files
- No backend/frontend split: code is all on the MCU.

##### Extract Key Architectural Insights from README
- Hardware interfaces:
- I2C (SDA/SCL) to PN532 NFC reader
- UART (TX/RX) to DFPlayer Mini
- GPIO (BUSY pin) from DFPlayer Mini for end‐of‐track
- Software features: NDEF card scanning → ID mapping (cards.h) → play/volume/mode commands.
- Use of PlatformIO for build, Arduino‐style loop() and setup() in main.cpp.

##### Main Components & Their Interactions
a. Hardware Blocks
- ESP8266 MCU (power, firmware)
- PN532 NFC Reader Module (I2C bus)
- DFRobot DFPlayer Mini (UART + busy‐pin GPIO)
- microSD Card (mounted by DFPlayer Mini)
- LiPo Battery & Power Regulation
- 3D Printed Enclosure (physical housing)
b. Software Blocks
- HAL/Transport Layer (lib/PN532_* for I2C/SPI/HSU)
- NFC Protocol Layer (lib/PN532/llcp, snep)
- NDEF Parsing Library (lib/NDEF)
- Application Logic (src/main.cpp)
- Card Definitions (src/cards.h)
- Audio Library (DFRobotDFPlayerMini via Arduino Library Manager)
- Configuration & Build (platformio.ini)

##### Architectural Patterns & Design Principles
- Layered Abstraction:
- Transport → Protocol → Format → Application
- Event‐Driven Loop: main.cpp polls PN532, reacts to events (card tap, end-of-track, volume card).
- Separation of Concerns: NFC handling vs. audio control vs. card ID configuration.
- Hardware Abstraction: generic PN532 interface (can switch I2C to SPI by changing include/PlatformIO settings).

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "3D-Printed Enclosure"
        subgraph "Hardware"
            MCU["ESP8266 MCU"]:::hardware
            PN532["PN532 NFC Reader"]:::hardware
            DFPlayer["DFPlayer Mini"]:::hardware
            SD["microSD (FAT32)"]:::external
            Battery["LiPo Battery + Regulator"]:::external
        end
        MCU <-->|"I2C SDA/SCL"| PN532
        MCU -->|"UART TX/RX"| DFPlayer
        DFPlayer -->|"BUSY pin (GPIO16)"| MCU
        DFPlayer --> SD
        Battery --> MCU
        Battery --> PN532
        Battery --> DFPlayer
        subgraph "Firmware"
            subgraph "Transport & Protocol"
                PN532_HAL["PN532 HAL (I2C/SPI/HSU)"]:::software
                Protocol["PN532 Protocol (LLCP/SNEP)"]:::software
            end
            NDEF["NDEF Parsing Library"]:::software
            App["Application Logic\n(main.cpp)"]:::software
            Cards["Card Definitions\n(cards.h)"]:::software
            Config["Build & Deployment\n(platformio.ini)"]:::software
        end
        PN532_HAL --> Protocol
        Protocol --> NDEF
        NDEF --> App
        Cards --> App
        Config --> App
        App --> MCU
    end

    classDef hardware fill:#ddd,stroke:#333,stroke-width:1px
    classDef software fill:#ccf,stroke:#333,stroke-width:1px
    classDef external fill:#cfc,stroke:#333,stroke-width:1px

    click Config "https://github.com/taclab/music-box/blob/main/platformio.ini"
    click App "https://github.com/taclab/music-box/blob/main/src/main.cpp"
    click Cards "https://github.com/taclab/music-box/blob/main/src/cards.h"
    click NDEF "https://github.com/taclab/music-box/tree/main/lib/NDEF/"
    click PN532_HAL "https://github.com/taclab/music-box/tree/main/lib/PN532/"
    click PN532_HAL "https://github.com/taclab/music-box/tree/main/lib/PN532_I2C/"
    click PN532_HAL "https://github.com/taclab/music-box/tree/main/lib/PN532_SPI/"
    click PN532_HAL "https://github.com/taclab/music-box/tree/main/lib/PN532_HSU/"
    click PN532_HAL "https://github.com/taclab/music-box/tree/main/lib/PN532_SWHSU/"
    click Protocol "https://github.com/taclab/music-box/blob/main/lib/PN532/llcp.cpp"
    click Protocol "https://github.com/taclab/music-box/blob/main/lib/PN532/llcp.h"
    click Protocol "https://github.com/taclab/music-box/blob/main/lib/PN532/snep.cpp"
    click Protocol "https://github.com/taclab/music-box/blob/main/lib/PN532/snep.h"
```
