Documentation

SparrowKit handles the parts of a Rails application that are the same every time — signing in, sending mail, taking money — so that the part that is not the same every time is the part you write.

Four modules: three that do the work, and a control panel to configure them. Use one of them or all of them.

Installing

SparrowKit is not on RubyGems, so the modules come from the repository. They also pin each other to an exact version, which means every module in the chain has to come from the same place. One git block does all of it:

# Gemfile
git "https://github.com/sparrow-soft/sparrowkit.git", tag: "v1.4.0", glob: "gems/*/*.gemspec" do
  gem "sparrow_auth"   # passkeys, teams, invitations
  gem "sparrow_mail"   # sending email
  gem "sparrow_pay"    # subscription billing

  group :development do
    gem "sparrow_ui"   # the control panel; never in production
  end
end

Comment out anything you do not want. Taking one module on its own works — the glob: is what lets Bundler find whatever that module depends on from the same source without you naming it.

The tag: pins you to a release rather than to whatever the repository holds today. Change it when you want to move.

Then one command:

bin/rails sparrowkit:install

That mounts each module, mounts the control panel at /sparrowkit, copies each module’s database tables in and applies them, and tells you what it changed. It is safe to run again — a second run adds only what is missing.

It runs only its own migrations. bin/rails db:migrate means “apply every pending change in this application”, so on an existing app it would also run whatever migration you happened to be halfway through writing. The installer runs the ones it copied and no others, and tells you if you have any of your own left pending.

sparrowkit:install comes from sparrow_ui. If you are not taking the control panel, install each module with its own task instead — bin/rails sparrow_mail:install, sparrow_auth:install or sparrow_pay:install.

What your database has to be

PostgreSQL 12 or newer, or SQLite 3.9 or newer. MySQL is not supported, and the installer says so before it writes anything.

You also need Rails 8.1 or newer and Ruby 3.2 or newer.

Then start the server and open http://localhost:3000/sparrowkit.

Modules

Teams and tenancy sits underneath all of it: it is what a subscription belongs to, and what keeps one customer’s records away from another’s.

Where settings live

Everything the control panel saves goes into your application’s Rails encrypted credentials, one top-level key per module. That means settings are committed with your code and never sit in a .env file waiting to be pasted into a chat window.

The panel is the easier way to write them, not the only way — bin/rails credentials:edit reaches the same place. sparrow_mail will also read its adapter and default sender from the environment, for a deployment that prefers to set them that way.

There are no licence keys, no activation, and nothing phones home. What you install is what runs.

What SparrowKit does not do

Worth reading before you plan around it, because these are the assumptions that cost the most to discover late.

It ships no screens. No sign-in page of ours, no invitation page, no member list, no team switcher, no billing page. Rodauth serves its own pages under /auth; everything your customers look at, you write. There is no generator that writes them for you.

It does not decide what a role may do. There is no permission system, no policy object and no role ranking. A role is a name. SparrowKit stores it and never interprets it.

It never goes looking through your models. Marking a table as belonging to a team is something you opt into, one model at a time.

Licence and source

MIT. The source is at github.com/sparrow-soft/sparrowkit, and every module is ordinary Rails — models, controllers, migrations, all where you would expect them. Read it, change it, fork it.

Found a security problem? Write to humans@sparrowsoft.co rather than opening a public issue.