Architecture Map

BLOGE is best understood as a layered orchestration system. The core remains embeddable, but the current source tree has grown beyond a small DAG library: it now includes a DSL platform, extension runtimes, durable operations, common operators, and authoring tools.

This page is verified against BLOGE 0.9.8-RC1 source commit cc38fbe5bb79ccc603888e4307cfe566d4674ffc.

Five Layers

Layer	Primary modules	What it owns
Execution kernel	bloge-core, bloge-runtime-spi	Graph model, scheduler, operators, context, resilience, saga, timers, work items, graph versioning
Language and contracts	bloge-dsl, bloge-dsl-caffeine, bloge-lang, bloge-conformance	DSL parsing, AST, compiler, schema validation, imports, expressions, conformance parity
Extension platform	bloge-session-ext, bloge-state-ext, bloge-agent-ext	Provider-owned syntax, semantic compilers, nested operator factories, extension-specific lint
Durable operations	bloge-durable, bloge-durable-mybatis, bloge-durable-codec, bloge-event-journal, bloge-spring-web	Checkpoints, leases, recovery, event journal, audit journal, task inbox, archive, ops console
Ecosystem and tooling	bloge-spring, bloge-common-operators, bloge-metrics-otel, bloge-lsp, bloge-vscode, bloge-intellij, bloge-maven-plugin, bloge-lint, bloge-test	Framework integration, operator catalog, telemetry, editors, metadata, engine testing

bloge-verification crosses these layers rather than becoming a sixth runtime layer. It consumes Scenario, Policy, Fixture, DSL, core, durable, and customer Operator inputs to execute the real graph and produce a separate verification result.

Business Verification Path

The verification result has three independent projections: execution status, evidence trust, and claim capability. See BLOGE Verify before treating any result as a gate.

Execution Path

The normal runtime path is intentionally compact:

LIVE EXECUTION · APPROVED PATHIndependent reads run together, then the graph joins their outputs.

Watch the payload move left to right: two ready nodes run in parallel before pricing and credit approval.

Graph input

customerId=C-104 · productIds=[P-7,P-9]

Graph result

orderId=O-2048

RUNNINGLoad customercustomerId → customer

RUNNINGLoad inventoryproductIds → stock

WAITINGCalculate pricecustomer + stock → total

WAITINGCheck creditcustomer + total → approved

WAITINGCreate orderapproved order → orderId

NOT TAKENManual reviewfallback case → reviewId

approved = true otherwise

Loading interactive Graph…

Now running: Load customer + Load inventoryapproved = true

DSL and Java authoring converge on the same Graph model. The runtime does not create a second programming model for DSL users.

DSL Compilation Path

Extensions do not patch the core parser ad hoc. They register provider-owned syntax and compilers through the DSL extension SPI.

Durable Runtime Path

Durability adds persistence, recovery, routing, and operations without changing the basic graph authoring model.

Choosing the Right Model

Use this	When the workflow is
Plain graph	A DAG of business capabilities, API calls, decisions, and transforms
foreach / loop	Repeated work, polling, pagination, or batch processing
wait / await	Timer or external-signal suspension inside a graph
Session	Multi-round conversational or interaction workflows
State machine	Explicit named states and event-driven transitions
Agent	LLM reasoning loop with tools, memory, and exit conditions
Remote worker	One node must run outside the orchestrator process
Dynamic subgraph	A controlled runtime-generated graph should execute as a nested workflow

Reading Order

1. Start with What is BLOGE?.
2. Build a small graph in Getting Started.
3. Understand runtime semantics in Operator & Graph and Execution Model.
4. Learn the language in DSL Overview.
5. Add production concerns through Durable Flows, Event Journal & Ops Console, and Observability.
6. Add business-owned acceptance paths through BLOGE Verify.