ItalyPaleAle/francis

The simple & low-maintenance Go distributed actor framework and workflow engine

Summary

Francis is a Go framework that combines distributed actors with a durable workflow engine. It is designed to be low-maintenance: the only required dependency is a relational database (PostgreSQL or SQLite), and it can run embedded in the host application rather than as a separate control plane.

What it is useful for

Francis targets building stateful services where each entity—users, devices, shopping carts, or game sessions—is modeled as an actor with its own durable state that survives restarts and host moves. Engineers can also use it for multi-step workflows with compensation: when a later step fails, the framework runs earlier steps' compensation handlers in reverse, implementing the saga pattern (for example, releasing inventory then refunding a charge if a shipment step fails). Other documented use cases include durable alarms for scheduled background work, a distributed task pool that bounds concurrency per host and scales out as hosts are added, and adding resilience to microservices without standing up a separate message broker or coordination service. Each actor runs with turn-based concurrency, so callers do not manage actor lifecycles or coordinate access to actor state themselves.

How engineers can use it

Per the README, the first step is adding the module:

go get github.com/italypaleale/francis

For the simplest setup (the local topology, which requires no extra services), the quickstart creates a host with local.NewHost, configures an embedded SQLite store via local.WithSQLiteProvider, and sets a runtime PSK that the framework uses to derive a cluster CA for host-to-host mTLS. Actor types are registered before the host runs:

err = h.RegisterActor("counter", NewCounter)

Actor methods take an actor.Envelope and read or write durable state through the actor client, as in the README's Counter.Invoke example. Workflows are declared as graphs of workflow.Step entries, each pairing a WithRun function with an optional WithCompensate undo handler. For more complex deployments the same code can point workers at a standalone runtime (the remote topology).

Runnable samples live in the examples directory, and the full walkthrough is in the Quickstart at gofrancis.dev. The README notes the local PSK placeholder ("change-me-please") must be replaced before production use, and that the docs site is the source of truth for the remote topology and deployment guidance.