A framework for distributed systems
The State-Based Collaboration Framework
Build collaborative systems that are predictable, auditable, and easy to reason about.
A practical model for designing real-world, multi-user, state-driven systems. It brings order to collaboration on shared state: how it evolves, who can change it, how intent is captured, and how reality is presented to users.
What is State-Based Collaboration?
State-based collaboration is built on one foundational idea: every item is always in exactly one state, and collaboration happens by moving the item from one state to the next.
This model makes work clearer, more predictable, and easier to understand — both for individuals and teams. Unlike task lists or complex process engines, a state-based system provides a single, authoritative view of where every item stands and what should happen next.
Learn more about state-based collaboration →One state at a time, one owner at a time, one clear next step.
Why State-Based Collaboration Works
Predictable
Clear state transitions make system behavior deterministic and easy to reason about.
Auditable
Every state change is tracked, creating a complete history of what happened and when.
Testable
Pure functions and explicit transitions make state changes easy to test in isolation.
Clear Ownership
Each state has a clear owner, eliminating confusion about who is responsible.
Guided Transitions
The system shows what actions are allowed, preventing mistakes and reducing cognitive load.
Shared Understanding
Teams use the same vocabulary and mental model, reducing coordination overhead.
Why a Framework for Collaboration on Shared State?
The Problem
Traditional CRUD thinking breaks down when many people touch the same object: approvals, workflows, documents, dashboards, cases, tickets. Conflicts, race conditions, and unclear responsibilities appear everywhere.
Most systems respond with ad-hoc rules sprinkled across services, making behavior hard to reason about and nearly impossible to evolve.
Common issues: Scattered validation logic, unclear ownership, race conditions, inconsistent state, hard-to-debug workflows.
The Solution
State-based collaboration gives teams a shared model: how state is represented, how it is allowed to change, who can act, and how change is recorded and presented.
Instead of bolting on "real-time" features, you design collaboration as a first-class concern in your architecture.
Framework benefits: Centralized rules, explicit ownership, deterministic transitions, clear audit trail, testable behavior.
Overview: The 8 components
View framework details →
The framework organizes collaboration concerns into eight components: states, transitions, actions, events, policies, filters, and projections. Together, they describe how shared state changes and how each participant experiences it.
The eight components of state-based collaboration
These components give you a vocabulary for reasoning about multi-user systems. You don't have to adopt all of them at once, but naming them makes collaboration problems tractable.
States
Where collaboration lives — the shared truth participants operate on.
View component →Transitions
How state moves forward through controlled, auditable steps.
View component →Actions
User-driven intent that triggers change in the system.
View component →Events
The chronological record of what happened, by whom, and when.
View component →Action-Control Policies
Who can do what in a given state, encoding rules and constraints.
View component →Filters
How each participant’s view is shaped by context and relevance.
View component →Data-Access Policies
Why users see what they see, aligning visibility with governance.
View component →Projections
Presenting collaborative reality through derived, read-optimized views.
View component →Common Use Cases
Document Workflows
Approval processes, content review, publishing pipelines. Track documents through Draft → Review → Approved → Published.
Bug & Issue Tracking
Manage tickets through Open → In Progress → In Review → QA → Done with clear ownership at each stage.
Approval Processes
Expense approvals, purchase requests, access requests. Clear states and explicit transitions prevent confusion.
Case Management
Support cases, legal matters, insurance claims. Track cases through their lifecycle with audit trails.
Hiring Workflows
Candidate pipelines: Applied → Screen → Interview → Offer → Hired. Clear handoffs between recruiters and hiring managers.
Order Processing
E-commerce orders: Pending → Processing → Shipped → Delivered. Each state has clear responsibilities and next steps.
Featured collaboration patterns
View all patterns →State Machine Design Pattern
Model state transitions explicitly as a finite state machine, making allowed state changes clear, testable, and auditable.
View pattern →CQRS (Command Query Responsibility Segregation)
Separate read and write operations into distinct models and paths. This pattern optimizes for different performance characteristics and allows read and write sides to evolve independently.
View pattern →State Reducer Pattern
A state reducer is a pure function that takes an action and current state, then returns either an error or a new state. This pattern provides a deterministic, testable way to handle state transitions.
View pattern →Policy Engines
A policy engine evaluates rules to determine authorization and data visibility. It separates access control logic from business logic, making permissions explicit, testable, and maintainable.
View pattern →Articles & essays
View all articles →Undo Operations in Collaborative Systems
Undo is deceptively simple in single-user applications but becomes complex in collaborative systems. This article explores the challenges and presents a practical approach for implementing undo in state-based collaboration.
Synchronous vs. Async Projections
Projections are by default asynchronous for command execution, but GUIs need synchronous action and projection generation to ensure correct operation. This article explores when to use each approach and how to balance performance with correctness.
CRUD, REST, and the Case for Explicit Commands
CRUD and REST interfaces are centered on manipulating resources, not expressing business actions. This article explores why explicit command interfaces are essential for collaborative systems and how they create clearer workflows and simpler UIs.
State Systems vs. Process Systems: Why Only One Can Have Parallel Tasks
Understanding the fundamental difference between state-based collaboration and BPMN-style process collaboration. This article explores why state systems can only have one active state at a time, while process systems can have multiple active tasks in parallel.
Project Management Tools as a Special Case of State-Based Collaboration
Most modern project management tools implement a simplified form of state-based collaboration. This article explains how tools like Trello, Asana, and Jira fit into the broader idea of state-based collaboration, why they work well for simple task flows, and where they fall short when workflows become more complex.
Who this framework is for
State-based collaboration is aimed at teams building serious multi-participant systems, not just toy demos.
- • Engineering leaders adding collaboration to existing products
- • Architects designing distributed workflows and state machines
- • Senior developers wrestling with conflicts and consistency
- • Product teams aligning UX with real architectural constraints
About the framework's author
The State-Based Collaboration Framework is developed by Jorge Leal Portela, based on years of working on distributed systems, collaborative workflows, and state-driven architectures.
This site is a living notebook: patterns, trade-offs, and design notes for teams who need collaboration that survives latency, partial failure, and organizational complexity.
Over time it will grow into a pattern library and a set of implementable guidance you can apply in your own systems.
Ready to go deeper?
Start with the framework overview, then pick one collaboration pattern that matches a real problem in your system today.