An open-source framework for building application servers that separate decision-making from business logic.
Instead of binding HTTP endpoints directly to predefined handlers, Aleatoricism introduces an agent-driven execution model in which requests are interpreted dynamically and mapped to business processes represented as process graphs.
Aleatoricism is an open-source project that explores a different approach to server-side application architecture.
Traditional server applications are typically deterministic: each endpoint is explicitly mapped to a specific piece of business logic. Aleatoricism challenges this assumption by introducing an agent layer responsible for interpreting incoming requests and selecting the most appropriate business process at runtime.
Business logic is modeled as forests of process graphs, where each process consists of interconnected execution nodes called Waypoints. These graphs can be composed, extended, reused, and shared across different business capabilities.
The result is a highly adaptable architecture that allows applications to evolve without constantly redesigning their HTTP interface.
The name Aleatoricism originates from aleatoric music, a compositional technique in which certain elements of a musical work are intentionally left open to performer interpretation or chance.
Rather than defining every note and transition in advance, an aleatoric composition provides a set of structures, rules, and possibilities from which the final performance emerges.
This idea serves as the inspiration for the framework.
In Aleatoricism, the application does not rigidly bind a request to a single predefined execution path. Instead, an agent evaluates the request, interprets its intent, and selects an appropriate process from a collection of available process graphs.
Just as aleatoric music balances structure with freedom, Aleatoricism balances deterministic business logic with dynamic runtime decision-making.
-
📂
aleatoricism-chain
HTTP routing and instruction-driven execution entry point. -
📂
aleatoricism-flows
Typed flow runtime, waypoint definitions, and process execution engine. -
📂
aleatoricism-spring-boot-autoconfigure
Spring Boot auto-configuration and property wiring. -
📂
aleatoricism-spring-boot-starter
Starter dependencies for Spring Boot applications. -
📂
aleatoricism-spring-boot-sample-app
Reference implementation demonstrating framework capabilities.
Aleatoricism intentionally departs from several common assumptions found in modern backend systems:
- Requests are not statically bound to controller methods.
- Business capabilities are not modeled as endpoint hierarchies.
- REST maturity levels and rigid resource-oriented APIs are not the primary architectural concern.
- The HTTP layer acts as a transport mechanism rather than the source of business decisions.
The agent layer is responsible for determining how a request should be processed.
Agent behavior is configured through an aleatoricism.md file located on the application's classpath. This file contains instructions and operational guidance that help the agent understand:
- available business capabilities,
- execution constraints,
- domain-specific rules,
- request interpretation strategies.
When an HTTP request arrives, the request payload and metadata are passed to the agent layer. The agent analyzes the request together with the instructions defined in aleatoricism.md and decides which business process should be executed.
Business logic is represented as a collection of process graphs.
Each process (Flow) consists of interconnected Waypoints, which represent individual execution steps. Waypoints can be reused across multiple processes, enabling modular process composition and reducing duplication.
This approach provides:
- reusable business capabilities,
- clear separation of orchestration and execution,
- composable workflows,
- simplified process evolution over time.
Because process selection happens dynamically, new business capabilities can be introduced without modifying the HTTP layer.
Developers can:
- add new flows,
- modify existing flows,
- introduce new waypoints,
- change orchestration strategies,
while keeping the external API stable.
This makes the system particularly suitable for domains where business requirements evolve rapidly.
Representing business logic as graphs makes application behavior easier to understand and analyze.
Process structures can be visualized directly from source code definitions, providing:
- improved maintainability,
- easier onboarding,
- better architectural transparency,
- clearer domain modeling.
Aleatoricism promotes a higher-level interaction model between clients and servers.
Rather than invoking narrowly defined operations, clients express intent and provide instructions describing the desired outcome.
The agent layer interprets these instructions and determines which process graph should be executed.
In many scenarios, interacting with the API feels closer to communicating objectives than calling individual operations.
- An HTTP request is received.
- The request is forwarded to the agent layer.
- The agent evaluates the request and available instructions.
- A matching business process is selected.
- The process graph is executed asynchronously.
- Results are returned to the client.
If execution cannot be completed, the client receives a structured explanation describing why the request could not be processed.
The sample application demonstrates:
- tool definitions,
- flow construction,
- waypoint composition,
- dynamic process selection,
- agent-driven request handling.
For a complete walkthrough, see the sample application's documentation: 📖 Read the guide