From Chaos to Clarity: A Guide to Business-as-Code with Verbs.do

In the complex world of modern software development, business logic often becomes a tangled web. An action as simple as a "user signup" can trigger a cascade of events across different microservices, databases, and third-party APIs. This logic is frequently scattered, poorly documented, and difficult to track. When something goes wrong, or when auditors come knocking, answering the simple question "Who did what, and when?" can become a forensic nightmare.

What if you could treat your business operations with the same clarity, precision, and version control as your application code?

This is the promise of Business-as-Code, a paradigm that transforms abstract operations into tangible, auditable assets. And Verbs.do is the API built to make it a reality. By defining, executing, and logging every business operation as a simple, powerful Verb, you can create a comprehensive, auditable system of record for everything that happens in your organization.

The Problem: The Hidden Language of Your Business

Every business runs on actions. A UserSignsUp, a PaymentIsProcessed, an InvoiceIsGenerated, an ItemIsShipped. Too often, these core actions are not first-class citizens in our codebases. Instead, they are implicit results of a series of function calls and API requests.

This leads to several critical challenges:

Scattered Logic: The logic for CreateInvoice might live partially in your billing service, your CRM, and your email notification system. There's no single source of truth.
Poor Visibility: Without a centralized system, you can't easily see a complete history of every time a specific action was performed.
Auditing Nightmares: For compliance and security, you need a verifiable audit trail. Piecing one together from disparate application logs is time-consuming and error-prone.
Inconsistency: Different teams or different parts of an application might implement the same logical action in slightly different ways, leading to bugs and data integrity issues.

Actions as Code: The Verbs.do Philosophy

Verbs.do introduces a beautifully simple concept: treat every business action as a well-defined Verb. A Verb is a standardized, declarative definition of an operation. It's not just a function; it's a complete, observable business event.

Let's see what that means in practice. Here's how you might define a SignUp action—once—and then use it anywhere.

import { Verb } from 'verbs.do';

// Define a 'SignUp' action once
const signUp = new Verb({
  name: 'SignUp',
  description: 'A new user creates an account.',
  subject: { type: 'User' },
  properties: {
    email: { type: 'string', format: 'email' },
    password: { type: 'string', sensitive: true }
  },
  effects: [
    { name: 'CreateUserRecord' },
    { name: 'SendWelcomeEmail' }
  ]
});

// Execute it anywhere in your application
await signUp.execute({
  subject: { id: 'user_123' },
  properties: {
    email: 'hello@example.com',
    password: 'a-secure-password'
  }
});

By defining the action this way, you've created a reusable, self-documenting piece of your business logic. Let’s break it down:

name & description: A clear, human-readable identifier for the action.
subject: The entity performing the action (in this case, a 'User').
properties: The data schema required to execute the action. Verbs.do can even handle sensitive data, ensuring it's not logged in plain text.
effects: The downstream workflows or side effects that should be triggered upon successful execution. This is the key to powerful workflow automation.

When you call .execute(), Verbs.do doesn't just run code. It validates the input, logs a detailed and immutable event, and orchestrates the defined effects.

The Payoff: Why Your Business Needs Verbs

Adopting this "Actions as Code" model delivers powerful benefits across your entire organization, from engineering to compliance.

1. Bulletproof Audit Trails

Every time a Verb is executed, Verbs.do creates a detailed, immutable record. This log captures the who, what, and when of every action, providing a complete, verifiable audit trail out of the box. This simplifies compliance with regulations like GDPR and SOC 2 and gives you an invaluable tool for security analysis and debugging.

2. Powerful Workflow Automation

The effects array is your gateway to simple and robust automation. When a SignUp Verb executes, Verbs.do can automatically trigger a CreateUserRecord process and a SendWelcomeEmail job. This decouples your services. Your user management service can listen for CreateUserRecord events without ever needing to know what originally caused them.

3. A Centralized System of Record

Your Verb definitions become a central registry of your entire business's capabilities. New developers can instantly understand what actions are possible. Product managers can see a clear map of system workflows. Everyone speaks the same language because the business logic is no longer hidden—it's explicit.

4. Simplified, Decoupled Architecture

Because Verbs.do is API-first, it integrates seamlessly into any architecture. Your frontend can simply execute the SignUp Verb without knowing anything about the complex backend processes it triggers. You can refactor or replace the service that sends welcome emails, and as long as it still listens for the SendWelcomeEmail effect, your core SignUp logic doesn't need to change.

Frequently Asked Questions (FAQ)

What's the difference between a Verb and a regular function call?
While a function just executes code, a Verb represents a complete, observable business action. It automatically handles structured logging, analytics, permissions, and triggers subsequent actions ('effects'), providing a richer, standardized operational layer for your business.

Can I integrate Verbs.do with my existing applications?
Absolutely. Verbs.do is an API-first platform. You define your Verbs and then trigger their execution from anywhere in your codebase using our simple SDKs. This makes it easy to integrate into new or existing systems without requiring a major refactor.

How does Verbs.do help with auditing and compliance?
Every time a Verb is executed, a detailed, immutable log is created. This provides a complete, verifiable audit trail of all actions—who performed them, on what, and when—which dramatically simplifies compliance reporting and security analysis.