craft

README

Craft

A domain-specific language for modeling business use cases and domain interactions, with automatic generation of C4, domain-flow, and sequence diagrams.

Documentation · Examples · VS Code Extension

---

Install

brew install tcarcao/craft/craft

Verify:

craft --help

Use as a Go library

Parse Craft source in-process, without shelling out to the CLI:

go get github.com/tcarcao/craft/v2/pkg/craft

import "github.com/tcarcao/craft/v2/pkg/craft"

// Single file.
doc, diags, err := craft.Parse("example.craft", src)

// Multiple files, merged with cross-file resolution.
doc, diags, err := craft.ParseFiles(map[string][]byte{
    "billing.craft": billingSrc,
    "catalog.craft": catalogSrc,
})

Diagnostics are returned as data (diags); err is reserved for programmer errors. Requires Go 1.25+. The module path carries its major version (/v2), per Go's semantic import versioning.

---

Quick example

actors {
    user Customer
    service Database
}

domain Order {
    Cart
    Checkout
    Payment
}

services {
    OrderService {
        contexts: Cart, Checkout, Payment
        data-stores: order_db
        language: golang
        deployment: rolling
    }
}

use_case "Purchase Item" {
    when Customer adds item to cart
        Cart validates item availability
        Cart notifies "Item Added to Cart"

    when Checkout listens "Item Added to Cart"
        Checkout asks Payment to process payment
        Payment notifies "Payment Processed"
}

Run craft validate, craft generate, or craft inspect on any .craft file. See the CLI reference.

---

VS Code Extension

The Craft VS Code extension adds syntax highlighting, domain/services tree views, and live diagram previews. Install from GitHub releases.

---

Claude Code skill

If you use Claude Code, install the Craft skill to get AI assistance for writing and extending .craft files:

npx skills add tcarcao/craft

The skill teaches Claude the full grammar, modeling patterns, and event-driven choreography conventions. See the skill docs.

---

Examples

See examples/ for complete models:

• Banking system — financial services with fraud detection
• User management — authentication and profile management

---

Development

Prerequisites

• Go 1.22+
• Docker or Podman

Build

# First-time setup — pulls ANTLR image and regenerates parser
make fresh-setup

# Build and run the server
make docker-build && make docker-run

# Run tests
make test

Grammar changes

The ANTLR grammar lives in tools/antlr-grammar/Craft.g4. Generated parser code in pkg/parser/ is gitignored — regenerate with:

make generate-grammar

---

License

MIT