# darkgraycat/bleeder architecture

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

- Interactive diagram: https://gitdiagram.com/darkgraycat/bleeder
- Repository: https://github.com/darkgraycat/bleeder

## Overview

#### Purpose and Entry Points
Bleeder is a Go-based live-coding/audio-generation system: it reads “bleed” source files, parses a music-oriented DSL, builds an intermediate representation, renders audio, and can play WAV output. The executable entry point is `main.go`; CLI construction and command context live in `cmd/cmd.go`, `cmd/cfg.go`, and `cmd/ctx.go`.

Example DSL inputs are stored under `bleeds/`, including `bleeds/aelin.practice.toml` and `bleeds/just_playing.toml`.

#### CLI and Execution Context
The command layer owns process-level configuration and dispatch into the core engine. `cmd/cfg.go` and root `config.toml` establish configuration boundaries, while `cmd/ctx.go` appears to carry shared execution context between CLI operations and runtime services.

The top-level control path is expected to be:
`main.go` → `cmd/` command setup → core Bleeder orchestration → parse/render/play stages.

#### Core Bleeder Orchestration
`internal/core/bleeder.go` is the principal application coordinator. It works with bleed inputs and their context through `internal/core/bleed.go` and `internal/core/bleedctx.go`. This is the main boundary between user-authored source/configuration and the compiler-like audio pipeline.

The core package is where parsing results, runtime options, and downstream renderer/player dependencies should be assembled rather than embedded in CLI commands.

#### DSL Parsing and IR Boundary
The repository has two parser implementations, `internal/core/parser.go` and `internal/core/parser2.go`, suggesting an evolving syntax model. Both feed the canonical intermediate representation in `internal/ir/ir.go`.

This IR is the key architectural contract: parsers translate bleed syntax into structured musical/audio instructions; renderers should consume IR rather than depend on source syntax. DSL intent and planned behavior are documented in `docs/aelin/dsl-design.md`, `docs/aelin/parser-design.md`, and `docs/aelin/syntax-model-v2.md`.

#### Audio Synthesis and Rendering
Audio-domain primitives are concentrated in `internal/audio/notes.go`, `internal/audio/waves.go`, and `internal/audio/wav.go`. These likely provide note/frequency handling, waveform generation, and WAV encoding.

Rendering is abstracted by `internal/renderer/renderer.go`, with WAV-specific implementation in `internal/renderer/wav_renderer.go`. The rendering boundary converts IR/audio instructions into a material audio artifact, keeping file-format concerns separate from parsing and orchestration.

#### Playback and Runtime Output
Playback is separated from rendering in `internal/player/player.go` and `internal/player/wav_player.go`. This permits a generated WAV artifact to be consumed by a player implementation independently of how it was synthesized.

The system therefore has a clear output chain: IR → renderer → WAV/audio output → player. Audio-device behavior, buffering, and streaming concerns are architecturally relevant and discussed in `docs/aelin/streaming-architecture.md` and `docs/aelin/buffer-drain-solution.md`.

#### Live-Coding Integration
The `extensions/bleeder-vscode/` package provides a VS Code integration, principally through `extensions/bleeder-vscode/extension.js`. It is an external editor-facing control surface rather than part of the Go runtime pipeline.

Supporting design documents, especially `docs/aelin/live-coding-architecture.md` and `LIVE_CODING_PLAN.md`, indicate that rapid source update, parse/rebuild, and audio-output lifecycle management are central future/runtime concerns.

