# koushikr/easy-fsm architecture

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

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

## Overview

easy-fsm is a small Java finite-state-machine library. A client defines a start state, event-driven transitions, and end states through MachineBuilder, then fires events with a Context; StateMachine looks up the matching transition and dispatches configured callbacks. It also validates state/transition completeness and routes runtime callback failures to an error handler. The graph focuses on this documented/runtime flow; the sampled source does not show callback implementations supplied by library consumers.

Main entry points: [`src/main/java/io/github/fsm/MachineBuilder.java`](https://github.com/koushikr/easy-fsm/blob/master/src/main/java/io/github/fsm/MachineBuilder.java) (MachineBuilder), [`src/main/java/io/github/fsm/StateMachine.java`](https://github.com/koushikr/easy-fsm/blob/master/src/main/java/io/github/fsm/StateMachine.java) (StateMachine), [`src/main/java/io/github/fsm/services/impl/TransitionServiceImpl.java`](https://github.com/koushikr/easy-fsm/blob/master/src/main/java/io/github/fsm/services/impl/TransitionServiceImpl.java) (Transition service), [`src/main/java/io/github/fsm/services/impl/StateManagementServiceImpl.java`](https://github.com/koushikr/easy-fsm/blob/master/src/main/java/io/github/fsm/services/impl/StateManagementServiceImpl.java) (State management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_configuration["Machine configuration"]
  node_builder["MachineBuilder"]
end

subgraph group_runtime["Event runtime"]
  node_machine["StateMachine<br/>[StateMachine.java]"]
  node_transitions["Transition service"]
  node_state_mgmt["State management"]
  node_actions["Action service"]
end

subgraph group_model["FSM model"]
  node_entities["FSM entities"]
  node_executors["Callback interfaces"]
end

node_client(("Library client"))

node_client -->|"configures"| node_builder
node_builder -->|"creates"| node_transitions
node_builder -->|"creates"| node_state_mgmt
node_builder -->|"creates"| node_actions
node_builder -->|"builds"| node_machine
node_builder -->|"adds transitions"| node_transitions
node_builder -->|"sets end states"| node_state_mgmt
node_client -->|"fires event"| node_machine
node_machine -->|"looks up transition"| node_transitions
node_machine -->|"dispatches callbacks"| node_actions
node_machine -->|"validates states"| node_state_mgmt
node_actions -->|"calls handlers"| node_executors
node_client -->|"supplies handlers"| node_executors
node_machine -->|"uses event and context"| node_entities
node_transitions -->|"stores transitions"| node_entities
node_state_mgmt -->|"tracks states"| node_entities

click node_builder "https://github.com/koushikr/easy-fsm/blob/master/src/main/java/io/github/fsm/MachineBuilder.java"
click node_machine "https://github.com/koushikr/easy-fsm/blob/master/src/main/java/io/github/fsm/StateMachine.java"
click node_transitions "https://github.com/koushikr/easy-fsm/blob/master/src/main/java/io/github/fsm/services/impl/TransitionServiceImpl.java"
click node_state_mgmt "https://github.com/koushikr/easy-fsm/blob/master/src/main/java/io/github/fsm/services/impl/StateManagementServiceImpl.java"
click node_actions "https://github.com/koushikr/easy-fsm/blob/master/src/main/java/io/github/fsm/services/impl/ActionServiceImpl.java"
click node_entities "https://github.com/koushikr/easy-fsm/tree/master/src/main/java/io/github/fsm/models/entities"
click node_executors "https://github.com/koushikr/easy-fsm/tree/master/src/main/java/io/github/fsm/models/executors"

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_builder,node_client toneBlue
class node_machine,node_transitions,node_state_mgmt,node_actions toneAmber
class node_entities,node_executors toneMint
```

## Components

### Machine configuration

- [MachineBuilder](https://github.com/koushikr/easy-fsm/blob/master/src/main/java/io/github/fsm/MachineBuilder.java): `src/main/java/io/github/fsm/MachineBuilder.java`

### Event runtime

- [StateMachine](https://github.com/koushikr/easy-fsm/blob/master/src/main/java/io/github/fsm/StateMachine.java): `src/main/java/io/github/fsm/StateMachine.java`
- [Transition service](https://github.com/koushikr/easy-fsm/blob/master/src/main/java/io/github/fsm/services/impl/TransitionServiceImpl.java): `src/main/java/io/github/fsm/services/impl/TransitionServiceImpl.java`
- [State management](https://github.com/koushikr/easy-fsm/blob/master/src/main/java/io/github/fsm/services/impl/StateManagementServiceImpl.java): `src/main/java/io/github/fsm/services/impl/StateManagementServiceImpl.java`
- [Action service](https://github.com/koushikr/easy-fsm/blob/master/src/main/java/io/github/fsm/services/impl/ActionServiceImpl.java): `src/main/java/io/github/fsm/services/impl/ActionServiceImpl.java`

### FSM model

- [FSM entities](https://github.com/koushikr/easy-fsm/tree/master/src/main/java/io/github/fsm/models/entities): `src/main/java/io/github/fsm/models/entities`
- [Callback interfaces](https://github.com/koushikr/easy-fsm/tree/master/src/main/java/io/github/fsm/models/executors): `src/main/java/io/github/fsm/models/executors`

### Other components

- **Library client**

## Connections

- Library client → MachineBuilder: configures
- MachineBuilder → Transition service: creates
- MachineBuilder → State management: creates
- MachineBuilder → Action service: creates
- MachineBuilder → StateMachine: builds
- MachineBuilder → Transition service: adds transitions
- MachineBuilder → State management: sets end states
- Library client → StateMachine: fires event
- StateMachine → Transition service: looks up transition
- StateMachine → Action service: dispatches callbacks
- StateMachine → State management: validates states
- Action service → Callback interfaces: calls handlers
- Library client → Callback interfaces: supplies handlers
- StateMachine → FSM entities: uses event and context
- Transition service → FSM entities: stores transitions
- State management → FSM entities: tracks states