# statelyai/xstate architecture

> Architecture diagram of the GitHub repository statelyai/xstate, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/statelyai/xstate
- Repository: https://github.com/statelyai/xstate

## Overview

XState is a JavaScript/TypeScript state-management monorepo: its core models state machines and actors, then interprets events into snapshots and effects. Framework packages expose those actors to UI reactivity; a separate event-based store serves simpler state needs, and inspection and graph utilities support visibility and path analysis. The main user workflow is define logic, create and run an actor, send events, and observe snapshots. README capability descriptions inform unsampled package branches; only the sampled adapter and inspector internals support detailed wiring claims.

Main entry points: [`packages/core/src/State.ts`](https://github.com/statelyai/xstate/blob/main/packages/core/src/State.ts) (Running Actor), [`packages/core/src/createActor.ts`](https://github.com/statelyai/xstate/blob/main/packages/core/src/createActor.ts) (Actor Creation), [`packages/xstate-store/src/store.ts`](https://github.com/statelyai/xstate/blob/main/packages/xstate-store/src/store.ts) (Store API), [`packages/core/src/transition.ts`](https://github.com/statelyai/xstate/blob/main/packages/core/src/transition.ts) (Transitions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Machines and Actors"]
  node_machine["Machine Definition<br/>[createMachine.ts]"]
  node_state_logic["State Logic<br/>[StateMachine.ts]"]
  node_actor_factory["Actor Creation<br/>[createActor.ts]"]
  node_actor["Running Actor<br/>[State.ts]"]
  node_transitions["Transitions<br/>[transition.ts]"]
  node_state_nodes["State Nodes<br/>[StateNode.ts]"]
  node_actions["Actions<br/>[actions.ts]"]
  node_guards["Guards<br/>[guards.ts]"]
  node_actors["Actor Logic<br/>[index.ts]"]
  node_mailbox["Event Mailbox<br/>[Mailbox.ts]"]
  node_snapshot["Snapshots<br/>[getNextSnapshot.ts]"]
end

subgraph group_integrations["UI Integrations"]
  node_react["React Bindings<br/>[useActor.ts]"]
  node_solid["Solid Bindings<br/>[useActor.ts]"]
  node_svelte["Svelte Bindings<br/>[useActor.ts]"]
  node_vue["Vue Bindings<br/>[useActor.ts]"]
end

subgraph group_store["Event Store"]
  node_store_api["Store API<br/>[store.ts]"]
  node_store_state["Store State<br/>[atom.ts]"]
  node_persistence["Persistence<br/>[persist.ts]"]
  node_store_bindings["Store Bindings<br/>[index.ts]"]
end

subgraph group_tools["Inspection and Graphs"]
  node_inspector["Inspector<br/>[inspectMachine.ts]"]
  node_browser_inspector["Browser Inspector<br/>[browser.ts]"]
  node_server_inspector["WebSocket Inspector<br/>[server.ts]"]
  node_graph_tools["Graph Traversal<br/>[index.ts]"]
  node_model_testing["Model Testing<br/>[TestModel.ts]"]
  node_paths["Generated Paths<br/>[pathGenerators.ts]"]
end

node_developer(("Application Developer"))
node_app(("Application"))
node_websocket(("WebSocket Clients"))

node_developer -->|"defines"| node_machine
node_machine -->|"creates logic"| node_state_logic
node_app -->|"starts runtime"| node_actor_factory
node_actor_factory -->|"instantiates"| node_state_logic
node_actor_factory -->|"creates"| node_actor
node_app -->|"sends events"| node_actor
node_actor -->|"queues events"| node_mailbox
node_actor -->|"processes events"| node_transitions
node_transitions -->|"selects transitions"| node_state_nodes
node_transitions -->|"checks conditions"| node_guards
node_transitions -->|"executes actions"| node_actions
node_actions -->|"invokes actors"| node_actors
node_actor -->|"emits snapshots"| node_snapshot
node_snapshot -->|"observed by"| node_app
node_react -->|"creates actor"| node_actor_factory
node_react -->|"subscribes"| node_actor
node_solid -->|"creates actor"| node_actor_factory
node_solid -->|"reads snapshots"| node_actor
node_svelte -->|"creates actor"| node_actor_factory
node_svelte -->|"subscribes"| node_actor
node_vue -->|"creates actor"| node_actor_factory
node_vue -->|"selects snapshots"| node_actor
node_developer -->|"defines handlers"| node_store_api
node_app -->|"sends events"| node_store_api
node_store_api -->|"updates state"| node_store_state
node_store_api -.->|"persists state"| node_persistence
node_store_api -.->|"exposes bindings"| node_store_bindings
node_app -.->|"configures inspection"| node_browser_inspector
node_browser_inspector -.->|"forwards events"| node_inspector
node_actor -.->|"reports activity"| node_inspector
node_server_inspector -->|"creates service"| node_inspector
node_server_inspector -->|"broadcasts inspection"| node_websocket
node_websocket -->|"forwards messages"| node_server_inspector
node_developer -->|"requests traversal"| node_graph_tools
node_graph_tools -->|"analyzes machine"| node_machine
node_model_testing -->|"uses traversal"| node_graph_tools
node_model_testing -->|"generates paths"| node_paths

click node_machine "https://github.com/statelyai/xstate/blob/main/packages/core/src/createMachine.ts"
click node_state_logic "https://github.com/statelyai/xstate/blob/main/packages/core/src/StateMachine.ts"
click node_actor_factory "https://github.com/statelyai/xstate/blob/main/packages/core/src/createActor.ts"
click node_actor "https://github.com/statelyai/xstate/blob/main/packages/core/src/State.ts"
click node_transitions "https://github.com/statelyai/xstate/blob/main/packages/core/src/transition.ts"
click node_state_nodes "https://github.com/statelyai/xstate/blob/main/packages/core/src/StateNode.ts"
click node_actions "https://github.com/statelyai/xstate/blob/main/packages/core/src/actions.ts"
click node_guards "https://github.com/statelyai/xstate/blob/main/packages/core/src/guards.ts"
click node_actors "https://github.com/statelyai/xstate/blob/main/packages/core/src/actors/index.ts"
click node_mailbox "https://github.com/statelyai/xstate/blob/main/packages/core/src/Mailbox.ts"
click node_snapshot "https://github.com/statelyai/xstate/blob/main/packages/core/src/getNextSnapshot.ts"
click node_react "https://github.com/statelyai/xstate/blob/main/packages/xstate-react/src/useActor.ts"
click node_solid "https://github.com/statelyai/xstate/blob/main/packages/xstate-solid/src/useActor.ts"
click node_svelte "https://github.com/statelyai/xstate/blob/main/packages/xstate-svelte/src/useActor.ts"
click node_vue "https://github.com/statelyai/xstate/blob/main/packages/xstate-vue/src/useActor.ts"
click node_store_api "https://github.com/statelyai/xstate/blob/main/packages/xstate-store/src/store.ts"
click node_store_state "https://github.com/statelyai/xstate/blob/main/packages/xstate-store/src/atom.ts"
click node_persistence "https://github.com/statelyai/xstate/blob/main/packages/xstate-store/src/persist.ts"
click node_store_bindings "https://github.com/statelyai/xstate/blob/main/packages/xstate-store-react/src/index.ts"
click node_inspector "https://github.com/statelyai/xstate/blob/main/packages/xstate-inspect/src/inspectMachine.ts"
click node_browser_inspector "https://github.com/statelyai/xstate/blob/main/packages/xstate-inspect/src/browser.ts"
click node_server_inspector "https://github.com/statelyai/xstate/blob/main/packages/xstate-inspect/src/server.ts"
click node_graph_tools "https://github.com/statelyai/xstate/blob/main/packages/core/src/graph/index.ts"
click node_model_testing "https://github.com/statelyai/xstate/blob/main/packages/core/src/graph/TestModel.ts"
click node_paths "https://github.com/statelyai/xstate/blob/main/packages/core/src/graph/pathGenerators.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_machine,node_state_logic,node_actor_factory,node_actor,node_transitions,node_state_nodes,node_actions,node_guards,node_actors,node_mailbox,node_snapshot,node_websocket toneBlue
class node_react,node_solid,node_svelte,node_vue toneAmber
class node_store_api,node_store_state,node_persistence,node_store_bindings toneMint
class node_inspector,node_browser_inspector,node_server_inspector,node_graph_tools,node_model_testing,node_paths toneRose
class node_developer,node_app toneIndigo
```

## Components

### Machines and Actors

- [Machine Definition](https://github.com/statelyai/xstate/blob/main/packages/core/src/createMachine.ts): `packages/core/src/createMachine.ts`
- [State Logic](https://github.com/statelyai/xstate/blob/main/packages/core/src/StateMachine.ts): `packages/core/src/StateMachine.ts`
- [Actor Creation](https://github.com/statelyai/xstate/blob/main/packages/core/src/createActor.ts): `packages/core/src/createActor.ts`
- [Running Actor](https://github.com/statelyai/xstate/blob/main/packages/core/src/State.ts): `packages/core/src/State.ts`
- [Transitions](https://github.com/statelyai/xstate/blob/main/packages/core/src/transition.ts): `packages/core/src/transition.ts`
- [State Nodes](https://github.com/statelyai/xstate/blob/main/packages/core/src/StateNode.ts): `packages/core/src/StateNode.ts`
- [Actions](https://github.com/statelyai/xstate/blob/main/packages/core/src/actions.ts): `packages/core/src/actions.ts`
- [Guards](https://github.com/statelyai/xstate/blob/main/packages/core/src/guards.ts): `packages/core/src/guards.ts`
- [Actor Logic](https://github.com/statelyai/xstate/blob/main/packages/core/src/actors/index.ts): `packages/core/src/actors/index.ts`
- [Event Mailbox](https://github.com/statelyai/xstate/blob/main/packages/core/src/Mailbox.ts): `packages/core/src/Mailbox.ts`
- [Snapshots](https://github.com/statelyai/xstate/blob/main/packages/core/src/getNextSnapshot.ts): `packages/core/src/getNextSnapshot.ts`

### UI Integrations

- [React Bindings](https://github.com/statelyai/xstate/blob/main/packages/xstate-react/src/useActor.ts): `packages/xstate-react/src/useActor.ts`
- [Solid Bindings](https://github.com/statelyai/xstate/blob/main/packages/xstate-solid/src/useActor.ts): `packages/xstate-solid/src/useActor.ts`
- [Svelte Bindings](https://github.com/statelyai/xstate/blob/main/packages/xstate-svelte/src/useActor.ts): `packages/xstate-svelte/src/useActor.ts`
- [Vue Bindings](https://github.com/statelyai/xstate/blob/main/packages/xstate-vue/src/useActor.ts): `packages/xstate-vue/src/useActor.ts`

### Event Store

- [Store API](https://github.com/statelyai/xstate/blob/main/packages/xstate-store/src/store.ts): `packages/xstate-store/src/store.ts`
- [Store State](https://github.com/statelyai/xstate/blob/main/packages/xstate-store/src/atom.ts): `packages/xstate-store/src/atom.ts`
- [Persistence](https://github.com/statelyai/xstate/blob/main/packages/xstate-store/src/persist.ts): `packages/xstate-store/src/persist.ts`
- [Store Bindings](https://github.com/statelyai/xstate/blob/main/packages/xstate-store-react/src/index.ts): `packages/xstate-store-react/src/index.ts`

### Inspection and Graphs

- [Inspector](https://github.com/statelyai/xstate/blob/main/packages/xstate-inspect/src/inspectMachine.ts): `packages/xstate-inspect/src/inspectMachine.ts`
- [Browser Inspector](https://github.com/statelyai/xstate/blob/main/packages/xstate-inspect/src/browser.ts): `packages/xstate-inspect/src/browser.ts`
- [WebSocket Inspector](https://github.com/statelyai/xstate/blob/main/packages/xstate-inspect/src/server.ts): `packages/xstate-inspect/src/server.ts`
- [Graph Traversal](https://github.com/statelyai/xstate/blob/main/packages/core/src/graph/index.ts): `packages/core/src/graph/index.ts`
- [Model Testing](https://github.com/statelyai/xstate/blob/main/packages/core/src/graph/TestModel.ts): `packages/core/src/graph/TestModel.ts`
- [Generated Paths](https://github.com/statelyai/xstate/blob/main/packages/core/src/graph/pathGenerators.ts): `packages/core/src/graph/pathGenerators.ts`

### Other components

- **Application Developer**
- **Application**
- **WebSocket Clients**

## Connections

- Application Developer → Machine Definition: defines
- Machine Definition → State Logic: creates logic
- Application → Actor Creation: starts runtime
- Actor Creation → State Logic: instantiates
- Actor Creation → Running Actor: creates
- Application → Running Actor: sends events
- Running Actor → Event Mailbox: queues events
- Running Actor → Transitions: processes events
- Transitions → State Nodes: selects transitions
- Transitions → Guards: checks conditions
- Transitions → Actions: executes actions
- Actions → Actor Logic: invokes actors
- Running Actor → Snapshots: emits snapshots
- Snapshots → Application: observed by
- React Bindings → Actor Creation: creates actor
- React Bindings → Running Actor: subscribes
- Solid Bindings → Actor Creation: creates actor
- Solid Bindings → Running Actor: reads snapshots
- Svelte Bindings → Actor Creation: creates actor
- Svelte Bindings → Running Actor: subscribes
- Vue Bindings → Actor Creation: creates actor
- Vue Bindings → Running Actor: selects snapshots
- Application Developer → Store API: defines handlers
- Application → Store API: sends events
- Store API → Store State: updates state
- Store API → Persistence: persists state
- Store API → Store Bindings: exposes bindings
- Application → Browser Inspector: configures inspection
- Browser Inspector → Inspector: forwards events
- Running Actor → Inspector: reports activity
- WebSocket Inspector → Inspector: creates service
- WebSocket Inspector → WebSocket Clients: broadcasts inspection
- WebSocket Clients → WebSocket Inspector: forwards messages
- Application Developer → Graph Traversal: requests traversal
- Graph Traversal → Machine Definition: analyzes machine
- Model Testing → Graph Traversal: uses traversal
- Model Testing → Generated Paths: generates paths