# floe-audio/floe architecture

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

- Interactive diagram: https://gitdiagram.com/floe-audio/floe
- Repository: https://github.com/floe-audio/floe

## Overview

- Build & Deployment System – Illustrate the Zig-based build system (build.zig, build.zig.zon) along with continuous integration/deployment workflows (.github/workflows). Note that the build system supports cross-compilation for multiple platforms.
- Core Infrastructure – Capture the “common_infrastructure” and “foundation” directories. These include modules for:
- Audio data handling and utilities
- Error reporting, global constants, and preferences management
- Custom containers, memory management, and platform-independent utilities (often replacing standard library functionality)
- OS and Platform Abstraction – Highlight the “os” directory responsible for filesystem, threading, and platform-specific implementations (Linux, macOS, Windows).
- Plugin and DSP Modules – Focus on the “plugin” directory, which breaks down into several submodules:
- Plugin Engine: Contains the core engine logic (autosave, shared_engine_systems, package installation)
- GUI Subsystem: Separates into “gui” and “gui_framework” components for the user interface, editor widgets, and live editing definitions
- DSP/Processor Components: Under “processor” and “processing_utils” for audio signal processing, various effects (delay, reverb, distortion, filter, etc.) and voice management
- Preset & Packaging: “preset_server” and “packager_tool” for managing sample libraries, loading preset data, and handling package installation
- State Management: “state” for instrument state encoding and snapshots
- Standalone Wrapper – “standalone_wrapper” represents the code to run Floe as a standalone app.
- Testing & Debugging – "tests" and "utils/debug" directories, as well as files supporting validation (e.g., clang-tidy, clang-format) which show a high focus on development reliability.
- Third-Party Libraries – The “third_party_libs” directory holds specialized libraries (e.g., FFTConvolver, vitfx) that support DSP, image handling, and other additional features.

##### Relationships and Interactions
- From the Core Infrastructure and Foundation modules, show dependencies feeding into both the Plugin Engine and DSP modules, emphasizing these lower-level components as the foundation for higher-level functionality (e.g., shared utility functions, containers, and error handling).
- OS abstractions to both the Core Infrastructure (for platform independent file I/O, threading, etc.) and UI subsystems, showing how each platform-specific implementation is abstracted away.
- Link the Plugin Engine, GUI, and DSP/Processor groups together to highlight the flow from audio input processing to UI interactions and state management. For example, the Plugin Engine coordinates with the DSP-specific processor modules, while concurrently providing status and parameter updates to the GUI.
- That the Preset Server and Packager Tool interact with the sample library systems, both in the core code (“sample_library” under common_infrastructure) and within plugin-specific code.

