# magicbowen/muse architecture

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

- Interactive diagram: https://gitdiagram.com/magicbowen/muse
- Repository: https://github.com/magicbowen/muse

## Overview

##### Project Type and Purpose
- The README and file structure confirm that muse is a C++‐based promise system for testing. It is built with CMake and uses Google Test (gtest) for unit testing.
- The project includes a DSL (domain-specific language) component (with files such as Promise.g4, PromiseSyntaxVisitor.cpp, and Python syntax files) that likely helps parse and translate promise expressions.
- Overall, muse appears to function as a core engine that uses promises, facts, events, and a DSL interface to facilitate complex testing scenarios.

##### File Structure
- The top-level “code” directory contains the core implementation, split into subdirectories under include, src, and test:
- “code/include/muse” contains headers for various modules: base classes (logging, state management, etc.), DSL, event, fact, listener, predicate, and promise.
- “code/src” contains the corresponding implementations for these modules.
- The “code/deps/rapidjson” directory hints at the use of rapidjson – likely for configuration or JSON-based promise definitions.
- The “code/test” directory houses test cases using gtest, and even a “fakefact” test module to simulate fact behavior.
- The “dsl” directory holds grammar specifications (Promise.g4) plus separate C++ and Python syntax implementations. This implies that the DSL is a first‑class part of the system, translating human‑readable promise definitions into the underlying test system.
- The “project/build.sh” script (in the project subdirectory) and related CMakeLists.txt files define the build and deployment process.

A. Main Components:
- Muse Core Library:
- Base Module: Contains utilities, logging, singleton management, etc. (found in code/include/muse/base and code/src/base).
- Fact Module: Manages fact definitions and state changes (code/include/muse/fact and code/src/fact).
- Event Module: Defines and handles events (code/include/muse/event).
- Promise Module: Implements various promise types (CompositePromise, ConcurrentPromise, etc. found in code/include/muse/promise and code/src/promise).
- Predicate Module: Helps to define conditions for promises (code/include/muse/pred).
- Listener Module: Provides hooks to listen to promise events (code/include/muse/listener).

- DSL Component:
- Grammar & Parser: Defined in “dsl/Promise.g4” for the DSL syntax.
- C++ and Python Syntax Implementations: Located in “dsl/cpp-syntax” and “dsl/py-syntax”, including visitor and translator classes.
- Test Cases for DSL: Found in “dsl/testcase” which help validate the syntax and translation.

- Dependencies and External Services:
- rapidjson: Used as a third-party dependency for JSON processing, integrated via the “code/deps/rapidjson” folder.
- Google Test (gtest): For unit tests (as instructed in the README).

- Build and Deployment:
- Build System: CMake build scripts (found in various CMakeLists.txt files) along with the build.sh script in the “project” directory.

- Test Harness:
- Test cases are provided in “code/test”, simulating aspects like promise execution, DSL usage, and fake fact/event generation.

B. Relationships and Interactions:
- The Muse Core Library is the central component that handles promises, events, and facts during test execution.
- The DSL component interacts with the Muse Core by accepting high‑level human-readable promise definitions and translating them into actual promise, fact, and event constructs that the core library can execute.
- The rapidjson dependency supports configuration or structured data exchanges between components.
- The Test Harness uses Google Test to run tests across the Muse modules and DSL translation logic.
- The build system ties all these parts together during compile‑time, ensuring that dependencies (e.g., rapidjson and gtest) are correctly integrated.

C. Architectural Patterns and Design Principles:
- Modular Design: Each major functionality (promise handling, DSL parsing, event and fact management) is separated into clear modules.
- Separation of Concerns: The DSL parser module is isolated from the execution engine, and the test code is separated from core business logic.
- Extensibility: The presence of helper classes (like various PromiseHelper and PredHelper classes) suggests that the system is built to be extended with new promise types or fact definitions.

## Diagram (Mermaid)

```mermaid
graph TD
    %% DSL Component Layer
    subgraph "DSL Component"
        DSL_Grammar["Grammar & Parser"]:::dsl
        DSL_CPP["C++ Syntax Implementation"]:::dsl
        DSL_Py["Python Syntax Implementation"]:::dsl
    end

    %% Test Harness Node
    TH["Test Harness (gtest)"]:::test

    %% Muse Core Library Layer
    subgraph "Muse Core Library"
        Core_Base["Base Module"]:::core
        Core_Fact["Fact Module"]:::core
        Core_Event["Event Module"]:::core
        Core_Promise["Promise Module"]:::core
        Core_Pred["Predicate Module"]:::core
        Core_Listener["Listener Module"]:::core
    end

    %% Build & External Dependencies Layer
    subgraph "Build & External"
        BuildSys["Build & Deployment"]:::build
        RapidJSON["rapidjson"]:::external
    end

    %% DSL Component internal connections
    DSL_CPP -->|"supports"| DSL_Grammar
    DSL_Py  -->|"supports"| DSL_Grammar

    %% DSL to Core interactions
    DSL_Grammar -->|"translates"| Core_Promise
    DSL_Grammar -->|"translates"| Core_Fact

    %% Test Harness testing core modules
    TH -->|"tests"| Core_Base
    TH -->|"tests"| Core_Fact
    TH -->|"tests"| Core_Event
    TH -->|"tests"| Core_Promise
    TH -->|"tests"| Core_Pred
    TH -->|"tests"| Core_Listener

    %% External dependency usage
    RapidJSON -->|"used_by"| Core_Promise

    %% Build system builds components
    BuildSys -->|"builds"| DSL_Grammar
    BuildSys -->|"builds"| DSL_CPP
    BuildSys -->|"builds"| DSL_Py
    BuildSys -->|"builds"| Core_Base
    BuildSys -->|"builds"| Core_Fact
    BuildSys -->|"builds"| Core_Event
    BuildSys -->|"builds"| Core_Promise
    BuildSys -->|"builds"| Core_Pred
    BuildSys -->|"builds"| Core_Listener
    BuildSys -->|"builds"| TH

    %% Class Definitions
    classDef core fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef dsl fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef external fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef build fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef test fill:#D2B4DE,stroke:#5B2C6F,stroke-width:2px;

    %% Click Events
    click Core_Base "https://github.com/magicbowen/muse/tree/master/code/include/muse/base"
    click Core_Fact "https://github.com/magicbowen/muse/tree/master/code/include/muse/fact"
    click Core_Event "https://github.com/magicbowen/muse/tree/master/code/include/muse/event"
    click Core_Promise "https://github.com/magicbowen/muse/tree/master/code/include/muse/promise"
    click Core_Pred "https://github.com/magicbowen/muse/tree/master/code/include/muse/pred"
    click Core_Listener "https://github.com/magicbowen/muse/tree/master/code/include/muse/listener"
    click DSL_Grammar "https://github.com/magicbowen/muse/blob/master/dsl/Promise.g4"
    click DSL_CPP "https://github.com/magicbowen/muse/blob/master/dsl/cpp-syntax/PromiseSyntaxVisitor.cpp"
    click DSL_Py "https://github.com/magicbowen/muse/blob/master/dsl/py-syntax/PromiseLexer.py"
    click RapidJSON "https://github.com/magicbowen/muse/tree/master/code/deps/rapidjson"
    click TH "https://github.com/magicbowen/muse/tree/master/code/test"
    click BuildSys "https://github.com/magicbowen/muse/blob/master/project/build.sh"
```
