Smalldb, the state machine abstraction layer, is the framework to build a model layer of a web application using state machines. Smalldb combines formal finite automata, simple PHP code, and powerful SQL database into a single elegant package.


The basic concept

(CRUD state machine)

Each and every entity in Smalldb is a state machine. Some are simple, some are complex, but they all share a unified API. The formal model of the Smalldb state machines provides us with a definition that describes the expected behavior and life cycle of each entity. Then, when the application is running, the framework validates the entity behavior against the definition and throws an error when something unexpected happens.

We can model a simple CRUD entity using a simple state machine with three transitions: create, update, and delete (see the diagram above/right). Usual REST API implementations use HTTP Post, Put, and Delete methods, respectively, to represent these actions. For more complex entities, we can be easily add more states and transitions to express what actions the entity can perform at which moments of its life cycle, or we can remove the transitions we do not want (see the examples below).

Unlike traditional finite automata implementations, where each state machine instance exists as an instantiated object, the Smalldb state machines are abstract entities which exist outside the application. Their life cycle is independent of the application life cycle. The Smalldb framework then provides an API to communicate with the state machine instances rather than representing them.

Smalldb is designed (but not limited) to run on top of an SQL database, where each row in a designated SQL table represents a single instance of a given Smalldb state machine. Transitions of the state machine, implemented as PHP methods, then perform SQL queries to modify the data in the database.

Smalldb expects nothing more than a good database design and does not limit you from using the full power of SQL (unlike many ORM frameworks). However, it can use any other data storage — the SQL support is merely an extension (a plugin) that you may or may not use. Smalldb can encapsulate anything from physical devices to cloud storage.

Why state machines?

Understandability. State machines provide an elegant way to specify the behavior of an entity, and they are often used during software development process (see UML state machine). In contrast to source code, a state machine diagram is comprehensible even to non-technical people (with some explanation involved), and thus it is possible to discuss the business logic effectively with customers (domain experts), or to put new programmers on the track quickly.

Visualization. The primary way of defining a state machine is a state diagram. What else to say? Smalldb framework provides tools to both render a state machine diagram using Grafovatko and to import the diagram you drew (and saved as a GraphML or BPMN file). The diagrams are now part of the application source code. One way or another, there is always an up-to-date diagram you can include in your documentation, presentation, show in an admin interface, or put on your wall.

Simple API. Read state, invoke transition. — That is the API of a Smalldb state machine. Then there is a repository to browse the state machines, and a state machine definitions to describe what each state machine can do. No complications involved.

Formal background. Finite automata (on which Smalldb stands) is a simple formal concept. It is relatively easy to prove formally many interesting properties of given finite automata, like state reachability and liveness to make sure your users won’t get stuck somewhere, even when they have only limited permissions. The formally verified software is no longer a matter of academic discussion, Smalldb brings it to real-world applications.

See also:

State Machine Examples

A blog post in CMS. Write it and publish it. Or delete it.

(blogpost diagram)

An article, which can be accepted or rejected by an editor. Like the previous blog post example, but with some review workflow.

(article diagram)

Bug in a bug tracking system. Bug is created when a user reports it, then it may be assigned to a programmer or directly resolved. If everything is good, it will get closed, and if not, it can be reopened.

(bug diagram)

A taxi order. Customer calls a taxi, taxi waits for customer and taximeter updates price of the order. Then customer rides to his destination and finally pays the ride.

(taxi order diagram)

An invoice. Once created, it never changes again; it simply exists forever. This is an example of a trivial state machine.

(invoice diagram)

See also …