Skip to main content

Why Your Next App Should Be a State Machine

· 4 min read
Osamah Alghanmi
Osamah Alghanmi
Co-Founder & Technical Lead

Your development team ships features fast. But bugs keep coming back. Deployments break on Fridays. The codebase grows, and so does the fear of touching it.

The problem isn't your team. It's the architecture.

The Hidden Cost of "Move Fast and Break Things"​

The software industry spends an estimated $2.41 trillion annually on fixing bad code (CISQ 2022). Not on building new features. On fixing what already exists.

Most of this cost comes from a single root cause: unpredictable state.

User clicks "Submit" →
  Is the form valid? (depends on 12 boolean flags)
  Is the user authenticated? (check a global variable)
  Is the network available? (hope for the best)
  Has this already been submitted? (add another boolean)

Every boolean flag doubles the number of possible states. With 10 flags, your app has 1,024 possible states, most of which nobody has tested.

What If Your App Could Only Be in States You Defined?​

That's what a state machine gives you.

Instead of scattered booleans and implicit state, you declare exactly what's possible:

{
  "states": [
    { "name": "Draft", "isInitial": true },
    { "name": "Submitted" },
    { "name": "UnderReview" },
    { "name": "Approved" },
    { "name": "Rejected" }
  ]
}

Five states. Not 1,024. Every transition between them is explicit:

{
  "from": "Draft",
  "to": "Submitted",
  "event": "SUBMIT",
  "guard": ["and",
    ["not-empty", "@entity.title"],
    ["not-empty", "@entity.description"]
  ]
}

The guard says: you can't submit without a title and description. This isn't a validation library you might forget to call. It's architecture that enforces the rule.

The Business Case​

1. Bugs Become Architecturally Impossible​

In a traditional app, you prevent bugs with tests. Tests cover the cases you thought of. State machines prevent bugs by making invalid states unrepresentable.

A modal that can't be closed? The Almadar compiler rejects it:

Error: CIRCUIT_NO_OVERLAY_EXIT
  State 'EditModal' renders to 'modal' slot but has no exit transition.
  Users will be stuck in this overlay.

This error fires at compile time. Before deployment. Before QA. Before users.

2. Development Speed Increases​

With Almadar, a complete application — frontend, backend, database, API — compiles from a single schema file:

orbital compile invoice-app.orb --shell typescript -o app/

A typical CRUD application that takes 2-4 weeks to build traditionally takes days with a schema-first approach. The generated code handles routing, state management, API endpoints, and database models.

3. Compliance Becomes Automatic​

For regulated industries, the schema is the specification:

{
  "from": "InProgress",
  "to": "Completed",
  "event": "COMPLETE",
  "guard": ["and",
    ["=", "@entity.allFieldsFilled", true],
    [">=", "@entity.inspectorSignatures", 2]
  ]
}

An inspector can't complete a report without all fields filled and two signatures. This isn't a suggestion in a training manual. It's enforced by the system.

Auditors don't need to review code. They review the schema — a readable JSON document that is the system.

4. Onboarding Takes Hours, Not Weeks​

New developers don't need to understand thousands of lines of React, Express, and Redux. They read the schema:

  • Entities tell them what data exists
  • States tell them what the app can do
  • Transitions tell them how it moves between states
  • Guards tell them the business rules
  • Effects tell them what happens on each transition

The schema is the documentation. It's always accurate because it is the running system.

Real Example: Government Inspection System​

We built a field inspection system for government use. Traditional approach: 6 months, 5 developers, complex workflow management.

With Almadar:

  • 5 inspection phases modeled as states (Introduction, Content, Preparation, Record, Closing)
  • Legal requirements encoded as guards (can't close without all mandatory fields)
  • Audit trail built into the state machine (every transition is logged)
  • Document generation triggered as effects on the Closing transition

The schema is 400 lines. It generates a complete web application with backend API, database models, and inspector-facing UI.

When State Machines Don't Fit​

State machines aren't for everything:

  • Pure content sites (blogs, landing pages) — no complex state
  • One-off scripts — not worth the structure
  • Highly exploratory prototypes — sometimes you need to figure out what you're building first

But for any application with workflows, forms, approvals, multi-step processes, or user roles — which is most business software — state machines eliminate entire categories of bugs.

The Takeaway​

The question isn't whether state machines are worth learning. It's whether you can afford the bugs you'll ship without them.

Almadar makes state machines practical for business applications:

  • One schema file → full-stack application
  • Compile-time bug prevention → fewer production incidents
  • Readable schemas → faster audits and onboarding
  • Guards and transitions → compliance as code

Your users won't know they're using a state machine. They'll just notice that things work.

Ready to try it? Check out the Getting Started guide.

Recent Posts