# plugine/yyds architecture

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

- Interactive diagram: https://gitdiagram.com/plugine/yyds
- Repository: https://github.com/plugine/yyds

## Overview

##### Project Type and Purpose
- The README makes it clear that the project's goal is to function as a professional text music editor.
- It implements a custom music-description language (DSL) where users define patterns, tempo, tracks, and musical notations.
- The project parses these DSL files and plays music via sine wave generation and an external audio library (oto).
- This is a command-line application that integrates language parsing, music processing, and audio playback in a modular design.

##### Analysis of File Structure
- The top-level structure includes standard configuration files (.gitignore, go.mod, go.sum) along with directories for the code (cmd, internal) and examples (example, pics).
- The cmd/yyds folder contains the main entry point (main.go), indicating where the program is initiated.
- Under the internal directory:
- The "parser" subdirectory contains the DSL’s grammar file (Music.g4) and the generated (and handwritten) parsing code (lexer, parser, listeners, tests). This indicates use of a parser generator (ANTLR 4) to transform the DSL into an abstract syntax tree.
- The "music" subdirectory holds the code for music processing (frequency calculation, music synthesis, sine wave generation). This represents the core logic for audio signal generation.
- The example folder provides sample DSL files to test and demonstrate the music language.

##### Main Components
A. CLI / Application Entry Point:
- Represented by cmd/yyds/main.go.
- It is responsible for reading the input DSL file (e.g., example/shutdown.yyds) and coordinating the overall workflow.

B. Parser Module:
- Located under internal/parser.
- Components include:
- The DSL grammar (Music.g4)
- Generated lexer, parser, and listener code that processes the music DSL.
- This module converts the text-based music instructions into a structured abstract representation (likely an AST or similar data structure).

C. Music Processing Module:
- Located under internal/music.
- Handles conversion of parsed music instructions into frequency data, synthesizes notes, creates sine waves, and (potentially) adds harmonics.
- Implements the audio logic that is later fed into the audio output system.

D. Audio Playback Integration:
- Although there is no dedicated internal package, the README highlights that the project leverages the "oto" library.
- External dependency towards oto and indicate that it is used to route the processed audio data to the sound hardware.

##### Relationships and Data Flow
- The CLI (main.go) receives a DSL file and feeds its content to the Parser Module.
- The Parser Module, using the ANTLR-generated components, processes the DSL content and produces an internal representation of the music.
- The Music Processing Module takes the parsed representation and computes the musical parameters (tempo, note frequencies, timings) via its functions (e.g., using sine_wave.go, freq.go).
- The processed audio data is then sent to the oto audio playback library, which handles low-level audio output.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The application cleanly divides responsibilities between the command-line interface, parsing of the DSL, and audio synthesis.
- Modular Design: Each internal component (parser and music processing) is encapsulated in its own directory, allowing for easier maintenance and potential reusability.
- Extensibility: The TODOLIST indicates plans for extending instrument support, so the modular design should accommodate future addition of new sound generation modules or external integrations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Input"
        EX["Sample DSL Files (example)"]:::inputStyle
    end

    subgraph "Application"
        CLI["Main Program (cmd/yyds/main.go)"]:::cliStyle
    end

    subgraph "Processing"
        PARSER["DSL Parser (internal/parser)\nMusic.g4, lexer, parser, listeners"]:::parserStyle
        MUSIC["Music Processing/Synthesis (internal/music)\nfreq.go, music.go, sine_wave.go"]:::musicStyle
    end

    subgraph "Output"
        OTO["Audio Playback (oto)"]:::externalStyle
    end

    EX -->|"ProvideDSLInput"| CLI
    CLI -->|"PassDSLInput"| PARSER
    PARSER -->|"ParsedMusicData"| MUSIC
    MUSIC -->|"AudioSignalData"| OTO

    %% Annotation indicating parser regeneration via ANTLR when grammar changes
    PARSER ---|"RegenerateParserUsingANTLRIfGrammarChanges"| PARSER

    %% Click Events
    click CLI "https://github.com/plugine/yyds/blob/master/cmd/yyds/main.go"
    click PARSER "https://github.com/plugine/yyds/tree/master/internal/parser"
    click MUSIC "https://github.com/plugine/yyds/tree/master/internal/music"
    click EX "https://github.com/plugine/yyds/tree/master/example"

    %% Style Definitions
    classDef cliStyle fill:#f9e79f,stroke:#f39c12,stroke-width:2px;
    classDef parserStyle fill:#aed6f1,stroke:#3498db,stroke-width:2px;
    classDef musicStyle fill:#d5f5e3,stroke:#28b463,stroke-width:2px;
    classDef externalStyle fill:#f5b7b1,stroke:#e74c3c,stroke-width:2px;
    classDef inputStyle fill:#d7bde2,stroke:#8e44ad,stroke-width:2px;
```
