# gocardless/statesman

A statesmanlike state machine library.

Repository: https://github.com/gocardless/statesman
Canonical: https://ross.abutalabs.com/products/statesman
Homepage: https://gocardless.com/blog/statesman/
Language: Ruby
License: MIT
License Family: permissive
Last push: 2026-08-04T09:14:42+00:00

## Health v2 (maintenance only)
Score: 93/100 (v2, computed 2026-09-02T17:46:02.011165+00:00)
- activity 96, release rhythm 84, longevity 100
- inputs: {"age_days": 4745, "days_push": 29, "days_rel": 29, "gap_med": 40, "n_releases_24m": 4}
- flags: none
- formula: round(0.45*activity + 0.35*rhythm + 0.20*longevity); archived -> min(score, 10)

## Adoption (not part of the score)
Stars 1906, forks 158 (observed 2026-08-28T04:05:51.968679+00:00)

## What it is
Statesman is an opinionated Ruby state machine library that decouples state machine logic from models by defining machines in separate classes. It persists transitions to the database for a full audit history with JSON metadata and uses database indices to prevent duplicate transitions under race conditions.

## Use cases
- model order lifecycles like pending, purchased, shipped, refunded in a Rails app
- persist a full audit trail of state transitions with metadata
- prevent duplicate state transitions across multiple app servers
- define state machines as separate classes composable with any Ruby object
- add guard conditions and callbacks around state transitions

## When to choose
- you need database-level integrity and race-condition protection for state changes
- you need a persisted, queryable audit history of every transition
- you want state machine logic decoupled from your ActiveRecord models
- you're building Rails applications with complex object lifecycles

## When to avoid
- you want a lightweight in-memory state machine without persistence
- you prefer state machine behavior defined directly on your models
- you're not using Ruby or Rails

## Facets
- artifact type: library
- maturity: stable
- function: developer-tools
- domain: developer-tools, backend, web-development
- platform: ruby, jvm
- tags: state-machine, audit-trail, rails, transitions, data-integrity

## Member repositories
- gocardless/statesman (main) score 93

## Provenance
- Observed fields: from GitHub, fetched 2026-08-28T04:05:51.968679+00:00.
- Health v2: computed from the inputs above; adoption is never an input.
- Inferred fields (summary, facets, guidance): AI-extracted, prompt v1, taxonomy v1, on 2026-08-30T03:11:40.583037+00:00, confidence not recorded.
  - readme: https://github.com/gocardless/statesman (fetched 2026-08-28T04:05:51.968679+00:00, sha f76f79ea2378)
  - homepage: https://gocardless.com/blog/statesman/ (fetched 2026-08-29T10:50:41.669863+00:00, sha 03b20a9841ce)
  - site_page: https://gocardless.com/features/variable-recurring-payments (fetched 2026-08-29T10:50:41.673597+00:00, sha c6ff4bb5d9b5)
  - site_page: https://gocardless.com/features/invoicing (fetched 2026-08-29T10:50:41.681530+00:00, sha d117ed5c9284)
  - site_page: https://gocardless.com/about/jobs (fetched 2026-08-29T10:50:41.683352+00:00, sha 51eaa19728d9)
  - site_page: https://gocardless.com/guides/posts/gc-changelog (fetched 2026-08-29T10:50:41.685116+00:00, sha 95064c7e0f78)
  - site_page: https://gocardless.com/features/recurring-payments (fetched 2026-08-29T10:50:41.686814+00:00, sha 711de9d37dad)
  - site_page: https://gocardless.com/pricing (fetched 2026-08-29T10:50:41.675693+00:00, sha 30f8a16039a6)
  - site_page: https://gocardless.com/partners (fetched 2026-08-29T10:50:41.677525+00:00, sha 12087b77b1fa)
  - site_page: https://gocardless.com/developers (fetched 2026-08-29T10:50:41.679520+00:00, sha 0f6945e5d567)
- Data as of 2026-08-30T08:39:29.467469+00:00.