# goatx/goat architecture

> Architecture diagram of the GitHub repository goatx/goat, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/goatx/goat
- Repository: https://github.com/goatx/goat

## Overview

##### Project Type and Purpose
- This is an open-source Go library/tool (“goat” = Go-Oriented Architecture Testing) for modeling and testing state machines and system architectures via Kripke structures and invariant checks.
- The core functionality lets users define states, events, handlers, and invariants, then automatically explore possible transitions and verify properties.

##### File-Structure Analysis
- Top-level Go packages (each .go file):
- environment.go – orchestrates execution contexts
- statemachine.go – core engine that steps through states
- event.go / eventhandler.go – definitions and callbacks for events
- invariant.go – user-supplied checks on states
- kripke.go – builds the Kripke graph of all reachable states
- error.go / version.go – support utilities
- No frontend/backend split—this is purely a Go library plus illustrative example CLIs.

##### Key Components & Interactions
a. User Code (examples/main.go)
- Defines a StateMachine type (states, transitions)
- Registers event handlers via environment.OnTransition
- Supplies invariants via environment.WithInvariant
- Calls environment.Run or a similar entry point
b. environment.go
- Serves as the central coordinator, invoking the statemachine engine
- Hooks user event handlers and invariants into each transition
c. statemachine.go
- Examines current state, available events
- Applies transitions, returns next state(s)
d. kripke.go
- Traverses all possible states/transitions to build a graph
- Annotates nodes/edges for downstream invariant checking
e. invariant.go
- Defines the interface for checks to be run at each state
f. event.go / eventhandler.go
- Event types and the registration/invocation logic for user callbacks
g. error.go / version.go
- Standard support modules

##### Architectural Patterns & Principles
- Modular package separation (each concern in its own file)
- Inversion of control: the library calls user-provided handlers (OnTransition, WithInvariant).
- Graph-based model checking: Kripke structure generation and exploration.
- Extensibility: users can plug in arbitrary handlers and invariants.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "API Layer (User Code)"
        ExampleCS["Client-Server Demo\n(main.go)"]:::user
        click ExampleCS "https://github.com/goatx/goat/blob/main/example/client-server/main.go"
        ExampleSH["Simple Halt Demo\n(main.go)"]:::user
        click ExampleSH "https://github.com/goatx/goat/blob/main/example/simple-halt/main.go"
        ExampleSND["Simple Non-Deterministic Demo\n(main.go)"]:::user
        click ExampleSND "https://github.com/goatx/goat/blob/main/example/simple-non-deterministic/main.go"
        ExampleST["Simple Transition Demo\n(main.go)"]:::user
        click ExampleST "https://github.com/goatx/goat/blob/main/example/simple-transition/main.go"
    end

    subgraph "Core Engine"
        Env["environment.go"]:::core
        click Env "https://github.com/goatx/goat/blob/main/environment.go"
        SM["statemachine.go"]:::core
        click SM "https://github.com/goatx/goat/blob/main/statemachine.go"
    end

    subgraph "Extensibility Points"
        EventDef["event.go"]:::ext
        click EventDef "https://github.com/goatx/goat/blob/main/event.go"
        EventHandler["eventhandler.go"]:::ext
        click EventHandler "https://github.com/goatx/goat/blob/main/eventhandler.go"
        Invariant["invariant.go"]:::ext
        click Invariant "https://github.com/goatx/goat/blob/main/invariant.go"
    end

    KG["kripke.go\n(Kripke Graph Builder)"]:::kripke
    click KG "https://github.com/goatx/goat/blob/main/kripke.go"

    subgraph "Utilities"
        Err["error.go"]:::util
        click Err "https://github.com/goatx/goat/blob/main/error.go"
        Ver["version.go"]:::util
        click Ver "https://github.com/goatx/goat/blob/main/version.go"
    end

    %% Data Flow
    ExampleCS -->|"calls Run()"| Env
    ExampleSH -->|"calls Run()"| Env
    ExampleSND -->|"calls Run()"| Env
    ExampleST -->|"calls Run()"| Env

    Env -->|"Run()/Next()"| SM
    SM -->|"emit events"| EventDef
    SM -->|"invoke callbacks"| EventHandler
    Env -->|"query checks"| Invariant

    Env -.->|"register handlers"| EventHandler
    Env -.->|"register invariants"| Invariant

    SM -->|"transitions"| KG
    Env -->|"history data"| KG

    Env -->|"uses utilities"| Err
    Env -->|"uses utilities"| Ver
    SM -->|"uses utilities"| Err
    SM -->|"uses utilities"| Ver

    classDef core fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef ext fill:#d4edda,stroke:#333,stroke-width:1px;
    classDef util fill:#e2e3e5,stroke:#333,stroke-width:1px;
    classDef user fill:#fff3cd,stroke:#333,stroke-width:1px;
    classDef kripke fill:#d1ecf1,stroke:#333,stroke-width:1px;
```