Main entry points: [`internal/core/bleeder.go`](https://github.com/darkgraycat/bleeder/blob/main/internal/core/bleeder.go) (Bleeder coordinator), [`cmd/cmd.go`](https://github.com/darkgraycat/bleeder/blob/main/cmd/cmd.go) (Command setup), [`internal/renderer/wav_renderer.go`](https://github.com/darkgraycat/bleeder/blob/main/internal/renderer/wav_renderer.go) (WAV renderer), [`internal/renderer/renderer.go`](https://github.com/darkgraycat/bleeder/blob/main/internal/renderer/renderer.go) (Renderer abstraction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI & configuration"]
  node_main{{"Executable entry<br/>Go entry point<br/>[main.go]"}}
  node_commands["Command setup<br/>CLI commands<br/>[cmd.go]"]
  node_cli_config["CLI config<br/>configuration<br/>[cfg.go]"]
  node_command_context["Command context<br/>execution context<br/>[ctx.go]"]
  node_root_config["Root config<br/>configuration<br/>[config.toml]"]
end

subgraph group_core["Bleeder core"]
  node_bleeder{{"Bleeder coordinator<br/>application orchestration<br/>[bleeder.go]"}}
  node_bleed_input["Bleed source &amp; context<br/>source model<br/>[bleed.go]"]
  node_bleed_context["Bleed runtime context<br/>[bleedctx.go]"]
  node_parser["DSL parsers<br/>parser implementations<br/>[parser.go]"]
  node_bleed_examples["Bleed examples<br/>DSL inputs"]
end

subgraph group_pipeline["Audio pipeline"]
  node_ir["Music IR<br/>intermediate representation<br/>[ir.go]"]
  node_renderer["Renderer abstraction<br/>rendering interface<br/>[renderer.go]"]
  node_wav_renderer["WAV renderer<br/>renderer implementation<br/>[wav_renderer.go]"]
  node_audio_primitives["Audio primitives<br/>synthesis primitives<br/>[waves.go]"]
  node_wav_artifact["WAV output<br/>audio artifact<br/>[wav.go]"]
  node_player["Player abstraction<br/>playback interface<br/>[player.go]"]
  node_wav_player["WAV player<br/>player implementation<br/>[wav_player.go]"]
end

subgraph group_live["Live-coding surface"]
  node_vscode["VS Code extension<br/>editor integration<br/>[extension.js]"]
  node_live_design["Live-coding plan<br/>architecture plan"]
end

node_main -->|"starts"| node_commands
node_commands -->|"loads"| node_cli_config
node_commands -->|"creates"| node_command_context
node_cli_config -->|"uses"| node_root_config
node_commands -->|"dispatches to"| node_bleeder
node_bleed_examples -->|"provides"| node_bleed_input
node_bleeder -->|"reads"| node_bleed_input
node_bleeder -->|"establishes"| node_bleed_context
node_bleeder -->|"invokes"| node_parser
node_parser -->|"produces"| node_ir
node_bleeder -->|"orchestrates"| node_renderer
node_ir -->|"renders"| node_renderer
node_renderer -->|"implemented by"| node_wav_renderer
node_wav_renderer -->|"synthesizes with"| node_audio_primitives
node_audio_primitives -->|"encodes"| node_wav_artifact
node_wav_renderer -->|"writes"| node_wav_artifact
node_bleeder -->|"orchestrates"| node_player
node_player -->|"implemented by"| node_wav_player
node_wav_artifact -->|"plays"| node_wav_player
node_vscode -.->|"edits"| node_bleed_input
node_live_design -.->|"guides"| node_vscode

click node_main "https://github.com/darkgraycat/bleeder/blob/main/main.go"
click node_commands "https://github.com/darkgraycat/bleeder/blob/main/cmd/cmd.go"
click node_cli_config "https://github.com/darkgraycat/bleeder/blob/main/cmd/cfg.go"
click node_command_context "https://github.com/darkgraycat/bleeder/blob/main/cmd/ctx.go"
click node_root_config "https://github.com/darkgraycat/bleeder/blob/main/config.toml"
click node_bleeder "https://github.com/darkgraycat/bleeder/blob/main/internal/core/bleeder.go"
click node_bleed_input "https://github.com/darkgraycat/bleeder/blob/main/internal/core/bleed.go"
click node_bleed_context "https://github.com/darkgraycat/bleeder/blob/main/internal/core/bleedctx.go"
click node_parser "https://github.com/darkgraycat/bleeder/blob/main/internal/core/parser.go"
click node_ir "https://github.com/darkgraycat/bleeder/blob/main/internal/ir/ir.go"
click node_renderer "https://github.com/darkgraycat/bleeder/blob/main/internal/renderer/renderer.go"
click node_wav_renderer "https://github.com/darkgraycat/bleeder/blob/main/internal/renderer/wav_renderer.go"
click node_audio_primitives "https://github.com/darkgraycat/bleeder/blob/main/internal/audio/waves.go"
click node_wav_artifact "https://github.com/darkgraycat/bleeder/blob/main/internal/audio/wav.go"
click node_player "https://github.com/darkgraycat/bleeder/blob/main/internal/player/player.go"
click node_wav_player "https://github.com/darkgraycat/bleeder/blob/main/internal/player/wav_player.go"
click node_vscode "https://github.com/darkgraycat/bleeder/blob/main/extensions/bleeder-vscode/extension.js"
click node_live_design "https://github.com/darkgraycat/bleeder/blob/main/LIVE_CODING_PLAN.md"

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_main,node_commands,node_cli_config,node_command_context,node_root_config toneBlue
class node_bleeder,node_bleed_input,node_bleed_context,node_parser,node_bleed_examples toneAmber
class node_ir,node_renderer,node_wav_renderer,node_audio_primitives,node_wav_artifact,node_player,node_wav_player toneMint
class node_vscode,node_live_design toneRose
```

## Components

### CLI & configuration

- [Executable entry](https://github.com/darkgraycat/bleeder/blob/main/main.go): Go entry point · `main.go`
- [Command setup](https://github.com/darkgraycat/bleeder/blob/main/cmd/cmd.go): CLI commands · Builds commands, configuration, and execution context. · `cmd/cmd.go`
- [CLI config](https://github.com/darkgraycat/bleeder/blob/main/cmd/cfg.go): configuration · `cmd/cfg.go`
- [Command context](https://github.com/darkgraycat/bleeder/blob/main/cmd/ctx.go): execution context · `cmd/ctx.go`
- [Root config](https://github.com/darkgraycat/bleeder/blob/main/config.toml): configuration · `config.toml`

### Bleeder core

- [Bleeder coordinator](https://github.com/darkgraycat/bleeder/blob/main/internal/core/bleeder.go): application orchestration · Assembles parsing, rendering, and playback services. · `internal/core/bleeder.go`
- [Bleed source & context](https://github.com/darkgraycat/bleeder/blob/main/internal/core/bleed.go): source model · `internal/core/bleed.go`
- [Bleed runtime context](https://github.com/darkgraycat/bleeder/blob/main/internal/core/bleedctx.go): runtime context · `internal/core/bleedctx.go`
- [DSL parsers](https://github.com/darkgraycat/bleeder/blob/main/internal/core/parser.go): parser implementations · Two evolving parser implementations translate bleed syntax. · `internal/core/parser.go`
- **Bleed examples**: DSL inputs

### Audio pipeline

- [Music IR](https://github.com/darkgraycat/bleeder/blob/main/internal/ir/ir.go): intermediate representation · Canonical contract between DSL parsing and rendering. · `internal/ir/ir.go`
- [Renderer abstraction](https://github.com/darkgraycat/bleeder/blob/main/internal/renderer/renderer.go): rendering interface · `internal/renderer/renderer.go`
- [WAV renderer](https://github.com/darkgraycat/bleeder/blob/main/internal/renderer/wav_renderer.go): renderer implementation · Materializes rendered output as WAV. · `internal/renderer/wav_renderer.go`
- [Audio primitives](https://github.com/darkgraycat/bleeder/blob/main/internal/audio/waves.go): synthesis primitives · Notes, waveforms, and WAV encoding. · `internal/audio/waves.go`
- [WAV output](https://github.com/darkgraycat/bleeder/blob/main/internal/audio/wav.go): audio artifact · `internal/audio/wav.go`
- [Player abstraction](https://github.com/darkgraycat/bleeder/blob/main/internal/player/player.go): playback interface · `internal/player/player.go`
- [WAV player](https://github.com/darkgraycat/bleeder/blob/main/internal/player/wav_player.go): player implementation · `internal/player/wav_player.go`

### Live-coding surface

- [VS Code extension](https://github.com/darkgraycat/bleeder/blob/main/extensions/bleeder-vscode/extension.js): editor integration · External editor-facing control surface for live coding. · `extensions/bleeder-vscode/extension.js`
- [Live-coding plan](https://github.com/darkgraycat/bleeder/blob/main/LIVE_CODING_PLAN.md): architecture plan · Defines rapid update and audio lifecycle direction. · `LIVE_CODING_PLAN.md`

## Connections

- Executable entry → Command setup: starts
- Command setup → CLI config: loads
- Command setup → Command context: creates
- CLI config → Root config: uses
- Command setup → Bleeder coordinator: dispatches to
- Bleed examples → Bleed source & context: provides
- Bleeder coordinator → Bleed source & context: reads
- Bleeder coordinator → Bleed runtime context: establishes
- Bleeder coordinator → DSL parsers: invokes
- DSL parsers → Music IR: produces
- Bleeder coordinator → Renderer abstraction: orchestrates
- Music IR → Renderer abstraction: renders
- Renderer abstraction → WAV renderer: implemented by
- WAV renderer → Audio primitives: synthesizes with
- Audio primitives → WAV output: encodes
- WAV renderer → WAV output: writes
- Bleeder coordinator → Player abstraction: orchestrates
- Player abstraction → WAV player: implemented by
- WAV output → WAV player: plays
- VS Code extension → Bleed source & context: edits
- Live-coding plan → VS Code extension: guides