A framework for distributed systems
The State-Based Collaboration Framework
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.
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 →Why a framework for collaboration on shared state?
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.
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.
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.
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.