# looplab/fsm architecture

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

- Interactive diagram: https://gitdiagram.com/looplab/fsm
- Repository: https://github.com/looplab/fsm

## Overview

##### Project Type and Purpose
- This is a Go library that implements a Finite State Machine (FSM). It exposes an API that lets users define states, events (transitions), and callbacks. It’s designed as an embeddable component for managing state transitions in Go applications.

##### File Structure and Architectural Modules
- Key source files like fsm.go and errors.go encapsulate the core logic.
- Event handling and transition management are implemented in fsm.go along with error management (errors.go and its accompanying test file).
- There are dedicated visualizer files (graphviz_visualizer.go, mermaid_visualizer.go, and a generic visualizer.go) that suggest separate components for generating visual representations of state machines.
- The project includes examples demonstrating various use cases (such as alternate transition systems, asynchronous context management, and structural integration) that guide how the FSM integrates with user code.
- The tests (fsm_test.go, errors_test.go, visualizer tests, etc.) ensure that the core logic behaves as expected.

a. Main Components:
- FSM Core Module: Represented by fsm.go which defines the FSM struct, its state, event handling, and transition logic.
- Event & Transition Manager: Part of the core FSM logic where events are defined (name, source states, destination state) and transitions are executed.
- Callback/Observer Module: Represents the callbacks configured to run upon state transitions (as seen in the usage examples with “enter_state”).
- Error Handling: Captured in errors.go, handling edge cases or invalid state transitions.
- Auxiliary Modules: Additional support components like uncancel_context modules which may influence asynchronous transition management.

b. Interactions and Data Flow:
- Transition path from the current state through the following phases: checking valid transitions → executing callbacks → updating state.
- “Examples” as demo usage scenarios that show external callers interacting with the FSM.

##### Architectural Patterns and Principles
- Modular Design: Core FSM logic is separated from visual representations and error handling.
- Observer/Callback Pattern: Callbacks are used to notify when state changes occur.
- Interface Abstraction: The design provides a clear API that user code interfaces with, hiding internal state management.

##### In Summary
- Branch out:
+ To the Event Manager, which manages events and state transitions.
+ To the Callback Handler, which listens for state changes.
+ To the Error Manager, dealing with invalid transitions.
+ To the Visualizer modules that convert FSM configurations to visual formats.
- Overlay additional context such as asynchronous cancellation support (if relevant) and note where examples in the “examples” folder illustrate usage.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Interaction"
        ex["Examples/Demo Usage (examples)"]:::examples
    end

    subgraph "Core Engine"
        f1["FSM Core (fsm.go)"]:::core
        ev["Event Manager (fsm.go, event.go)"]:::event
        cb["Callback Handler (fsm.go)"]:::callback
        err["Error Handler (errors.go)"]:::error
    end

    subgraph "Visualization Modules"
        gv["Graphviz Visualizer (graphviz_visualizer.go)"]:::visualizer
        mer["Mermaid Visualizer (mermaid_visualizer.go)"]:::visualizer
        gen["Generic Visualizer (visualizer.go)"]:::visualizer
    end

    subgraph "Support"
        ac["Asynchronous Cancellation Support (uncancel_context.go)"]:::async
    end

    ex -->|"triggers"| f1
    f1 -->|"processesEvent"| ev
    ev -->|"executesCallback"| cb
    ev -->|"onError"| err
    f1 -->|"generatesDiagram"| gv
    f1 -->|"generatesDiagram"| mer
    f1 -->|"generatesDiagram"| gen
    f1 -->|"handlesAsync"| ac

    click f1 "https://github.com/looplab/fsm/blob/main/fsm.go"
    click ev "https://github.com/looplab/fsm/blob/main/event.go"
    click cb "https://github.com/looplab/fsm/blob/main/fsm.go"
    click err "https://github.com/looplab/fsm/blob/main/errors.go"
    click gv "https://github.com/looplab/fsm/blob/main/graphviz_visualizer.go"
    click mer "https://github.com/looplab/fsm/blob/main/mermaid_visualizer.go"
    click gen "https://github.com/looplab/fsm/blob/main/visualizer.go"
    click ac "https://github.com/looplab/fsm/blob/main/uncancel_context.go"
    click ex "https://github.com/looplab/fsm/tree/main/examples/"

    classDef core fill:#a2d2ff,stroke:#000,stroke-width:2px;
    classDef event fill:#caffbf,stroke:#000,stroke-width:2px;
    classDef callback fill:#ffb7b2,stroke:#000,stroke-width:2px;
    classDef error fill:#ffadad,stroke:#000,stroke-width:2px;
    classDef visualizer fill:#ffd6a5,stroke:#000,stroke-width:2px;
    classDef async fill:#c9c9ff,stroke:#000,stroke-width:2px;
    classDef examples fill:#baffc9,stroke:#000,stroke-width:2px;
```
