Modeling
SynthEvents
Remembering
EventSourcingDB
Building
ArchitectureKit
Version
2.1 · latest2.01.0
Docs / ArchitectureKit 1.0 / Quickstart / Quickstart

Quickstart

This quickstart gets a first command running with ArchitectureKit in a few minutes: you start EventSourcingDB with Docker, define a command, an event, and the state to decide on, and execute the command. It uses a temporary setup for development and testing – for everything else, see the links at the end.

Before You Begin#

You need Go 1.27.1 or later, which ArchitectureKit requires, and Docker to run EventSourcingDB.

Compatibility

ArchitectureKit 1.0 runs with EventSourcingDB 1.1 and later.

Starting EventSourcingDB#

ArchitectureKit stores its events in EventSourcingDB. Start it with the following command. On the first start, Docker downloads the image:

docker run -it -p 3000:3000 \
  thenativeweb/eventsourcingdb run \
  --api-token=secret \
  --data-directory-temporary \
  --http-enabled \
  --https-enabled=false

This starts EventSourcingDB on port 3000, with the API token secret, a temporary data directory that is cleaned up on shutdown, and unencrypted HTTP.

For Development and Testing Only

These settings simplify the setup but are not secure for production. For production-ready configurations, see Running EventSourcingDB.

Creating a Module#

In a second terminal, create a Go module, and add ArchitectureKit and the client SDK for Go:

Changed in 2.0

mkdir library
cd library
go mod init library
go get github.com/thenativeweb/architecturekit-golang/architecturekit github.com/thenativeweb/eventsourcingdb-client-golang/eventsourcingdb

Defining a Command, an Event, and the State#

Create a file main.go. A command describes what someone wants to do, an event describes what has happened, and the state holds what a command needs to decide on. The example acquires a book for a library:

Changed in 2.0

package main

import (
  "context"
  "fmt"
  "log"
  "net/url"

  "github.com/thenativeweb/architecturekit-golang/architecturekit"
  "github.com/thenativeweb/eventsourcingdb-client-golang/eventsourcingdb"
)

type AcquireBook struct {
  BookID string
  Title  string
  Author string
  ISBN   string
}

func (c AcquireBook) Subject() string {
  return "/books/" + c.BookID
}

func (c AcquireBook) Preconditions() []architecturekit.Precondition {
  return []architecturekit.Precondition{
    architecturekit.OnStateRead(),
  }
}

type BookAcquired struct {
  Title  string `json:"title"`
  Author string `json:"author"`
  ISBN   string `json:"isbn"`
}

func (BookAcquired) EventType() string {
  return "io.eventsourcingdb.library.book-acquired"
}

type Book struct {
  IsAcquired bool
}

var bookState = architecturekit.NewState(Book{}).
  Evolve(func(book Book, event BookAcquired) Book {
    book.IsAcquired = true
    return book
  })

The command names the subject it acts on, and its precondition OnStateRead makes sure that its events are only written if nothing has been written to that subject since the state was read. The event names its event type, the kit derives the JSON schema of its data from the struct, and the state evolves from every BookAcquired event. For details, see Defining Commands, Defining Events, and Defining State.

Deciding on the Command#

A decider connects the state with the decision made on it. Create it with the NewDecider function, from the state and a function that receives the command and the current state, and returns the events to write, or an error to reject the command. Add it to main.go:

var acquireBook = architecturekit.NewDecider(bookState,
  func(ctx context.Context, cmd AcquireBook, book Book) ([]architecturekit.Event, error) {
    if book.IsAcquired {
      return nil, architecturekit.NewDomainError("book %s has already been acquired", cmd.BookID)
    }

    return []architecturekit.Event{
      BookAcquired{
        Title:  cmd.Title,
        Author: cmd.Author,
        ISBN:   cmd.ISBN,
      },
    }, nil
  })

For details, see Making Decisions.

Executing the Command#

Finally, create a client and a store, register the schema of the event, and execute the command. Add the main function to main.go:

func main() {
  baseURL, err := url.Parse("http://localhost:3000")
  if err != nil {
    log.Fatal(err)
  }

  client, err := eventsourcingdb.NewClient(baseURL, "secret")
  if err != nil {
    log.Fatal(err)
  }

  store := architecturekit.NewStore(client, "https://library.eventsourcingdb.io")

  err = architecturekit.RegisterSchemas(context.TODO(), store, bookState.Schemas())
  if err != nil {
    log.Fatal(err)
  }

  writtenEvents, err := architecturekit.Execute(
    context.TODO(),
    store,
    acquireBook,
    AcquireBook{
      BookID: "42",
      Title:  "2001 – A Space Odyssey",
      Author: "Arthur C. Clarke",
      ISBN:   "978-0756906788",
    },
  )
  if err != nil {
    log.Fatal(err)
  }

  for _, event := range writtenEvents {
    fmt.Println(event.ID, event.Type, event.Subject)
  }
}

NewStore creates the store from the client and the source to use for all events you write, and returns a *Store, which reads and writes the events of all commands (see Creating a Store). RegisterSchemas registers the schema of the event with the database, which from then on rejects events that do not match it. Execute reads the events of the book's subject, evolves the state from them, calls the decider, and writes the events it returns.

Note that calling NewStore with nil as the client, or as one of the options, panics.

Run the program:

go run .

It prints the ID, the type, and the subject of the written event:

0 io.eventsourcingdb.library.book-acquired /books/42

Run it again. This time, the state shows that the book has already been acquired, so the decider rejects the command, and nothing is written:

2026/10/07 08:22:39 book 42 has already been acquired
exit status 1

Shutting Down#

Press Ctrl+C in the first terminal to shut down EventSourcingDB. Since the data directory is temporary, the event is gone afterwards.

Next Steps#

Further Resources#