architecture

Architectural principles

• This document outlines the fundamental architectural principles and patterns for the muster codebase. Adherence to these guidelines is mandatory to maintain a clean, decoupled, and testable system.

The API Service Locator Pattern

• All inter-package communication MUST go through the central API layer. This is the most critical rule in our architecture. It prevents direct coupling between packages, enabling them to be developed, tested, and refactored independently.

Core Concepts

• Central API: The internal/api package acts as a service locator. It contains handlers for all core muster functionality and also the tool definitions exposed by the aggregator package.
• Interface-Driven: Packages communicate using interfaces defined in internal/api/handlers.go. They do not know about each other's concrete implementations.
• One-Way Dependency: All packages can depend on internal/api, but internal/api depends on no other package in the project. This is crucial for preventing circular dependencies.

Define Interface in API: Add a new handler interface to internal/api/handlers.go.

// internal/api/handlers.go
type MyServiceHandler interface {
    DoSomething(ctx context.Context) error
}

Implement Adapter in Service Package: In the package providing the functionality (e.g., internal/myservice), create an api_adapter.go. This adapter implements the interface and calls the package's internal logic.

// internal/myservice/api_adapter.go
type Adapter struct {
    logic *ServiceLogic
}
func (a *Adapter) DoSomething(ctx context.Context) error {
    return a.logic.performAction(ctx)
}

Register the Adapter: Implement a Register() method on the adapter that calls the registration function in the api package.

// internal/myservice/api_adapter.go
func (a *Adapter) Register() {
    api.RegisterMyService(a)
}

Consume via API: Any other package that needs to use the service MUST retrieve the handler from the api package. It MUST NOT import the service package directly.

// in another_package/logic.go
import "github.com/giantswarm/muster/internal/api"

func DoWork(ctx context.Context) {
    handler := api.GetMyService()
    if handler == nil {
        // Handle case where service is not available
        return
    }
    handler.DoSomething(ctx)
}

Workflow executions

• From the user perspective workflows are executed via the tools workflow_<workflow-name>.
• In the workflows and api package these workflow execution tools are still called action_<workflow-name>.
• The aggregator maps the action_<workflow-name> tools to the actual workflow_<workflow-name>.

CRITICAL: Anti-Patterns

• NEVER import workflow, mcpserver, serviceclass and service packages directly. This creates tight coupling and violates the core architectural principle.
• NEVER USE TIMER/SLEEP/WAIT TO FIX TESTS OR RACE CONDITIONS. NEVER!!
• ALWAYS retrieve handlers from the api package.
• Don't change schema.json manually It is generated via muster test --generate-schema and changes are the result of the actual api of muster serve.

BDD test scenarios

• Execute test scenarios like this: muster test --scenario <scenario> --verbose
• Make sure muster is up to date: Use go install
• Always update muster after a code change in go
• There is no need to start muster serve: Each test scenario is executed in its own environment and its own instance of muster serve
• Always treat the scenario as the defined and supposed user behavior: If a scenario fails it is most likely a regression and the code needs to be fixed and not the scenario.
• To see debug messages during test scenario execution: You need to add a --debug flag: muster test --scenario <scenario> --verbose --debug
• Never ever stop or commit with failing test scenarios: You must fix them.