signoff 0.1.0

data/README.md

@@ -0,0 +1,794 @@
+# Signoff
+
+[![CI](https://github.com/JijoBose/Signoff/actions/workflows/ci.yml/badge.svg)](https://github.com/JijoBose/Signoff/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Concurrency-safe **approval workflows for ActiveRecord** with an immutable audit
+trail — a drop-in model concern, convention over configuration.
+
+Declare states and transitions with a tiny DSL, get `submit!` / `approve!` /
+`reject!` for free, plug in authorization and notifications, and keep an immutable
+PostgreSQL audit trail of every decision — **no external services required**.
+
+```ruby
+class ExpenseReport < ApplicationRecord
+  include Signoff
+
+  signoff do
+    state :draft
+    state :manager_review
+    state :finance_review
+    state :approved
+    state :rejected
+
+    transition :draft,          to: :manager_review
+    transition :manager_review, to: :finance_review
+    transition :finance_review, to: :approved
+
+    reject_to :rejected
+  end
+end
+```
+
+```ruby
+report.submit!
+report.approve!(user: current_user, comment: "Looks good")
+report.reject!(user: current_user, comment: "Missing receipts")
+
+report.current_state    # => :finance_review
+report.workflow_history # => [#<Signoff::Event ...>, ...]
+```
+
+## Features
+
+- 🧩 **Declarative DSL** — states, transitions, reject paths, guards and callbacks.
+- ⚙️ **Convention over configuration** — sensible defaults, minimal setup.
+- 🐘 **PostgreSQL-first** — an immutable JSONB audit log, properly indexed for millions of rows.
+- 🔐 **Authorization hooks** — `allow_transition` guards keyed to the state being acted on.
+- 📣 **Notifications** — `after_transition` callbacks that play nicely with ActiveJob & ActionMailer.
+- 🧾 **Immutable audit trail** — who did what, when, from where, with comments and metadata.
+- 🔎 **Query scopes** — `approved`, `pending`, `rejected`, `in_state(:x)`.
+- 🏗️ **Rails generators** — install + per-model migrations.
+- 🚂 **Rails 7.x & 8.x**, Ruby 3.2+.
+
+## Table of Contents
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Using It in a Rails Application](#using-it-in-a-rails-application)
+- [The DSL](#the-dsl)
+- [Instance API](#instance-api)
+- [Query Scopes](#query-scopes)
+- [Authorization](#authorization)
+- [Audit Trail](#audit-trail)
+- [Notifications](#notifications)
+- [Configuration](#configuration)
+- [Performance & Scale](#performance--scale)
+- [Generators](#generators)
+- [Example App](#example-app)
+- [Testing](#testing)
+- [Troubleshooting](#troubleshooting)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Requirements
+
+- Ruby **>= 3.2**
+- Rails **7.1 – 8.x** (`activerecord`, `activesupport`, `railties`)
+- **PostgreSQL** (the audit trail uses a `jsonb` column and a GIN index)
+
+> CI verifies every combination of Ruby 3.2 / 3.3 / 3.4 against Rails 7.1, 7.2,
+> 8.0 and 8.1.
+
+## Installation
+
+Add the gem to your `Gemfile`:
+
+```ruby
+gem "signoff"
+```
+
+Then:
+
+```bash
+bundle install
+```
+
+Run the installer to create the audit-events migration and the initializer:
+
+```bash
+rails generate signoff:install
+rails db:migrate
+```
+
+Add a state column to each model that has a workflow:
+
+```bash
+rails generate signoff:model ExpenseReport
+rails db:migrate
+```
+
+> The current state is stored in a column on the model itself (default
+> `approval_state`), which keeps state queries fast and indexable. The events
+> table is a separate, immutable audit log.
+
+## Quick Start
+
+### 1. Declare the workflow
+
+```ruby
+class ExpenseReport < ApplicationRecord
+  include Signoff
+
+  signoff do
+    state :draft
+    state :manager_review
+    state :finance_review
+    state :approved
+    state :rejected
+
+    initial_state :draft # optional; defaults to the first state
+
+    transition :draft,          to: :manager_review
+    transition :manager_review, to: :finance_review
+    transition :finance_review, to: :approved
+
+    reject_to :rejected
+
+    # Only managers can act on a report that is in manager_review:
+    allow_transition :manager_review do |user|
+      user.manager?
+    end
+
+    allow_transition :finance_review do |user|
+      user.finance_team?
+    end
+
+    # Fire a notification after each successful transition:
+    after_transition do |record, event|
+      WorkflowNotificationJob.perform_later(record.id, event.id)
+    end
+  end
+end
+```
+
+### 2. Drive it from your application
+
+```ruby
+report = ExpenseReport.create!(title: "Conference travel", amount: 1_200)
+report.current_state           # => :draft
+report.pending?                # => true
+
+report.submit!                 # draft -> manager_review
+
+report.approve!(
+  user:    current_user,       # must satisfy the manager_review guard
+  comment: "Looks good"
+)                              # manager_review -> finance_review
+
+report.approve!(user: finance_lead) # finance_review -> approved
+report.approved?               # => true
+
+report.workflow_history        # chronological audit trail
+report.approved_by             # => #<User finance_lead>
+```
+
+### 3. Reject when needed
+
+```ruby
+report.reject!(user: current_user, comment: "Missing receipts")
+report.rejected?               # => true
+report.last_rejection.comment  # => "Missing receipts"
+```
+
+## Using It in a Rails Application
+
+A complete, idiomatic integration — wiring the acting user, routes, a
+controller, views, and notifications. (A runnable version of this lives in
+[`examples/expense_approval/`](examples/expense_approval).)
+
+### 1. The model
+
+```ruby
+# app/models/expense_report.rb
+class ExpenseReport < ApplicationRecord
+  include Signoff
+
+  belongs_to :submitter, class_name: "User"
+
+  signoff do
+    state :draft
+    state :manager_review
+    state :finance_review
+    state :approved
+    state :rejected
+
+    transition :draft,          to: :manager_review
+    transition :manager_review, to: :finance_review
+    transition :finance_review, to: :approved
+
+    reject_to :rejected
+
+    allow_transition :manager_review do |user|
+      user.manager?
+    end
+
+    allow_transition :finance_review do |user|
+      user.finance_team?
+    end
+
+    # Runs after the transaction commits, with the persisted event.
+    after_transition do |record, event|
+      WorkflowNotificationJob.perform_later(record.id, event.id)
+    end
+  end
+end
+```
+
+Generate the audit table and the model's state column once:
+
+```bash
+rails generate signoff:install
+rails generate signoff:model ExpenseReport
+rails db:migrate
+```
+
+### 2. Attribute the acting user automatically
+
+Include the controller concern in `ApplicationController`. It populates
+`Signoff::Current` from your `current_user` helper (and the request IP /
+user agent when those are enabled in the initializer), so transitions are
+attributed without passing `user:` everywhere.
+
+```ruby
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::Base
+  include Signoff::Controller # sets Current.user / ip_address / user_agent
+  # Assumes a `current_user` helper (Devise, custom auth, etc.)
+end
+```
+
+> Prefer to be explicit, or not using the concern? Just pass the user directly:
+> `report.approve!(user: current_user, comment: "...")`.
+
+### 3. Routes
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  resources :expense_reports do
+    member do
+      patch :submit
+      patch :approve
+      patch :reject
+    end
+  end
+end
+```
+
+### 4. Controller
+
+```ruby
+# app/controllers/expense_reports_controller.rb
+class ExpenseReportsController < ApplicationController
+  before_action :set_report, only: %i[show submit approve reject]
+
+  # Turn workflow errors into friendly responses instead of 500s.
+  rescue_from Signoff::UnauthorizedError do |error|
+    redirect_back fallback_location: expense_reports_path, alert: error.message
+  end
+  rescue_from Signoff::InvalidTransitionError do |error|
+    redirect_back fallback_location: expense_reports_path, alert: error.message
+  end
+
+  # Use the generated scopes for dashboards.
+  def index
+    @pending  = ExpenseReport.pending.order(created_at: :desc)
+    @approved = ExpenseReport.approved
+    @rejected = ExpenseReport.rejected
+  end
+
+  # Preload the audit trail (and the acting users) to avoid N+1 queries.
+  def show
+    @report  = ExpenseReport.includes(signoff_events: :user).find(params[:id])
+    @history = @report.workflow_history
+  end
+
+  def submit
+    @report.submit!(comment: transition_params[:comment])
+    redirect_to @report, notice: "Submitted for review."
+  end
+
+  def approve
+    # The acting user comes from current_user via Signoff::Controller.
+    @report.approve!(comment: transition_params[:comment])
+    redirect_to @report, notice: "Approved."
+  end
+
+  def reject
+    @report.reject!(comment: transition_params[:comment])
+    redirect_to @report, notice: "Rejected."
+  end
+
+  private
+
+  def set_report
+    @report = ExpenseReport.find(params[:id])
+  end
+
+  def transition_params
+    params.permit(:comment)
+  end
+end
+```
+
+### 5. Views
+
+Render the current state and only the actions the current user is actually
+allowed to perform (`can_approve?` / `can_reject?` never raise):
+
+```erb
+<%# app/views/expense_reports/show.html.erb %>
+<h1><%= @report.title %></h1>
+
+<p>
+  Status:
+  <span class="badge badge-<%= @report.current_state %>">
+    <%= @report.current_state.to_s.humanize %>
+  </span>
+</p>
+
+<%= form_with url: nil do %>
+  <%# Show "Submit" only while the report is a draft %>
+  <% if @report.draft? %>
+    <%= button_to "Submit for review", submit_expense_report_path(@report), method: :patch %>
+  <% end %>
+
+  <% if @report.can_approve?(current_user) %>
+    <%= button_to "Approve", approve_expense_report_path(@report), method: :patch %>
+  <% end %>
+
+  <% if @report.can_reject?(current_user) %>
+    <%= button_to "Reject", reject_expense_report_path(@report), method: :patch %>
+  <% end %>
+<% end %>
+
+<h2>Audit trail</h2>
+<table>
+  <thead>
+    <tr><th>When</th><th>Action</th><th>Transition</th><th>By</th><th>Comment</th></tr>
+  </thead>
+  <tbody>
+    <% @history.each do |event| %>
+      <tr>
+        <td><%= event.created_at.to_fs(:short) %></td>
+        <td><%= event.action.humanize %></td>
+        <td><%= event.from_state %> &rarr; <%= event.to_state %></td>
+        <td><%= event.user&.name || "system" %></td>
+        <td><%= event.comment %></td>
+      </tr>
+    <% end %>
+  </tbody>
+</table>
+```
+
+A dashboard built from the scopes:
+
+```erb
+<%# app/views/expense_reports/index.html.erb %>
+<h2>Awaiting a decision (<%= @pending.size %>)</h2>
+<%= render @pending %>
+
+<h2>Approved (<%= @approved.size %>)</h2>
+<%= render @approved %>
+
+<h2>Rejected (<%= @rejected.size %>)</h2>
+<%= render @rejected %>
+```
+
+### 6. Notifications (ActiveJob + ActionMailer)
+
+The model's `after_transition` hook enqueues this job after each transition
+commits, so the event row is guaranteed to exist when the job runs:
+
+```ruby
+# app/jobs/workflow_notification_job.rb
+class WorkflowNotificationJob < ApplicationJob
+  queue_as :default
+
+  def perform(record_id, event_id)
+    event  = Signoff::Event.find(event_id)
+    report = event.workflowable
+
+    case event.action
+    when "submit"  then ApprovalMailer.with(report: report, event: event).submitted.deliver_later
+    when "approve" then ApprovalMailer.with(report: report, event: event).advanced.deliver_later
+    when "reject"  then ApprovalMailer.with(report: report, event: event).rejected.deliver_later
+    end
+  end
+end
+```
+
+```ruby
+# app/mailers/approval_mailer.rb
+class ApprovalMailer < ApplicationMailer
+  def submitted
+    @report = params[:report]
+    mail(to: User.managers.pluck(:email), subject: "Expense report awaiting your review")
+  end
+
+  def advanced
+    @report = params[:report]
+    mail(to: User.finance_team.pluck(:email), subject: "Expense report ready for finance review")
+  end
+
+  def rejected
+    @report = params[:report]
+    @event  = params[:event]
+    mail(to: @report.submitter.email, subject: "Your expense report was rejected")
+  end
+end
+```
+
+### 7. Testing the integration
+
+```ruby
+# spec/requests/expense_report_approvals_spec.rb
+RSpec.describe "Expense report approvals", type: :request do
+  it "lets a manager approve a submitted report" do
+    report = ExpenseReport.create!(title: "Travel", amount: 500, submitter: create(:user))
+    report.submit!
+    sign_in create(:user, manager: true)
+
+    patch approve_expense_report_path(report), params: { comment: "Looks good" }
+
+    expect(report.reload.current_state).to eq(:finance_review)
+    expect(report.last_approval.comment).to eq("Looks good")
+  end
+
+  it "blocks an employee and surfaces the error" do
+    report = ExpenseReport.create!(title: "Travel", amount: 500, submitter: create(:user))
+    report.submit!
+    sign_in create(:user) # not a manager
+
+    patch approve_expense_report_path(report), params: { comment: "nope" }
+
+    expect(response).to redirect_to(expense_reports_path)
+    expect(report.reload.current_state).to eq(:manager_review)
+  end
+end
+```
+
+## The DSL
+
+Everything goes inside `signoff do ... end`. Pass `column:` to override
+the state column for a single model (e.g. `signoff(column: :workflow_state) do`).
+
+| DSL method | Description |
+| --- | --- |
+| `state(name, initial: false)` | Declare a state. `initial: true` marks the start state. |
+| `states(*names)` | Declare several states at once. |
+| `initial_state(name)` | Set the start state explicitly (defaults to the first declared). |
+| `transition(from, to:)` | Declare a forward transition. `to:` accepts a symbol or an array. |
+| `reject_to(state)` | The state `reject!` moves a record into. |
+| `allow_transition(from) { \|user[, record]\| ... }` | Authorize transitions **out of** `from`. |
+| `before_transition { \|record, from, to\| ... }` | Run inside the transaction, before the state is written. |
+| `after_transition { \|record, event\| ... }` | Run after the transaction commits (great for jobs/mail). |
+
+Definitions are validated when the class loads. You'll get a descriptive
+`Signoff::DefinitionError` for duplicate states, transitions to/from
+undeclared states, a missing initial state, or an undeclared reject state.
+
+## Instance API
+
+Including `Signoff` and declaring a workflow generates:
+
+### Transitions
+
+```ruby
+report.submit!(user: nil, comment: nil, metadata: {}, to: nil)
+report.approve!(user: nil, comment: nil, metadata: {}, to: nil)
+report.reject!(user: nil, comment: nil, metadata: {})
+```
+
+- `submit!` and `approve!` both advance the **single forward transition** from the
+  current state; they differ only in the audit `action` recorded (`"submit"` vs
+  `"approve"`). Use `submit!` for the first step out of `draft` by convention.
+- When a state has **more than one** forward transition, pass `to:` to disambiguate
+  (`report.approve!(to: :finance_review)`).
+- `reject!` moves the record to the `reject_to` state.
+- All accept `ip_address:` and `user_agent:` keyword overrides (see
+  [Configuration](#configuration)).
+- Each returns the created `Signoff::Event`.
+
+### State & predicates
+
+```ruby
+report.current_state   # => :manager_review (a Symbol)
+
+report.pending?        # not approved and not rejected
+report.approved?       # in a successful terminal state
+report.rejected?       # in the reject state
+
+# One predicate per declared state:
+report.draft?
+report.manager_review?
+report.finance_review?
+```
+
+### Authorization predicates
+
+```ruby
+report.can_approve?(current_user) # => true / false (never raises)
+report.can_reject?(current_user)  # => true / false
+```
+
+Both fall back to `Signoff::Current.user` when no argument is given.
+
+### Audit helpers
+
+```ruby
+report.workflow_history  # all events, chronological, preloadable
+report.last_approval     # most recent "approve" event
+report.last_rejection    # most recent "reject" event
+report.approved_by       # the user who moved it into a terminal "approved" state
+```
+
+## Query Scopes
+
+```ruby
+ExpenseReport.approved              # in a successful terminal state
+ExpenseReport.pending              # neither approved nor rejected
+ExpenseReport.rejected             # in the reject state
+ExpenseReport.in_state(:finance_review)
+ExpenseReport.in_state(:draft, :manager_review)
+
+# Fully chainable:
+ExpenseReport.where(user: current_user).pending.order(created_at: :desc)
+```
+
+Scopes filter on the indexed state column, so they stay fast at scale.
+
+## Authorization
+
+`allow_transition` guards are keyed by the **state the record is in** when the
+action happens — i.e. "who is allowed to act on a record currently in this state".
+
+```ruby
+signoff do
+  # ...
+  allow_transition :manager_review do |user|
+    user.manager?
+  end
+
+  # Guards may also receive the record:
+  allow_transition :finance_review do |user, record|
+    user.finance_team? && record.amount <= user.approval_limit
+  end
+end
+```
+
+- A blocked transition raises `Signoff::UnauthorizedError` with a
+  descriptive message and **leaves the record unchanged** (the state is only
+  written inside the transaction, after the guard passes).
+- If a guard is declared but **no user** is supplied (and none is set on
+  `Signoff::Current`), an `UnauthorizedError` is raised too.
+- States without a guard are open to anyone (e.g. `draft` → `submit!`).
+- `can_approve?` / `can_reject?` evaluate the same guards but never raise.
+
+## Audit Trail
+
+Every transition writes one immutable `Signoff::Event` row:
+
+| Column | Notes |
+| --- | --- |
+| `workflowable_type` / `workflowable_id` | Polymorphic owner (the model). |
+| `user_id` | The acting user (nullable). |
+| `action` | `"submit"`, `"approve"`, `"reject"`. |
+| `from_state` / `to_state` | Strings. |
+| `comment` | Free text. |
+| `metadata` | `jsonb`, GIN-indexed. |
+| `ip_address` / `user_agent` | Captured when enabled (see config). |
+| `created_at` | Set automatically; rows are append-only. |
+
+```ruby
+event = report.approve!(user: current_user, comment: "Approved", metadata: { source: "web" })
+
+event.action      # => "approve"
+event.from_state  # => "manager_review"
+event.to_state    # => "finance_review"
+event.user        # => #<User ...>
+event.metadata    # => { "source" => "web" }
+```
+
+**Events are read-only once persisted** (configurable via
+`config.immutable_events`), guaranteeing a tamper-resistant trail. Useful scopes
+are available too: `Signoff::Event.chronological`, `.recent`,
+`.with_action("approve")`, `.approvals`, `.rejections`.
+
+### Capturing request context
+
+`Signoff::Current` is an `ActiveSupport::CurrentAttributes` store for the
+acting `user`, `ip_address` and `user_agent`. Populate it automatically from your
+controllers:
+
+```ruby
+class ApplicationController < ActionController::Base
+  include Signoff::Controller # sets Current.user / ip / user_agent
+end
+```
+
+Then `report.approve!` (with no `user:`) is attributed to `current_user`, and — when
+`track_ip_addresses` / `store_user_agent` are enabled — each event records the
+request IP and user agent.
+
+## Notifications
+
+Use `after_transition` to react once the transition has safely committed:
+
+```ruby
+signoff do
+  # ...
+  after_transition do |record, event|
+    WorkflowNotificationJob.perform_later(record.id, event.id)
+  end
+end
+```
+
+```ruby
+class WorkflowNotificationJob < ApplicationJob
+  queue_as :default
+
+  def perform(record_id, event_id)
+    event  = Signoff::Event.find(event_id)
+    record = event.workflowable
+
+    case event.action
+    when "approve" then ApprovalMailer.advanced(record, event).deliver_later
+    when "reject"  then ApprovalMailer.rejected(record, event).deliver_later
+    end
+  end
+end
+```
+
+Because `after_transition` runs **after** the transaction commits, the event row is
+guaranteed to exist by the time your job runs.
+
+## Configuration
+
+Generated at `config/initializers/signoff.rb`:
+
+```ruby
+Signoff.configure do |config|
+  config.user_class            = "User"          # model referenced by Event#user
+  config.track_ip_addresses    = false           # persist request IP on events
+  config.store_user_agent      = false           # persist request user agent on events
+  config.default_state_column  = :approval_state  # default state column for all models
+  config.event_table_name      = "signoff_events"
+  config.validate_on_transition = false          # run full record validation on transition
+  config.dependent             = :delete_all      # events strategy when owner is destroyed
+  config.immutable_events      = true             # make persisted events read-only
+end
+```
+
+> **Note:** because events are immutable by default, use `:delete_all` or `:nullify`
+> for `config.dependent` — `:destroy` instantiates each event and is blocked by the
+> read-only guard. Set `config.immutable_events = false` if you need `:destroy`.
+
+## Performance & Scale
+
+Designed for millions of audit rows:
+
+- **State lives in an indexed column** on the model, so `approved` / `pending` /
+  `in_state` are simple, index-backed `WHERE` queries — not correlated subqueries
+  over the events table.
+- The install migration indexes `workflowable_type`, `workflowable_id`,
+  `created_at`, a composite `(workflowable_type, workflowable_id, created_at)` for
+  history reads, a composite `(workflowable_type, workflowable_id, action, created_at)`
+  for `last_approval` / `last_rejection` / `approved_by`, `user_id`, and an optional
+  **GIN index on `metadata`** (skip it with `--skip-metadata-index` if you never
+  query metadata, to avoid write amplification).
+- **Concurrency-safe:** each transition takes a row lock (`SELECT … FOR UPDATE`) and
+  re-checks the current state before writing, so two racing `approve!` calls can't
+  both succeed — the loser gets an `InvalidTransitionError`.
+- `workflow_history` is the `signoff_events` association, so preload it to
+  avoid N+1 queries:
+
+  ```ruby
+  ExpenseReport.includes(:signoff_events).find_each do |report|
+    report.workflow_history.each { |event| ... } # no extra queries
+  end
+  ```
+
+- Transitions write the state column with a single `UPDATE` and insert one event
+  row inside one transaction.
+
+## Generators
+
+```bash
+# Migration for the events table + the initializer:
+rails generate signoff:install
+#   create  config/initializers/signoff.rb
+#   create  db/migrate/XXXX_create_signoff_events.rb
+
+# Add the state column to a model's table:
+rails generate signoff:model ExpenseReport
+#   create  db/migrate/XXXX_add_approval_state_to_expense_reports.rb
+
+# Custom column / initial value:
+rails generate signoff:model Invoice --column=workflow_state --initial=pending
+```
+
+Both generators emit migrations stamped with your app's current
+`ActiveRecord::Migration` version, so they work on Rails 7.x and 8.x alike.
+
+## Example App
+
+A complete, runnable Rails 8 + PostgreSQL example lives in
+[`examples/expense_approval/`](examples/expense_approval). It wires up `User` and
+`ExpenseReport`, a notification job, the migrations, and a demo script:
+
+```bash
+cd examples/expense_approval
+bundle install
+bin/rails db:create db:migrate db:seed
+bin/rails runner script/demo.rb   # walks a report from draft to approved (and a rejection)
+```
+
+## Testing
+
+The suite runs against a real PostgreSQL database (to exercise JSONB) and reports
+coverage with SimpleCov (enforced ≥ 90%).
+
+```bash
+bundle install
+# Point the suite at your PostgreSQL instance:
+export SIGNOFF_PGHOST=localhost SIGNOFF_PGPORT=5432 SIGNOFF_PGUSER=postgres SIGNOFF_PGDATABASE=signoff_test
+createdb signoff_test
+bundle exec rspec
+bundle exec rubocop
+```
+
+The harness reads `SIGNOFF_PGHOST`, `SIGNOFF_PGPORT`, `SIGNOFF_PGUSER`, `SIGNOFF_PGPASSWORD`,
+`SIGNOFF_PGDATABASE` (falling back to the standard `PG*` variables). To test a specific
+Rails line, export `RAILS_VERSION` (`7.1`, `7.2`, `8.0`, `8.1`) before `bundle install`.
+
+## Troubleshooting
+
+**`Signoff::MissingColumnError`** — the model's table has no state column.
+Run `rails g signoff:model YourModel` (or add an indexed string column
+named `approval_state`) and migrate.
+
+**`Signoff::NotConfiguredError`** — you `include Signoff` but never
+declared a `signoff do ... end` block.
+
+**`Signoff::InvalidTransitionError: ambiguous transition`** — the state has
+multiple forward transitions; pass `to:` to `approve!` / `submit!`.
+
+**`ActiveRecord::ReadOnlyRecord` when destroying a record** — events are immutable, so
+`config.dependent = :destroy` is incompatible. Use `:delete_all` or `:nullify`, or set
+`config.immutable_events = false`.
+
+**`Event#user` is `nil` / wrong class** — set `config.user_class` in the initializer
+(it is read when the `Event` model loads, after initializers run).
+
+## Development
+
+```bash
+bin/setup            # install dependencies
+bundle exec rspec    # run the test suite (needs PostgreSQL)
+bundle exec rubocop  # lint
+bin/console          # interactive prompt
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome at
+<https://github.com/JijoBose/Signoff>. This project follows the
+[Contributor Covenant](CODE_OF_CONDUCT.md) code of conduct.
+
+## License
+
+Available as open source under the terms of the [MIT License](LICENSE.txt).