Event Modeling
as Code

A human-readable JSON format for designing event-driven systems. Version control your architecture. Generate code from your model.

🚀 Open Giraflow See Example →

Get Started in Seconds

One command to install, one command to run

Terminal

$ npm install -g giraflow

$ cd your-project

$ giraflow

🦒 Watching your-project.giraflow.json

🌐 Open http://localhost:3333

How it works

Giraflow watches your .giraflow.json file and serves a live web visualization. Every change is reflected instantly.

Keep your model in version control alongside your code. Review changes in pull requests. Generate documentation automatically.

Auto-detects .giraflow.json files in your project
Hot reload on every save
Works offline, no account needed
Export to SVG, PowerPoint, or HTML

Why Giraflow?

Event Modeling is powerful. But where do you store the model?

❌ The Problem

Proprietary tools lock your designs into their platforms
Visual-only formats can't be version controlled meaningfully
Models live outside your codebase, getting stale
Manual sync between design and implementation

✅ The Giraflow Solution

Plain JSON – own your models, no vendor lock-in
Git-friendly – meaningful diffs and history
Code-adjacent – model lives with implementation
Single source of truth – generate from model

Features

Everything you need to model event-driven systems

📝

Human-Readable JSON

Edit with any text editor. No proprietary formats. Easy to read, write, and review in pull requests.

🔄

Live Web Preview

Browser-based visualization with hot reload. See timeline, slices, and scenarios update as you type.

💻

CLI Tool

Terminal visualization for quick checks. Timeline, slice, and table views. Export to file.

🧪

Specifications

Given-When-Then scenarios for commands and projections. Your model becomes executable documentation.

🎨

Wireframes

Link HTML mockups to actors. Visualize what each user role sees and interacts with.

🔗

Schema Validation

JSON Schema for IDE support. Autocomplete, validation, and documentation in your editor.

Simple & Expressive

Model your entire system in one readable file

order-system.giraflow.json

{
  "name": "Order System",
  "timeline": [
    { 
      "type": "event", 
      "name": "OrderPlaced", 
      "tick": 10
    },
    { 
      "type": "state", 
      "name": "PendingOrders", 
      "tick": 20,
      "sourcedFrom": ["OrderPlaced"]
    },
    { 
      "type": "actor", 
      "name": "Warehouse", 
      "tick": 30,
      "readsView": "PendingOrders",
      "sendsCommand": "ShipOrder"
    },
    { 
      "type": "command", 
      "name": "ShipOrder", 
      "tick": 40
    },
    { 
      "type": "event", 
      "name": "OrderShipped", 
      "tick": 50
    }
  ]
}

Timeline Elements

●

Event – Something that happened
Past tense: OrderPlaced, UserRegistered

◆

State View – Read model from events
Noun: PendingOrders, UserProfile

○

Actor – Who reads and acts
Role: Customer, Admin, System

▶

Command – Intent to do something
Imperative: PlaceOrder, ShipOrder

How It Works

From idea to implementation in four steps

Model

Define your timeline with events, states, actors, and commands in JSON

Visualize

Use the web preview or CLI to see your model as a swimlane diagram

Specify

Add scenarios with Given-When-Then to define behavior

Implement

Build your system guided by the model, generate tests from specs

Event Modelingas Code