# heckslabs/hecks architecture

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

- Interactive diagram: https://gitdiagram.com/heckslabs/hecks
- Repository: https://github.com/heckslabs/hecks

## Overview

hecks is an executable business-domain specification language: bluebook declarations define domain behavior and run directly, rather than generating conventional handlers. The principal workflow is authoring a declaration, loading and validating it, dispatching commands through the runtime’s fixed rule-and-mutation order, then persisting state and emitting events; queries read domain state. Separate capabilities project domain data into diagrams and other views, compile it for Rust, and fuzz generated execution sequences. README documentation establishes the main workflow; unsampled subsystem wiring is shown only where the tree or documentation supports it.

Main entry points: [`lib/hecks/ir.rb`](https://github.com/heckslabs/hecks/blob/main/lib/hecks/ir.rb) (Domain IR), [`lib/hecks/runtime/command_interpreter.rb`](https://github.com/heckslabs/hecks/blob/main/lib/hecks/runtime/command_interpreter.rb) (Command interpreter), [`lib/hecks/runtime/dispatcher.rb`](https://github.com/heckslabs/hecks/blob/main/lib/hecks/runtime/dispatcher.rb) (Command dispatcher), [`lib/hecks/bluebook/dsl.rb`](https://github.com/heckslabs/hecks/blob/main/lib/hecks/bluebook/dsl.rb) (Bluebook DSL)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_language["Domain language"]
  node_bluebook["Bluebook DSL<br/>[dsl.rb]"]
  node_builders["DSL builders"]
  node_domain_ir["Domain IR<br/>[ir.rb]"]
  node_meta_validator["Meta validation<br/>[meta_validator.rb]"]
end

subgraph group_execution["Runtime execution"]
  node_loader["Domain loader<br/>[loader.rb]"]
  node_registry["Runtime registry<br/>[registry.rb]"]
  node_dispatcher["Command dispatcher<br/>[dispatcher.rb]"]
  node_command_interpreter["Command interpreter"]
  node_command_rules["Command rules<br/>[command_rules.rb]"]
  node_outbox["Event outbox<br/>[outbox.rb]"]
  node_query_runtime["Query runtime"]
  node_facade["Application facade<br/>[facade.rb]"]
end

subgraph group_adapters["Ports and adapters"]
  node_repository["Persistence repository<br/>[persistence.rb]"]
  node_persistence_adapters["Persistence adapters"]
end

subgraph group_views["Domain projections"]
  node_forms["Domain forms<br/>[forms.rb]"]
  node_projections["Domain projections<br/>[projections.rb]"]
  node_diagrams["Domain diagrams<br/>[diagrams.rb]"]
  node_fuzzing["Generated fuzzing<br/>[fuzzing.rb]"]
end

subgraph group_rust["Rust support"]
  node_rust_parser["Rust parser<br/>[main.rs]"]
  node_rust_codegen["Rust code generation<br/>[main.rs]"]
  node_rust_kernel["Rust runtime kernel<br/>[mod.rs]"]
end

node_author(("Domain author"))

node_author -->|"authors"| node_bluebook
node_bluebook -->|"builds declarations"| node_builders
node_builders -->|"produces IR"| node_domain_ir
node_domain_ir -->|"validates"| node_meta_validator
node_domain_ir -->|"loads domain"| node_loader
node_loader -->|"registers domain"| node_registry
node_registry -->|"supplies runtime"| node_dispatcher
node_dispatcher -->|"dispatches command"| node_command_interpreter
node_command_interpreter -->|"enforces rules"| node_command_rules
node_command_interpreter -->|"persists state"| node_repository
node_repository -->|"uses adapter"| node_persistence_adapters
node_command_interpreter -->|"emits events"| node_outbox
node_dispatcher -->|"runs queries"| node_query_runtime
node_facade -->|"routes requests"| node_dispatcher
node_domain_ir -->|"projects domain"| node_projections
node_projections -->|"renders diagrams"| node_diagrams
node_domain_ir -.->|"generates test domains"| node_fuzzing
node_bluebook -.->|"parses declarations"| node_rust_parser
node_rust_parser -->|"provides parsed IR"| node_rust_codegen
node_rust_codegen -->|"targets runtime"| node_rust_kernel

click node_bluebook "https://github.com/heckslabs/hecks/blob/main/lib/hecks/bluebook/dsl.rb"
click node_builders "https://github.com/heckslabs/hecks/tree/main/lib/hecks/bluebook/dsl"
click node_domain_ir "https://github.com/heckslabs/hecks/blob/main/lib/hecks/ir.rb"
click node_meta_validator "https://github.com/heckslabs/hecks/blob/main/lib/hecks/bluebook/meta_validator.rb"
click node_loader "https://github.com/heckslabs/hecks/blob/main/lib/hecks/runtime/loader.rb"
click node_registry "https://github.com/heckslabs/hecks/blob/main/lib/hecks/runtime/registry.rb"
click node_dispatcher "https://github.com/heckslabs/hecks/blob/main/lib/hecks/runtime/dispatcher.rb"
click node_command_interpreter "https://github.com/heckslabs/hecks/blob/main/lib/hecks/runtime/command_interpreter.rb"
click node_command_rules "https://github.com/heckslabs/hecks/blob/main/lib/hecks/runtime/command_rules.rb"
click node_repository "https://github.com/heckslabs/hecks/blob/main/lib/hecks/ports/persistence.rb"
click node_persistence_adapters "https://github.com/heckslabs/hecks/tree/main/lib/hecks/adapters/driven"
click node_outbox "https://github.com/heckslabs/hecks/blob/main/lib/hecks/runtime/outbox.rb"
click node_query_runtime "https://github.com/heckslabs/hecks/blob/main/lib/hecks/runtime/query_interpreter.rb"
click node_facade "https://github.com/heckslabs/hecks/blob/main/lib/hecks/facade.rb"
click node_forms "https://github.com/heckslabs/hecks/blob/main/lib/hecks/forms.rb"
click node_projections "https://github.com/heckslabs/hecks/blob/main/lib/hecks/projections.rb"
click node_diagrams "https://github.com/heckslabs/hecks/blob/main/lib/hecks/projections/diagrams.rb"
click node_fuzzing "https://github.com/heckslabs/hecks/blob/main/lib/hecks/fuzzing.rb"
click node_rust_parser "https://github.com/heckslabs/hecks/blob/main/rust/parser/src/main.rs"
click node_rust_codegen "https://github.com/heckslabs/hecks/blob/main/rust/codegen/src/main.rs"
click node_rust_kernel "https://github.com/heckslabs/hecks/blob/main/rust/src/kernel/mod.rs"

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_bluebook,node_builders,node_domain_ir,node_meta_validator toneBlue
class node_loader,node_registry,node_dispatcher,node_command_interpreter,node_command_rules,node_outbox,node_query_runtime,node_facade toneAmber
class node_repository,node_persistence_adapters toneMint
class node_forms,node_projections,node_diagrams,node_fuzzing toneRose
class node_rust_parser,node_rust_codegen,node_rust_kernel,node_author toneIndigo
```

## Components

### Domain language

- [Bluebook DSL](https://github.com/heckslabs/hecks/blob/main/lib/hecks/bluebook/dsl.rb): `lib/hecks/bluebook/dsl.rb`
- [DSL builders](https://github.com/heckslabs/hecks/tree/main/lib/hecks/bluebook/dsl): `lib/hecks/bluebook/dsl`
- [Domain IR](https://github.com/heckslabs/hecks/blob/main/lib/hecks/ir.rb): `lib/hecks/ir.rb`
- [Meta validation](https://github.com/heckslabs/hecks/blob/main/lib/hecks/bluebook/meta_validator.rb): `lib/hecks/bluebook/meta_validator.rb`

### Runtime execution

- [Domain loader](https://github.com/heckslabs/hecks/blob/main/lib/hecks/runtime/loader.rb): `lib/hecks/runtime/loader.rb`
- [Runtime registry](https://github.com/heckslabs/hecks/blob/main/lib/hecks/runtime/registry.rb): `lib/hecks/runtime/registry.rb`
- [Command dispatcher](https://github.com/heckslabs/hecks/blob/main/lib/hecks/runtime/dispatcher.rb): `lib/hecks/runtime/dispatcher.rb`
- [Command interpreter](https://github.com/heckslabs/hecks/blob/main/lib/hecks/runtime/command_interpreter.rb): `lib/hecks/runtime/command_interpreter.rb`
- [Command rules](https://github.com/heckslabs/hecks/blob/main/lib/hecks/runtime/command_rules.rb): `lib/hecks/runtime/command_rules.rb`
- [Event outbox](https://github.com/heckslabs/hecks/blob/main/lib/hecks/runtime/outbox.rb): `lib/hecks/runtime/outbox.rb`
- [Query runtime](https://github.com/heckslabs/hecks/blob/main/lib/hecks/runtime/query_interpreter.rb): `lib/hecks/runtime/query_interpreter.rb`
- [Application facade](https://github.com/heckslabs/hecks/blob/main/lib/hecks/facade.rb): `lib/hecks/facade.rb`

### Ports and adapters

- [Persistence repository](https://github.com/heckslabs/hecks/blob/main/lib/hecks/ports/persistence.rb): `lib/hecks/ports/persistence.rb`
- [Persistence adapters](https://github.com/heckslabs/hecks/tree/main/lib/hecks/adapters/driven): `lib/hecks/adapters/driven`

### Domain projections

- [Domain forms](https://github.com/heckslabs/hecks/blob/main/lib/hecks/forms.rb): `lib/hecks/forms.rb`
- [Domain projections](https://github.com/heckslabs/hecks/blob/main/lib/hecks/projections.rb): `lib/hecks/projections.rb`
- [Domain diagrams](https://github.com/heckslabs/hecks/blob/main/lib/hecks/projections/diagrams.rb): `lib/hecks/projections/diagrams.rb`
- [Generated fuzzing](https://github.com/heckslabs/hecks/blob/main/lib/hecks/fuzzing.rb): `lib/hecks/fuzzing.rb`

### Rust support

- [Rust parser](https://github.com/heckslabs/hecks/blob/main/rust/parser/src/main.rs): `rust/parser/src/main.rs`
- [Rust code generation](https://github.com/heckslabs/hecks/blob/main/rust/codegen/src/main.rs): `rust/codegen/src/main.rs`
- [Rust runtime kernel](https://github.com/heckslabs/hecks/blob/main/rust/src/kernel/mod.rs): `rust/src/kernel/mod.rs`

### Other components

- **Domain author**

## Connections

- Domain author → Bluebook DSL: authors
- Bluebook DSL → DSL builders: builds declarations
- DSL builders → Domain IR: produces IR
- Domain IR → Meta validation: validates
- Domain IR → Domain loader: loads domain
- Domain loader → Runtime registry: registers domain
- Runtime registry → Command dispatcher: supplies runtime
- Command dispatcher → Command interpreter: dispatches command
- Command interpreter → Command rules: enforces rules
- Command interpreter → Persistence repository: persists state
- Persistence repository → Persistence adapters: uses adapter
- Command interpreter → Event outbox: emits events
- Command dispatcher → Query runtime: runs queries
- Application facade → Command dispatcher: routes requests
- Domain IR → Domain projections: projects domain
- Domain projections → Domain diagrams: renders diagrams
- Domain IR → Generated fuzzing: generates test domains
- Bluebook DSL → Rust parser: parses declarations
- Rust parser → Rust code generation: provides parsed IR
- Rust code generation → Rust runtime kernel: targets runtime