##### Architectural Patterns and Design Principles
- Modularity, showing clear separation between raw audio processing, frontend (GUI), and backend (engine state management, packaging).
- Layered abstraction: low-level utilities (foundation, os) support domain-specific modules (DSP processing, plugin engine, GUI).
- That dependency management is manual and performance-driven, justified by the absence of frameworks and minimal library usage.
- Use of continuous integration (CI) systems and extensive testing procedures to maintain backward-compatibility and robust platform support.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Deployment Subgraph
    subgraph "Build & Deployment"
        BS["Build System"]:::build
        CI["CI/CD Workflows"]:::build
    end

    %% Core Infrastructure and OS Abstraction Subgraph
    subgraph "Core Infrastructure & System Support"
        coreInfra["Core Infrastructure"]:::core
        OSAbs["OS & Platform Abstraction"]:::os
    end

    %% Plugin Modules Subgraph
    subgraph "Plugin & DSP Modules"
        Engine["Plugin Engine"]:::plugin
        GUI["GUI Subsystem"]:::plugin
        DSP["DSP/Processor Components"]:::plugin
        Preset["Preset & Packaging"]:::plugin
        State["State Management"]:::plugin
    end

    %% Other Components Subgraph
    subgraph "Additional Components"
        Standalone["Standalone Wrapper"]:::standalone
        Testing["Testing & Debugging"]:::testing
        ThirdParty["Third-Party Libraries"]:::thirdparty
    end

    %% Connections between Build & Deployment and Core Infrastructure
    BS -->|"compiles"| coreInfra
    CI -->|"triggers"| coreInfra
    BS -->|"initiates"| Testing
    CI -->|"verifies"| Testing

    %% OS Abstraction connections
    OSAbs -->|"supports"| coreInfra
    OSAbs -->|"interfaces with"| GUI

    %% Core Infrastructure dependencies
    coreInfra -->|"provides utilities to"| Engine
    coreInfra -->|"supplies sample library to"| Preset

    %% Plugin Modules interactions
    Engine -->|"processes audio in"| DSP
    Engine -->|"updates"| GUI
    Engine -->|"manages state in"| State
    Engine -->|"integrates with"| Standalone

    %% Third-Party Libraries support
    ThirdParty -->|"enhances"| DSP
    ThirdParty -->|"assists"| GUI
    ThirdParty -->|"augments"| Engine

    %% Click Events for Build & Deployment
    click BS "https://github.com/floe-audio/floe/blob/main/build.zig"
    click BS "https://github.com/floe-audio/floe/blob/main/build.zig.zon"
    click CI "https://github.com/floe-audio/floe/tree/main/.github/workflows/"

    %% Click Events for Core Infrastructure
    click coreInfra "https://github.com/floe-audio/floe/tree/main/src/common_infrastructure"
    click coreInfra "https://github.com/floe-audio/floe/tree/main/src/foundation"

    %% Click Event for OS Abstraction
    click OSAbs "https://github.com/floe-audio/floe/tree/main/src/os"

    %% Click Event for Plugin Engine
    click Engine "https://github.com/floe-audio/floe/tree/main/src/plugin/engine"

    %% Click Events for GUI Subsystem
    click GUI "https://github.com/floe-audio/floe/tree/main/src/plugin/gui"
    click GUI "https://github.com/floe-audio/floe/tree/main/src/plugin/gui_framework"

    %% Click Events for DSP/Processor Components
    click DSP "https://github.com/floe-audio/floe/tree/main/src/plugin/processing_utils"
    click DSP "https://github.com/floe-audio/floe/tree/main/src/plugin/processor"

    %% Click Events for Preset & Packaging
    click Preset "https://github.com/floe-audio/floe/tree/main/src/plugin/preset_server"
    click Preset "https://github.com/floe-audio/floe/tree/main/src/packager_tool"

    %% Click Event for State Management
    click State "https://github.com/floe-audio/floe/tree/main/src/plugin/state"

    %% Click Event for Standalone Wrapper
    click Standalone "https://github.com/floe-audio/floe/tree/main/src/standalone_wrapper"

    %% Click Events for Testing & Debugging
    click Testing "https://github.com/floe-audio/floe/tree/main/src/tests"
    click Testing "https://github.com/floe-audio/floe/tree/main/src/utils/debug"
    click Testing "https://github.com/floe-audio/floe/blob/main/.clang-format"
    click Testing "https://github.com/floe-audio/floe/blob/main/.clang-tidy"

    %% Click Event for Third-Party Libraries
    click ThirdParty "https://github.com/floe-audio/floe/tree/main/third_party_libs"

    %% Class Definitions for Color Styling
    classDef build fill:#ffcccc,stroke:#b30000,stroke-width:2px;
    classDef core fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef os fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef plugin fill:#e6ccff,stroke:#5a189a,stroke-width:2px;
    classDef standalone fill:#ccf2ff,stroke:#0077b6,stroke-width:2px;
    classDef testing fill:#fff5cc,stroke:#b58900,stroke-width:2px;
    classDef thirdparty fill:#e0ccff,stroke:#6f42c1,stroke-width:2px;
```
