# joaoreisa/guitar_tuner architecture

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

- Interactive diagram: https://gitdiagram.com/joaoreisa/guitar_tuner
- Repository: https://github.com/joaoreisa/guitar_tuner

## Overview

##### Project type and purpose
- This is a Go-based command-line interface (CLI) application whose sole purpose is to turn your terminal into a real-time guitar tuner.
- It captures live audio from your microphone, runs an FFT-based frequency analysis pipeline, maps the dominant frequency to a musical note, and displays a styled, interactive CLI using BubbleTea/Lipgloss.

##### File structure
- Top level:
- main.go: application entry point
- cmd/: Cobra command definitions (root.go, tune.go)
- internal/: code organized by clean-architecture layers
– internal/data/service: audio_input.go (PortAudio adapter)
– internal/domain/entities & usecase: core music theory logic (notes & frequency mapping)
– internal/presentation: BubbleTea model & Lipgloss styles
- utils/: cross-cutting helpers (e.g., FFT wrapper, window functions)
- bin/: compiled binary location
- go.mod/go.sum, README.md, LICENSE, .vscode

##### Key insights from README
- Uses Cobra for CLI commands (`tune` command)
- Uses PortAudio for low-level audio capture
- Audio pipeline: normalize → Hanning window → FFT → extract fundamental frequency
- Uses domain logic to map frequency to nearest guitar note
- BubbleTea drives the interactive state loop, Lipgloss handles styling

##### Main components
a. Entrypoint/CLI Layer
- Cobra’s root and tune commands in cmd/
b. Audio Capture Adapter
- PortAudio stream (internal/data/service/audio_input.go)
c. Audio Processing Pipeline
- Utils module: normalization, windowing, FFT
d. Domain Core
- Entities: Note, NoteSymbol enum
- Usecases: frequency → note calculation
e. Presentation Adapter
- BubbleTea model, Lipgloss styling (internal/presentation)
f. External Dependencies
- PortAudio native library
- Third-party Go modules (Cobra, BubbleTea, Lipgloss)

##### Relationships and data flow
1. User invokes `guitar_tuner tune` (CLI layer)
2. CLI layer calls Audio Capture Adapter
3. PortAudio pushes raw PCM buffer → sent to Audio Processing Pipeline
4. FFT library processes buffer → outputs dominant frequency
5. Frequency passed to Domain Core usecase → returns note entity
6. Domain result forwarded to Presentation Adapter → updates CLI UI
7. Loop back to step 2 until user quits

##### Architectural patterns and design principles
- Clean/Hexagonal architecture: separation between domain core and external adapters
- Single Responsibility: each package (data, domain, presentation, utils) owns a distinct concern
- Dependency Inversion: domain layer has no imports from data/presentation
- Event loop pattern (BubbleTea) in presentation

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI Layer"
        Main["main.go"]:::cli
        Root["cmd/root.go"]:::cli
        Tune["cmd/tune.go"]:::cli
    end

    %% Audio Capture Adapter
    subgraph "Audio Capture Adapter"
        AudioInput["audio_input.go"]:::adapter
    end

    %% Audio Processing Pipeline
    subgraph "Audio Processing Pipeline"
        Utils["utils.go\n(normalize, window, FFT)"]:::service
    end

    %% Domain Core
    subgraph "Domain Core"
        subgraph Entities
            NoteEnt["note.go"]:::domain
            Enum["notes_symbol_enum.go"]:::domain
        end
        subgraph Usecases
            Freq["frequencies.go"]:::domain
            NoteFromFreq["note_from_frequency.go"]:::domain
        end
    end

    %% Presentation Adapter
    subgraph "Presentation Adapter"
        Model["model.go"]:::ui
        Style["style.go"]:::ui
    end

    %% External Dependencies
    subgraph "External Dependencies"
        PortAudio["PortAudio Native"]:::external
        Cobra["Cobra"]:::external
        BubbleTea["BubbleTea"]:::external
        Lipgloss["Lipgloss"]:::external
    end

    %% Data Flow
    Main -->|"invoke tune"| Root
    Root -->|"execute tune command"| Tune
    Tune -->|"start audio capture"| AudioInput
    AudioInput -->|"Raw PCM buffer"| Utils
    Utils -->|"Dominant frequency"| Freq
    Freq -->|"compute note"| NoteFromFreq
    NoteFromFreq -->|"Note entity"| Model
    Model -->|"render UI"| Style
    Style -->|"update terminal"| Tune
    %% Loop
    Style -->|"continue loop"| AudioInput

    %% Internal Dependencies
    Freq -->|"uses"| NoteEnt
    Freq -->|"uses"| Enum

    %% External Dependencies Connections
    AudioInput -->|"uses"| PortAudio
    Root -->|"uses"| Cobra
    Model -->|"uses"| BubbleTea
    Style -->|"uses"| Lipgloss

    %% Click Events
    click Main "https://github.com/joaoreisa/guitar_tuner/blob/main/main.go"
    click Root "https://github.com/joaoreisa/guitar_tuner/blob/main/cmd/root.go"
    click Tune "https://github.com/joaoreisa/guitar_tuner/blob/main/cmd/tune.go"
    click AudioInput "https://github.com/joaoreisa/guitar_tuner/blob/main/internal/data/service/audio_input.go"
    click Utils "https://github.com/joaoreisa/guitar_tuner/blob/main/utils/utils.go"
    click NoteEnt "https://github.com/joaoreisa/guitar_tuner/blob/main/internal/domain/entities/note.go"
    click Enum "https://github.com/joaoreisa/guitar_tuner/blob/main/internal/domain/entities/notes_symbol_enum.go"
    click Freq "https://github.com/joaoreisa/guitar_tuner/blob/main/internal/domain/usecase/frequencies.go"
    click NoteFromFreq "https://github.com/joaoreisa/guitar_tuner/blob/main/internal/domain/usecase/note_from_frequency.go"
    click Model "https://github.com/joaoreisa/guitar_tuner/blob/main/internal/presentation/model.go"
    click Style "https://github.com/joaoreisa/guitar_tuner/blob/main/internal/presentation/style.go"

    %% Styles
    classDef cli fill:#FFA500,stroke:#333,color:#000
    classDef adapter fill:#90EE90,stroke:#333,color:#000
    classDef service fill:#98FB98,stroke:#333,color:#000
    classDef domain fill:#ADD8E6,stroke:#333,color:#000
    classDef ui fill:#FFD580,stroke:#333,color:#000
    classDef external fill:#D3D3D3,stroke:#333,color:#000
```
