OpenLoam 🌱

In short: OpenLoam is a Rails starter kit for business apps — multi-tenancy, permissions, audit trails, workflows, and an event bus already built in, so you skip months of plumbing and start on real features. It's also AI-native: convention-driven code that AI coding agents (Claude Code, Codex, etc.) can safely extend, with human-approval gates before any agent write takes effect.

The fertile Rails foundation where AI agents grow business software.

📖 Documentation: deliveristsio.github.io/open-loam/

Every serious back-office app — CRM, ERP, ops console, internal tool — re-derives the same ~80%: who's the tenant, who's allowed, what changed and when, how do modules talk, where's the admin. Teams burn months on this before shipping a single thing a customer cares about.

And now a second shift: AI coding agents (Claude Code, Codex, opencode) can write real features — if the codebase is legible to them. Sprawling, snowflake architectures confuse agents as much as they confuse new hires. Convention is what makes a codebase safe for an agent to extend.

OpenLoam fuses the two: a pre-built business foundation that is deliberately agent-legible. Rails already leans convention-over-configuration — arguably the most agent-friendly framework there is. OpenLoam extends that philosophy from "how to structure a controller" up to "how a multi-tenant, permissioned, audited business domain is built" — and ships the agent conventions to match.

The pieces exist in Rails, but scattered — foundation shape in Bullet Train and the commerce products, an event backbone in Rails Event Store, custom-entity modeling only inside commerce. No Rails project unifies them into a single, agent-legible business foundation. The closest structural analogs live in other stacks: Frappe/ERPNext in Python, and Open Mercato in TypeScript — whose module system and convention-first, agent-legible approach directly inspired OpenLoam. OpenLoam brings that idea to Rails, the substrate it always suited.

Each pillar ships as a convention with sane defaults, overridable when you truly need to — never a blank page.

You write the 20% that is your business. OpenLoam is the 80% that every business app shares.

OpenLoam treats "an AI agent will extend this" as a first-class constraint:

• One obvious way to add an entity, a permission, an event, a screen — so an agent's output is predictable and reviewable.
• A contract they read — an AGENTS.md map plus generators as the only interface, so an agent extends the app the same way every time. (Live schema access over MCP is on the roadmap.)
• Boundaries agents can't accidentally cross — tenancy and permissions are structural, not conventions an agent might forget.

The result: a codebase where "add a Subscription entity with an admin screen, tenant-scoped, audited, emitting subscription.created" is a small, safe task — for an agent or a human.

Working prototype — every pillar in the table above is built, tested, and exercised end to end by a demo app, a generator harness, and an agent benchmark. Some two dozen OpenLoam:: modules, from tenancy through SSO, each added the same way: a small in-gem implementation behind a convention, wired to agree with the rest.

What's in the repo

Security-hardened by adversarial review. Each batch of features went through an independent adversarial security review; the reviews found and closed real cross-tenant account-takeover chains, privilege escalations, and PII-leak vectors — every fix landing with a regression test that reproduces the exploit. That the power features (a business-rules engine, bulk import, SSO) are where the holes appeared, and that the guardrails and reviews caught them, is the whole thesis in miniature.

How honest the "prototype" label is — deliberately, each pillar is a minimal in-gem implementation rather than a wrapper around acts_as_tenant/pundit/paper_trail/Rails Event Store: the smallest surface that proves the conventions and the agent flow. Those swaps have since been evaluated one at a time and settled — the in-gem versions stay, and the one real gap they exposed (event capture) was closed in-gem too, in ADR 0007. Custom fields use the portable Rails json column (not Postgres jsonb/GIN) because the demo runs on SQLite. See How OpenLoam works for the pillar-by-pillar breakdown and the decisions behind them.

Try it

cd demo && bundle install && bin/rails db:migrate db:seed
bin/rails test            # guardrail + entity tests
bin/rails server          # → http://localhost:3000/admin

Sign in as anna@example.com (manager in both branches, so she gets the tenant picker) or tomek@example.com (Warsaw only) — password password123 for both.

New here? Start with the Getting Started walkthrough — it builds a multi-tenant feature from rails new to a working approval flow, showing the real commands and exactly what you didn't have to write.

• Architecture map — a visual tour: the module graph, a request lifecycle, the event flow
• Getting started — hands-on, install to first feature
• Overview — plain-language product, use cases, evidence, and risks
• Concept & positioning
• How OpenLoam works — the diagrams above + how every pillar is built
• Tenant isolation & Authorization — the two flagship guarantees, in depth
• Agents — the agent contract, guardrails, the golden-tasks benchmark, and subsystem deep-dives (encryption, SSO, scheduler, events, inbound webhooks, bulk, confirm-mode)
• Reference — configuration, generators, backward compatibility
• Roadmap — ordered backlog, Mercato-informed
• Backward-compatibility contract — the frozen public surfaces
• Architecture decisions & lessons — why things are the way they are, and the gotchas
• Agent pack — everything an AI agent should load to extend a OpenLoam app correctly
• Manifesto
• Contributing

MIT licensed — open-core, like the foundations it stands on.