Framework

The State-Based Collaboration Framework

This framework provides a structured way to design collaboration on shared state in real systems: how state is represented, how it changes, who can act, how intent is recorded, and how each participant experiences the result.

State-Based Collaboration Framework overview diagram

At a high level, the framework organizes collaboration concerns into eight components: states, transitions, actions, events, action-control policies, filters, data-access policies, and projections. Each component is simple on its own, but together they form a coherent model for multi-user systems.

Why a framework for shared state?

When multiple people interact with the same state — a case, a document, a dashboard, a workflow — traditional CRUD thinking starts to crack. Status fields multiply, business rules end up scattered across the codebase, and behavior becomes hard to predict or explain.

Teams often respond by layering ad-hoc logic on top of existing systems: a few extra flags here, a “real-time” update there, a hard-coded condition somewhere else. Over time, the system becomes opaque even to its own builders.

The State-Based Collaboration Framework aims to make these problems thinkable. By breaking collaboration into eight components, it gives architects and teams a shared vocabulary to design, review, and evolve multi-user systems deliberately.

You don't have to adopt every component at once. But recognizing them — and modeling them explicitly — is often enough to turn “weird edge cases” into clear design choices.

The eight components at a glance

Each component answers a different question about collaboration on shared state. Together they describe how change happens, how it's controlled, and how it's perceived by different participants.

State is the central object of collaboration: the case, document, ticket, workflow instance, or aggregate that multiple people care about. Modeling state explicitly means deciding what matters, how it is represented, and which aspects are allowed to change independently.

Key questions

  • What is the core object people are collaborating on?
  • Which parts of its state are shared vs local?
  • Which fields must be consistent at all times, and which can drift?

Typical examples

  • A customer case in a service workflow
  • A claim, order, or ticket moving through a process
  • A shared document or configuration entity

Transitions define how state is allowed to change over time. Instead of free-form status updates, transitions make state evolution explicit: from which state, to which state, under which conditions, and triggered by whom.

Key questions

  • Which state changes are legal, and which should never happen?
  • What needs to be true before a transition can occur?
  • Who is allowed to trigger each transition?

Typical examples

  • Case moving from 'Draft' → 'Submitted' → 'Reviewed' → 'Closed'
  • Document moving from 'In progress' to 'Approved'
  • Order transitioning from 'Pending' to 'Fulfilled' or 'Cancelled'

Actions represent what participants are trying to do: approve, reject, assign, comment, request changes, escalate. They are the bridge between user intent and transitions. Modeling actions explicitly clarifies what people can meaningfully do in each state.

Key questions

  • What do users think they are doing when they click a button?
  • Which actions should be available in each state?
  • Which actions can be undone, and how?

Typical examples

  • Approve, Reject, Request more information
  • Assign to colleague, Reassign to team
  • Submit for review, Escalate, Pause

Events capture what actually occurred: which action was taken, on which state, by which actor, at what time. Events make collaboration auditable and replayable, and they often form the foundation for projections and analytics.

Key questions

  • What do we need to know later about what happened?
  • Which events must be strictly ordered, and which can be eventual?
  • How long do we keep the event history, and where?

Typical examples

  • CaseCreated, CaseUpdated, CaseClosed
  • CommentAdded, AttachmentUploaded
  • ApprovalGiven, EscalationRequested
05

Action-Control Policies

Action-control policies define which actions are allowed for which actors in which states. This is where roles, permissions, and business rules meet the concrete actions and transitions in the system.

Key questions

  • Who is allowed to take each action in each state?
  • Which actions require additional approval or checks?
  • How do temporary roles or delegations affect what people can do?

Typical examples

  • Only reviewers can approve in 'Under review' state
  • Owners can always comment, even after closure
  • Escalation only available to team leads

Filters determine which subset of states or events a participant sees in a given context. They are essential for making collaboration manageable: showing people what matters now, hiding what doesn't, and preventing information overload.

Key questions

  • Which items should each persona see by default?
  • How do we surface urgent or blocked work?
  • How do filters interact with permissions and policies?

Typical examples

  • My cases, My team's cases, Overdue cases
  • Items waiting for my approval
  • Recently updated items related to a project
07

Data-Access Policies

Data-access policies govern which data each participant is allowed to see. They combine security, compliance, and business rules, making sure that collaboration does not leak sensitive information.

Key questions

  • Which fields are visible to which roles?
  • How do we handle cross-organization collaboration?
  • What is the minimal information a participant needs to act?

Typical examples

  • Redacting PII for external collaborators
  • Hiding financial details from non-finance roles
  • Showing only aggregated metrics to certain users

Projections turn events and state into views optimized for particular use cases: timelines, dashboards, queues, histories. They let different participants understand the same underlying reality from their own angle.

Key questions

  • What views help each persona understand what is going on?
  • Which projections need to be real-time, and which can lag?
  • How do projections stay consistent with the underlying state and events?

Typical examples

  • A case timeline with all actions and comments
  • A team dashboard of work in progress
  • An audit log for compliance review

From framework to patterns

The framework gives you language. The patterns show how it plays out in real architectures. A good next step is to explore a pattern that matches a concrete problem you're facing today.