# bull313/musika architecture

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

- Interactive diagram: https://gitdiagram.com/bull313/musika
- Repository: https://github.com/bull313/musika

## Overview

Based on our review of the complete file tree and the extensive README, the Musika project is a specialized desktop application for a custom music programming language. The project implements both a compiler (which translates Musika code in .ka files first into a note sheet binary and then into an audible .wav file) and an associated IDE. It is built in C# (as seen by the .cs files) with a clear separation of concerns between the language processing engine (lexer, parser, compiler, runtime, etc.) and the IDE/user interface portions.

##### Main Components
- Compiler Core – This module resides in dev/src/lang and contains components such as the LexicalAnalyzer, Parser, Compiler, RuntimeEnvironment, and data/serialization routines for creating WAV files. It also handles error scenarios (ContextError, SyntaxError, etc.) and supports the two-step conversion process.
- Integrated Development Environment (IDE) – Under dev/src/ide you have the UI, configuration files (App.config), and script files (MainWindow.xaml.cs, App.xaml.cs). This part handles file editing, syntax highlighting toggling, and compilation controls from the IDE menu.
- Standard Library & Accompaniments – The standard library files (in dev/src/lang/stdlib and various accompanied files under dev/vs/project) include ready-made patterns, chords, scales, double stops, power chords, etc. They are treated as importable modules that the core compiler uses.
- Testing and Samples – The dev/test directory contains various Musika language test files (.ka) for compiler and syntax testing, while sample_files provide example songs; both are useful to show test harness and example-driven usage.
- Project Configuration & Build - The vs and project folders contain Visual Studio solution and project files (e.g., MusikaIDE.csproj, compiler.csproj) to manage builds and dependencies.

##### Relationships and Data Flow
- Input flows from a .ka text file (written manually or via the IDE) into the Compiler Core.
- The compiler first converts the code to a note sheet binary (.mkc) and then to an audio .wav file.
- The IDE acts as a front-end editor and build controller, invoking the compiler’s two-step process. It also supports direct play of the resulting audio.
- Standard libraries and accompanied patterns/chords are imported during parsing and influence music generation.
- Testing frameworks (using sample programs and tests) verify behavior in the language nodes.

##### Architectural Patterns & Design Principles
- Separation of Concerns: The compilation logic (lexer, parser, note sheet building, WAV construction) is kept separate from UI and configuration tasks.
- Modular Design: The project splits the language processing into distinct modules (lexing, parsing, serialization) and supports extensibility via standard libraries and accompaniment files.
- MVC-Style/Command Pattern in IDE: Although not strictly MVC, the distinct roles (presentation in UI, processing in compiler, user interactions via commands – build, play, etc.) suggest a layered architecture.

##### Technologies & Frameworks
- C#/.NET (WPF is indicated by XAML files for the UI).
- XML (used for configuration files and note frequency data).
- Visual Studio solution architecture that separates projects (IDE and compiler).

##### Final Details
- Labels that denote configuration and runtime files (like App.config under IDE, note_frequency.xml under data).
- Extensibility – the ability to import and reference additional chords and patterns from accompanied files.

Happy diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Main Components
    IDE["Integrated Development Environment"]:::ide
    CompilerCore["Compiler Core"]:::compiler
    StdLib["Standard Library & Accompaniments"]:::library
    Testing["Testing"]:::test
    Samples["Samples"]:::test
    ProjectConfig["Project Configuration & Build"]:::config

    %% Subgraph for Compiler Core Modules
    subgraph "Compiler Core Modules"
        LC["Lexical Analyzer"]:::compiler
        PAR["Parser"]:::compiler
        COMP["Compiler"]:::compiler
        SER["Serializer"]:::compiler
        WAV["WAV Constructor"]:::compiler
        RE["Runtime Environment"]:::compiler
        CE["Context Error"]:::error
        SE["Syntax Error"]:::error
        WE["WAVConstructionError"]:::error
    end

    %% Internal connections within Compiler Core Modules
    LC -->|"analyzes"| PAR
    PAR -->|"parses"| COMP
    COMP -->|"calls serialization"| SER
    SER -->|"builds note sheet"| WAV
    WAV -->|"generates audio"| RE
    PAR -->|"throws"| CE
    PAR -->|"throws"| SE
    WAV -->|"throws"| WE

    %% Subgraph for IDE Components
    subgraph "IDE Components"
        UI["UI Layer"]:::ide
        Scripts["Code-Behind Scripts"]:::ide
        Config["Configuration"]:::ide
    end
    UI -->|"controls"| Scripts
    UI -->|"loads"| Config

    %% Data Flow between Main Components
    IDE -->|"sends .ka files"| CompilerCore
    CompilerCore -->|"imports modules"| StdLib
    CompilerCore -->|"produces .wav file"| IDE
    Testing -->|"runs compiler tests"| CompilerCore
    Samples -->|"provides sample .ka files"| CompilerCore
    ProjectConfig -->|"builds project for"| IDE
    ProjectConfig -->|"builds project for"| CompilerCore

    %% Click Events for Component Mapping
    click CompilerCore "https://github.com/bull313/musika/tree/master/dev/src/lang"
    click IDE "https://github.com/bull313/musika/tree/master/dev/src/ide"
    click StdLib "https://github.com/bull313/musika/tree/master/dev/src/lang/stdlib"
    click Testing "https://github.com/bull313/musika/tree/master/dev/test/lang"
    click Samples "https://github.com/bull313/musika/tree/master/sample_files"
    click ProjectConfig "https://github.com/bull313/musika/tree/master/dev/vs/project"

    %% Styles
    classDef compiler fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef ide fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef library fill:#C8E6C9,stroke:#388E3C,stroke-width:2px;
    classDef test fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef config fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
    classDef error fill:#FADBD8,stroke:#943126,stroke-width:2px;
```
