Forem: Sergiy Yevtushenko

Java Backend Design Technology: A Process-First Methodology

Sergiy Yevtushenko — Mon, 13 Apr 2026 21:53:25 +0000

Java Backend Design Technology: A Process-First Methodology

From Requirements to Code in Eight Questions

Every backend system is a collection of processes, not a collection of entities.

This sounds obvious when stated plainly. Yet the dominant design methodology for twenty years has been entity-first: identify User, Order, Product. Define their attributes. Attach behavior. Build services that operate on shared objects. The result is a system where every feature is coupled to every other feature through shared data models — and where every new requirement triggers an architecture discussion.

A different approach is gaining traction. Independent practitioners across five languages — F#, Rust, Java, Scala, .NET — have independently converged on the same structural insight: start with behavior, derive data. Design around what the system does, not what it stores. Six of them are documented in The Quiet Consensus, but the pattern extends far beyond those six.

Structured programming eliminated goto debates by making control flow mechanical. This methodology does the same for design: it makes most architectural decisions mechanical, determined by the problem rather than by the developer's preferences.

This article presents Java Backend Design Technology (JBDT) — the design phase of Java Backend Coding Technology (JBCT). It's a concrete, repeatable process for going from requirements to code structure. No entity diagrams. No aggregate boundaries. No architecture review boards. Just eight questions and the types that emerge from the answers.

The Questions Framework

For any feature, ask these eight questions. The answers produce the code structure mechanically.

What triggers this process?
What data does it need? — this becomes the Request record
What does success look like? — this becomes the Response record
What can go wrong? — these become error types (sealed interface with enum for fixed messages, records for contextual errors)
What are the steps? — these become step interfaces
Which steps depend on each other? — dependencies become sequential chains; independent steps become parallel operations
Are there conditional paths? — these become branching logic
Is there collection processing? — this becomes iteration

That's the entire design process. No other questions need answering. Pattern selection, type placement, error strategy — all determined by these eight answers.

Let's see it work.

Applying the Framework: Place an Order

Requirements: a customer places an order with items, a shipping address, and a payment method. The system checks inventory, processes payment, creates the order, and sends confirmation.

Question 1 — What triggers this? A customer submits an order.

Question 2 — What data does it need? Customer ID, list of items with quantities, shipping address, payment method.

record Request(String customerId, List<OrderItem> items,
               String shippingAddress, String paymentMethod) {}
record OrderItem(String productId, int quantity) {}

Question 3 — What does success look like? An order confirmation with an ID and estimated delivery.

record Response(String orderId, LocalDate estimatedDelivery) {}

Question 4 — What can go wrong? Invalid inputs, insufficient inventory, payment declined.

sealed interface PlaceOrderError extends Cause {
    enum General implements PlaceOrderError {
        EMPTY_CART("Cart is empty"),
        INVALID_ADDRESS("Shipping address is invalid");
        // ...
    }
    record InsufficientInventory(String productId, int requested, int available)
            implements PlaceOrderError { /* ... */ }
    record PaymentDeclined(String reason)
            implements PlaceOrderError { /* ... */ }
}

Question 5 — What are the steps? Validate the request. Check inventory. Process payment. Create order. Send confirmation.

Question 6 — Which steps depend on each other? Validation must happen first. Inventory check and payment processing are independent of each other. Order creation depends on both succeeding. Confirmation depends on the order being created.

This directly produces the composition:

static PlaceOrder placeOrder(CheckInventory checkInventory,
                             ProcessPayment processPayment,
                             CreateOrder createOrder,
                             SendConfirmation sendConfirmation) {
    return request -> ValidRequest.validRequest(request)
                                  .async()
                                  .flatMap(valid -> reserveOrder(checkInventory, processPayment, valid))
                                  .flatMap(createOrder::apply)
                                  .flatMap(sendConfirmation::apply);
}

private static Promise<ReservedOrder> reserveOrder(CheckInventory checkInventory,
                                                   ProcessPayment processPayment,
                                                   ValidRequest valid) {
    return Promise.all(checkInventory.apply(valid),
                       processPayment.apply(valid))
                  .map(ReservedOrder::new);
}

Questions 7 and 8 — no conditional paths or collection processing in the main flow.

Notice what happened. We didn't draw a class diagram. We didn't debate which aggregate owns what. We didn't create a shared Order entity used by every feature. We asked eight questions, wrote down the answers, and the code structure emerged.

Notice also: ValidateCart, ProcessPayment, InsufficientInventory, PaymentDeclined — these are exactly the words a domain expert would use when describing this process. The shared vocabulary between developers and business emerged directly from the design process, without dedicated modeling sessions. This is DDD's ubiquitous language in practice — emerging naturally rather than being constructed.

A Second Example: Publish Article

To show this isn't specific to e-commerce, let's design a content publishing feature.

Requirements: an author submits an article. The system validates the content, checks for duplicates, generates a slug, and publishes to multiple platforms.

Walking through the questions quickly:

Trigger: Author submits article
Data needed: Title, body, tags, author ID, target platforms
Success: Published URLs for each platform
Failures: Invalid content, duplicate title, platform rejection
Steps: Validate → check duplicates → generate slug → publish to platforms
Dependencies: Validation and duplicate check are independent. Slug generation depends on both. Publishing to each platform is independent (parallel).
Conditional paths: If a platform rejects, continue with others (best-effort)
Collection processing: Publishing to multiple platforms

static PublishArticle publishArticle(ValidateContent validate,
                                     CheckDuplicates checkDups,
                                     GenerateSlug generateSlug,
                                     PlatformPublisher publisher) {
    return request -> validateArticle(validate, checkDups, request)
                          .flatMap(generateSlug::apply)
                          .flatMap(article -> publisher.publishAll(article, request.platforms()));
}

private static Promise<ValidArticle> validateArticle(ValidateContent validate,
                                                     CheckDuplicates checkDups,
                                                     Request request) {
    return Promise.all(validate.apply(request),
                       checkDups.apply(request))
                  .map(ValidArticle::new);
}

Different domain, same eight questions, same mechanical process. The structure is determined by the answers, not by preferences.

Why It Works: Processes as Knowledge Gathering

There's a deeper structure underneath the eight questions.

Every backend process is fundamentally an act of knowledge gathering. Each step acquires a piece of knowledge. The process ends — successfully or not — when enough knowledge has accumulated to formulate an answer.

In PlaceOrder:

Validation gathers knowledge: "the inputs are well-formed"
Inventory check gathers knowledge: "the items are available"
Payment processing gathers knowledge: "the funds are secured"
Order creation gathers knowledge: "the order is persisted"

A failure at any step is also knowledge. A declined payment tells the process "funds are not available" — and that's enough to formulate the answer "order cannot be placed." The process doesn't need to continue once it has enough knowledge to respond.

This reframes data modeling entirely. Instead of asking "what data exists in the system?" (which produces entity diagrams), you ask "what does this process need to know?" The first question leads to shared entities. The second leads to per-process types — exactly what the methodology produces.

Data Dependency Graphs

The knowledge-gathering view has a formal structure. Three operators describe how pieces of knowledge relate:

Sequential — need A before gathering B. "Validate first, then check inventory."
ALL(A, B) — need both, they're independent. "Check inventory AND process payment."
ANY(A, B) — either source suffices. "Get credit score from internal system OR external bureau."

Between operators, transformation functions convert one piece of knowledge into another — pure business logic.

A Detailed Example: Resolve Customer Credit

A lending system needs to make a credit decision. The process:

Attempt to get the customer's credit score from the internal scoring system
If internal scoring is unavailable, fall back to an external credit bureau
Independently, retrieve the customer's payment history
Combine credit score and payment history to calculate a risk assessment
Apply lending policy to produce the final decision

As a data dependency graph:

CreditDecision = ApplyPolicy(
                     Assess(
                         ALL(
                             ANY(InternalScore, ExternalBureau),
                             PaymentHistory
                         )
                     )
                 )

Reading from the inside out:

ANY(InternalScore, ExternalBureau) — gather credit score from whichever source responds successfully first, any response is equally correct.
ALL(..., PaymentHistory) — gather the credit score (from either source) AND the payment history independently, in parallel.
Assess(...) — transform both pieces of knowledge into a risk assessment. Pure function, no I/O.
ApplyPolicy(...) — transform the risk assessment into a lending decision. Pure function.

This maps directly to code:

static ResolveCredit resolveCredit(InternalScoring internal,
                                   ExternalBureau external,
                                   PaymentHistoryService history,
                                   RiskAssessor assessor,
                                   LendingPolicy policy) {
    return request -> gatherCreditData(internal, external, history, request)
                          .map(assessor::assess)
                          .map(policy::apply);
}

private static Promise<CreditData> gatherCreditData(InternalScoring internal,
                                                    ExternalBureau external,
                                                    PaymentHistoryService history,
                                                    Request request) {
    return Promise.all(obtainCreditScore(internal, external, request),
                       history.retrieve(request.customerId()))
                  .map(CreditData::new);
}

private static Promise<CreditScore> obtainCreditScore(InternalScoring internal,
                                                      ExternalBureau external,
                                                      Request request) {
    return internal.score(request)
                   .orElse(() -> external.score(request));
}

Three methods, one pattern each. resolveCredit is the Sequencer (gather → assess → decide). gatherCreditData is the Fork-Join — the ALL operator gathering independent pieces of knowledge in parallel. obtainCreditScore is the fallback — the ANY operator trying the internal source first, falling back to external. The sequential .map calls are transformations that convert gathered knowledge into the final answer.

The DDG notation captures more useful information than an entity-relationship diagram. An ER diagram tells you what data exists. A DDG tells you what a process needs to know, where it gets that knowledge, and what depends on what. The code writes itself from the graph.

When Requirements Change

The product owner says: "We need to check for fraud before processing payment."

In an entity-first design, this triggers questions: Does the Order entity need a fraud status? Where does the fraud check live in the service layer? Do we need a new aggregate?

In process-first design, the response is mechanical:

Add a new step interface: CheckFraud
Ask question 6: does fraud check depend on other steps? It needs the validated request — so it comes after validation.
Is it independent of other steps? It's independent of inventory check but payment should wait for it.
Insert it into the composition:

static PlaceOrder placeOrder(CheckInventory checkInventory,
                             ProcessPayment processPayment,
                             CreateOrder createOrder,
                             SendConfirmation sendConfirmation,
                             CheckFraud checkFraud) {
    return request -> ValidRequest.validRequest(request)
                                  .async()
                                  .flatMap(valid -> reserveOrder(checkInventory, processPayment, checkFraud, valid))
                                  .flatMap(createOrder::apply)
                                  .flatMap(sendConfirmation::apply);
}

private static Promise<ReservedOrder> reserveOrder(CheckInventory checkInventory,
                                                   ProcessPayment processPayment,
                                                   CheckFraud checkFraud,
                                                   ValidRequest valid) {
    return Promise.all(checkInventory.apply(valid),
                       verifyAndPay(checkFraud, processPayment, valid))
                  .map(ReservedOrder::new);
}

private static Promise<PaymentResult> verifyAndPay(CheckFraud checkFraud,
                                                   ProcessPayment processPayment,
                                                   ValidRequest valid) {
    return checkFraud.apply(valid)
                     .flatMap(_ -> processPayment.apply(valid));
}

One new step interface. One change to the composition. No restructuring. No entity changes. No architecture discussion.

This is what mechanical design evolution looks like: patterns are used from the start, so evolution is adding and recomposing — never restructuring.

When Processes Meet Persistence

"But what about the database? Don't you end up with entities anyway?"

Yes — and that's fine. The difference is how they get there.

Multiple use cases converge on the same database tables. PlaceOrder writes order rows. CancelOrder updates the status column. TrackOrder reads shipping info. GenerateInvoice reads billing fields. The orders table is the union of what these processes need.

But this entity emerged from process convergence. It wasn't designed upfront. Every column has a known consumer — the process that needed it. No speculative fields "just in case." When a new process needs something new, you add it, and you know exactly why.

The key insight: entities are discovered, not invented. They're the natural intersection of processes that share persistence — a composition of views, not a universal model.

This isn't always the case. In event-sourced systems, entities may never materialize into a single flat record. Each process folds the event stream into exactly the shape it needs — different state reconstructions for different contexts (Rico Fritzsche explores this in depth in Beyond Aggregates). Whether your entities live as database rows, event folds, or CQRS projections, the principle holds: they're composed from process needs, not designed ahead of time.

Practical Consequences

Design meetings get shorter. When the methodology is mechanical, there's less to debate. "What are the use cases? What are the answers to the eight questions?" produces a design in minutes, not hours. Architects are freed to focus on genuinely hard problems — infrastructure, scaling, cross-system integration — instead of mediating aggregate boundary debates.

The six JBCT structural patterns map directly to BPMN constructs — code written using these patterns is structurally equivalent to a business process diagram. For the full pattern-BPMN mapping, see the JBCT series.

Testing becomes a side effect of design. Every step interface is a test seam. Stub it, test the composition. The design produces testable code by construction — no special effort required.

AI-assisted development benefits directly. Given the eight questions answered, an AI assistant produces structurally correct code because the design space is fully constrained. There's essentially one valid structure for a given set of answers.

Try It

Pick a feature from your current project. Ask the eight questions. Write down the Request, Response, error types, and step interfaces before writing any implementation code.

Notice how the structure emerges from the answers — not from architectural decisions or entity modeling. Notice how the types you name are the words your domain expert would use. Notice how you didn't need to debate anything.

That's JBDT in practice.

Going Deeper

Java Backend Design Technology is the design phase of Java Backend Coding Technology — a complete methodology covering design, implementation patterns, testing strategy, and tooling. JBDT has been validated against a 326,000-line distributed runtime (Aether) and formalized into a comprehensive learning series.

If you've independently arrived at similar conclusions from your own domain, language, or tradition — I'd like to hear about it. The convergence is the interesting part.

Further reading:

The Quiet Consensus — the convergent evolution toward process-first design
Hidden Anatomy of Backend Applications: Data Dependencies — the DDG formalism
Scott Wlaschin, Domain Modeling Made Functional — workflows with typed boundaries in F#
Rico Fritzsche, Beyond Aggregates: Lean, Functional Event Sourcing — aggregateless design with event sourcing

The Quiet Consensus

Sergiy Yevtushenko — Sun, 12 Apr 2026 10:27:18 +0000

Something is happening in software design that nobody organized.

Practitioners from different languages, different domains, different traditions are arriving at the same conclusion — independently, without coordination, often without knowing about each other's work.

The conclusion: business processes, not data entities, are the natural unit of software decomposition.

This isn't a manifesto. There was no conference keynote. No working group. Just a growing body of work from people solving real problems who kept ending up in the same place.

The Standard Starting Point

For two decades, the dominant approach to backend design has been data-first. Identify the entities — User, Order, Product. Define their attributes and relationships. Attach behavior. Build services that operate on shared objects.

This approach, formalized in Domain-Driven Design's tactical patterns, produces shared entity models that serve multiple contexts. The coupling is structural: change a shared entity, and every consumer is affected. Add a field to Order, and every service that touches orders must accommodate it — even services that don't care about the new field.

The pattern works. It has built enormous systems. But practitioners working at scale report the same friction points:

Entities grow into God objects because every feature needs something different from the same concept
Mapping layers accumulate (DTO to entity to DTO) because the entity doesn't fit any single feature perfectly
Architecture discussions become debates about aggregate boundaries — who owns what, how big should the aggregate be, where does this behavior belong
The "where does domain logic live?" question never settles — rich domain model, anemic domain model, transaction scripts, domain services. Each team picks differently, each project mixes approaches, and the answer changes depending on who you ask. The debate persists because entity-first design doesn't have a natural home for behavior that spans multiple entities
Coupling increases with every new feature because features share entities instead of owning their own types

These aren't implementation failures. They're structural consequences of starting with data.

Convergent Evolution

In biology, convergent evolution describes species that develop the same trait independently — wings in birds, bats, and insects. Different lineages, different mechanisms, same solution to the same problem.

Something similar is happening in software design. Practitioners from different ecosystems are converging on the same structural adaptation.

Scott Wlaschin (F#) models domains as workflows with typed inputs and outputs, composing small functions into complete use cases. His phrase "make illegal states unrepresentable" captures the type-driven approach. His book Domain Modeling Made Functional demonstrates how types replace defensive coding and how workflows replace entity models.

Rico Fritzsche (Rust/TypeScript) models domains as contextual decisions, not shared entities. Each feature slice owns its own state reconstruction. In his framing, entities are not fixed structures — they are "flexible, context-dependent manifestations". A "Seat" is a row and number in booking, a reservation status in availability, a price category in pricing. Three different types, three different processes, no shared entity.

Roman Weis (Java) proposes focusing "100% on behavior — the commands" instead of finding the perfect aggregate root. Business logic belongs in scoped, task-based commands.

Sandro Mancuso (Java/Craftsmanship) starts from external usage. His Interaction-Driven Design lets the domain model emerge from actual needs — use cases first, internal structure second. The domain isn't modeled in advance; it's discovered through implementation.

Jimmy Bogard (.NET) organizes code by features, not layers. His Vertical Slice Architecture minimizes coupling between slices and maximizes coupling within a slice. Each feature is self-contained. Shared abstractions are extracted only when proven necessary.

Debasish Ghosh (Scala) expresses behavior as pure function compositions rather than object methods, with immutable types and explicit side effects. His book Functional and Reactive Domain Modeling shows how algebraic types and composition replace the entity-service-repository pattern.

Six practitioners. Five languages. Different continents, different communities, different audiences. None of them cites the others as primary inspiration. They arrived at the same place because they were solving the same problem.

What They Share

Strip away the language-specific details and the individual vocabulary, and the shared structure becomes clear:

Processes over entities. The primary decomposition unit is a business operation with a trigger, inputs, outputs, and failure modes — not a data entity with attributes and relationships.

Per-context types. Data structures are shaped by the process that uses them. A "User" in registration has different fields than a "User" in authentication or billing. Each process owns its own types.

Functional composition. Small, pure, testable operations composed into larger workflows. The composition itself is the design — not a layer on top of a design.

No shared domain model. Domain knowledge is distributed across processes, not centralized in entity classes. Shared types exist only for validated domain concepts (email addresses, monetary amounts) that genuinely mean the same thing across contexts.

What's Driving the Convergence

Independent convergence implies shared environmental pressure. Several forces are pushing practitioners toward process-first design simultaneously:

Distributed systems demand it. Microservices and serverless architectures naturally align with process-based decomposition. Each service IS a process. Trying to maintain shared entity models across service boundaries creates the exact coupling that microservices were supposed to eliminate.

Scale reveals entity-model friction. Small systems don't feel the pain of shared entities. At 5 services, a shared User entity is manageable. At 50, it's a coordination bottleneck. At 500, it's impossible. Teams that grow past a certain size independently discover that process boundaries work better than entity boundaries.

Functional programming went mainstream. Rust brought algebraic types, pattern matching, Result<T, E>, and immutability by default to systems programming — proving these aren't academic preferences but engineering necessities. Java added records, sealed interfaces, and pattern matching. C# added records and discriminated unions. TypeScript refined literal types and discriminated unions. The languages now support typed composition natively, without framework overhead. What was theoretical in 2010 is practical in 2025.

AI-assisted development rewards deterministic patterns. When the design process is mechanical — ask these questions, the structure follows — AI can participate reliably. Process-first design constrains the design space in ways that make AI-generated code structurally correct more often. This wasn't a design goal for any of the practitioners cited. It's an emergent benefit.

From Observation to Practice

Observing convergence is interesting. Formalizing it is useful.

If processes are the natural decomposition unit, the design activity becomes identifying processes and their boundaries. A process has:

Typed input — what triggers it and what data it needs
Typed output — what success looks like
Typed failures — what can go wrong
Steps — sub-processes with their own typed boundaries

These aren't abstract categories. They're concrete questions you can ask about any feature requirement:

What triggers this process?
What data does it need?
What does success look like?
What can go wrong?
What are the steps?
Which steps depend on each other?
Are there conditional paths?
Is there collection processing?

The answers determine the code structure. Not guidelines — deterministic mapping. Independent steps become parallel operations. Sequential dependencies become chains. Conditional paths become branches. The developer doesn't invent the structure; they discover it from the answers.

Consider an order placement process. The questions yield:

Input: customer, items, address, payment method
Output: order confirmation with estimated delivery
Failures: invalid items, insufficient inventory, payment declined
Steps: validate, check inventory, process payment, create order, send confirmation
Dependencies: inventory check and payment are independent; order creation depends on both

The dependency analysis tells you the composition pattern: validate first (sequential), then inventory and payment in parallel (fork-join), then create order (sequential), then confirm (sequential). The code writes itself:

validate → (check inventory ∥ process payment) → create order → confirm

No architecture meeting required. No debate about aggregate boundaries. No class diagram. The process structure IS the architecture, derived mechanically from the requirements.

Context-Specific Types

One consequence of process-first design deserves emphasis: types belong to processes, not to the domain.

In entity-first design, you model "Seat" once and every feature uses that model. In process-first design, each process models exactly what it needs:

Booking — a location to select (row, number)
Reservation — a time-limited hold (id, reserved until)
Pricing — a cost input (id, category, base price)

Three different types, three different processes. No shared entity, no conflict, no coupling. Change the pricing model — only the pricing process changes. Add reservation expiry logic — only the reservation process is affected.

Shared types emerge only when genuinely needed: an email address means the same thing in registration and login, so it becomes a shared value object. But the sharing is discovered from evidence, not designed from speculation.

What This Changes

When processes own their types and composition follows from dependency analysis:

The language footprint shrinks. Most language features serve entity-model infrastructure — inheritance hierarchies, mutable state, reflection. Process-first design uses a small subset: records for data, sealed interfaces for alternatives, lambdas for composition. The rest becomes unnecessary.

Code reads like business documentation. A process method reads as a sequence of named business operations. New team members learn the domain by reading the code, not the framework.

Design evolves mechanically. New step? Add a step interface and insert it in the chain. Steps become independent? Change sequential to parallel. Process grows too large? Extract a sub-process. No "refactoring to patterns" — the patterns are used from the start.

Business stakeholders can validate structure. When code maps directly to process descriptions, a business analyst can look at the composition and verify it matches the business process. The gap between specification and implementation narrows to zero.

What Replaces Entity Modeling

A natural objection: if we don't start with entities, what happens to data modeling?

It doesn't disappear. It transforms.

Every backend process is fundamentally an act of knowledge gathering. Check inventory — now you know availability. Process payment — now you know if funds cleared. Each step acquires a piece of knowledge. The process ends — successfully or not — when enough knowledge has accumulated to formulate an answer.

This reframes data modeling entirely. Instead of asking "what data exists in the system?" (entity diagram), you ask "what does this process need to know?" (dependency graph). The data model becomes a data dependency graph scoped to each process:

PlaceOrder = Transform(ALL(InventoryStatus, PaymentResult))

ALL means "I need both pieces of knowledge — they're independent." Sequential chaining means "I need this knowledge before I can gather the next." ANY means "I can get this knowledge from multiple sources — the first success is enough."

These operators map directly to composition patterns in code. ALL is a fork-join. Sequential chaining is a flatMap. ANY is a fallback. The code structure mirrors the knowledge dependency structure — not because of a design framework, but because gathering knowledge to produce answers is what the code actually does.

The consequence: data types are scoped to the knowledge a process needs, not to what exists in the database. A "Seat" in the booking process carries row and number. A "Seat" in the pricing process carries category and base price. They're different knowledge, gathered for different answers. No shared entity needed.

Entity modeling asks: "What is a Seat?" — and produces one answer that fits no process perfectly.
Process modeling asks: "What does this process need to know about seats?" — and produces exactly the right answer for each process.

The Relationship to DDD

This isn't a rejection of Domain-Driven Design. DDD's most enduring contributions — bounded contexts, ubiquitous language, the insistence that software should model the domain — remain essential.

What's being reconsidered is the starting point. DDD's tactical patterns start with entities and aggregates, then attach behavior. Process-first design starts with behavior, then derives the types. The strategic patterns (bounded contexts, context mapping) are fully compatible — in fact, process boundaries often align with context boundaries more naturally than entity boundaries do.

The ubiquitous language still matters. But in process-first design, it emerges from use case identification and type definition rather than from separate modeling sessions. When a domain expert says "we need to check inventory before processing payment," that sentence maps directly to step interfaces and their ordering. The code reads like the conversation that produced it.

The Quiet Part

Nobody organized this convergence. There's no foundation, no standard, no certification program. Just practitioners solving problems and publishing what they found.

That's what makes it credible. When one person proposes a new methodology, it's an opinion. When six people from different ecosystems independently arrive at the same methodology, it's a signal. The environmental pressures — distributed systems, team scaling, AI-assisted development, functional language features — are producing the same structural adaptation across the industry.

The consensus is quiet because it doesn't need to be loud. It's not replacing anything overnight. It's just that every year, more teams try process-first design, find that it works, and don't go back.

The convergence described here is formalized in JBCT (Java Backend Coding Technology) — a methodology with patterns, tooling, and implementation guidance. The approach has been validated against a 326,000-line distributed runtime built entirely with process-first design.

Further reading: Scott Wlaschin, Domain Modeling Made Functional. Debasish Ghosh, Functional and Reactive Domain Modeling. Rico Fritzsche, How to Model Domain Logic Without Shared Entities. Roman Weis, Alternative Approach to DDD. Sandro Mancuso, Interaction-Driven Design. Jimmy Bogard, Vertical Slice Architecture.

We Should Write Java Code Differently: Less Language, More Business

Sergiy Yevtushenko — Mon, 06 Apr 2026 12:21:55 +0000

How much of your code is actually about your business?

Open any Java service method. Count the lines. How many describe what the business does? And how many are null checks, exception handling, try-catch blocks, type conversions, logging boilerplate, and framework annotations?

In most codebases, the answer is uncomfortable. Technical ceremony dominates. Business logic hides between the scaffolding. A new developer reads the code and understands how it works — but not what it does or why.

This isn't a skill problem. It's a language problem. Java gives us powerful tools, but doesn't guide us toward using them in ways that preserve business meaning.

The Ratio

Consider a typical service method that processes an order:

Validate the input (null checks, field validation, exception wrapping)
Check inventory (try-catch around HTTP call, retry logic, timeout handling, response parsing)
Calculate pricing (more HTTP, more try-catch, more parsing)
Create the order (database call, transaction management, exception handling)
Return the result (response mapping, error conversion)

Five business steps. But the code for each step is 80% technical handling and 20% business intent. The ratio is inverted — the scaffolding is louder than the signal.

Shrinking the Technical Part

What if the technical surface was standardized to the point where it almost disappeared?

Return types encode behavior. A method returning Result<Order> tells you it can fail — without looking at the implementation. Option<User> tells you the value might be absent. Promise<Response> tells you it's asynchronous. The type signature is the high-level documentation. No Javadoc needed to explain "this method might throw" — the return type already said it.

Composition operators have fixed semantics. flatMap means "if the previous step succeeded, do this next." all() means "these operations are independent — they have no ordering dependency and can execute in parallel." These aren't just API methods. They're business-level statements about relationships between operations. When you read all(checkInventory, calculatePricing), you know these two things don't depend on each other. That's domain knowledge encoded in structure.

Error types are exhaustive. A sealed interface listing every failure mode means a business analyst can read the error hierarchy and understand what can go wrong — without reading implementation code. The errors aren't strings or exception classes buried in catch blocks. They're first-class types that enumerate the business failure domain.

Patterns are structural, not creative. A Sequencer means "do these things in this order." Fork-Join means "do these things in parallel, combine results." A Leaf is a single operation with no sub-steps. The developer doesn't invent control flow — they select from a small set of patterns that map directly to how business processes work.

What Remains

When the technical part shrinks, what's left is business logic — and it becomes the dominant signal in the code.

The order processing method becomes:

static OrderService orderService(InventoryService inventory,
                                 PricingService pricing) {
    return request -> inventory.check(request.items())
                               .flatMap(pricing::calculate)
                               .map(OrderResult::placed);
}

Three lines. Each line is a business step. The technical ceremony — HTTP calls, serialization, retry, error handling — exists, but it's handled by the runtime and the type system, not by the developer in this method.

Read it aloud: "Check inventory. Then calculate pricing. Then create the order." That's not a description of the code. That is the code.

Preserving Knowledge

This matters beyond aesthetics.

When technical ceremony dominates, a new team member reads the code and learns the framework. They understand how things are wired — which annotations trigger what, which configuration goes where, which exception handler catches what. This knowledge is framework-specific and doesn't transfer.

When business logic dominates, the same team member reads the code and learns the domain. They understand what the system does — which operations depend on each other, what can fail, what the valid states are. This knowledge survives framework migrations, team changes, and technology shifts.

The original developer's intent — the business reasoning behind the code — is preserved in the structure itself. Not in comments that drift from reality. Not in documentation that nobody updates. In the code.

The Language Shrinks

Something unexpected happens when you measure language features against business value: most of them become unnecessary.

Java is a large language. Inheritance hierarchies, checked exceptions, mutable state, reflection, annotation processing, type erasure workarounds, synchronized blocks, volatile fields — these are powerful tools. But when the goal is expressing business logic clearly, how many of them do you actually use?

The answer is surprisingly few. Records for data. Sealed interfaces for type-safe alternatives. Lambdas and method references for composition. Pattern matching for dispatch. That's most of it.

The rest — the features that generate conference talks and blog posts about clever techniques — serves the technical ceremony, not the business logic. Class inheritance exists to share implementation, not to model business concepts. Checked exceptions exist to force handling, but Result types handle errors more expressively. Mutable state exists for performance optimization, but immutable records are sufficient for business data.

This isn't a limitation. It's a feature. When the useful subset of the language is small:

The learning curve compresses. A new developer doesn't need to master all of Java — just the subset that carries business meaning.
Code becomes predictable. When there are three ways to express something, developers argue about style. When there's one way, they focus on the domain.
The "which feature should I use here?" decision disappears. The answer is always the same small set of constructs.

The implication is broader than one language. If Java's business-relevant subset is this small, adding more language features doesn't increase business expressiveness — it increases the technical surface that competes for attention with the business logic. Expressiveness comes from domain modeling, not from language syntax.

The Boundary Is Clear

The technical part of the code should be:

Small — a handful of types and patterns, not a framework vocabulary
Standardized — the same patterns everywhere, no per-developer style
Semantically meaningful — each construct maps to a business concept

The business part should be:

Dominant — more visible than the technical scaffolding
Readable — a sequence of named operations, not a tangle of callbacks
Exhaustive — every failure mode visible, every dependency declared

When these two conditions are met, code becomes what it should have been from the start: an executable specification of what the business does.

This is the sixth article in the "We Should Write Java Code Differently" series. Previous: The DI Confusion.

We Should Write Java Code Differently: The DI Confusion

Sergiy Yevtushenko — Sun, 05 Apr 2026 08:44:15 +0000

Inversion of Control is one of the most impactful ideas in software engineering. It fundamentally changed how we structure applications — making code testable, modular, and composable. Dependency Injection, its most common implementation, became the backbone of virtually every modern Java framework.

But somewhere along the way, DI acquired a second job. And that second job is quietly causing problems.

Assembly vs. Provisioning

DI was designed to solve one problem: assembling an application from its components. Controller depends on service, service depends on repository — wire them together, done. The components are internal. The wiring is deterministic. Configuration is minimal or zero.

But most frameworks also use DI for something fundamentally different: resource provisioning. Database connections, HTTP clients, message brokers, caches, stream consumers — external resources that the application needs access to.

These two concerns look similar on the surface. Both involve "giving a component something it needs." But they behave completely differently:

Assembly — internal components, part of the application. Minimal or no configuration. Created once at startup. Dependencies are your code. No security concerns. Failures are deterministic, caught at compile time.

Provisioning — external resources, part of the infrastructure. Environment-dependent, complex configuration. Managed lifecycle: pools, reconnects, health checks. Dependencies are drivers, SDKs, adapters. Requires credentials, certificates, rotation. Failures are environmental, discovered at runtime.

By fusing these into one mechanism, frameworks created a set of consequences that the industry accepted as normal.

The Consequences

Your application bundles infrastructure.
Database drivers, connection pools, HTTP client libraries, messaging SDKs — they all live in your application's dependency tree. A typical backend service is 60% infrastructure dependencies, 40% business logic. Your pom.xml is a manifest of things that aren't your problem but became your problem.

Environment leaks into the artifact.
Dev, staging, production — each needs different resource configurations. Connection strings, pool sizes, timeouts, retry policies. The application artifact is identical, but the resource configuration isn't. Managing these variations across services and environments becomes a combinatorial challenge that grows with every new service and every new resource.

Credentials live where they shouldn't.
Because the application provisions its own resources, it needs secrets. Database passwords, API keys, certificates. Every service, every environment. Now multiply by the number of services. Secret management becomes an infrastructure project of its own — not because the problem is inherently hard, but because every application was given responsibility for its own credentials.

Infrastructure changes become application changes.
Upgrading a connection pool library? Touch every service. Switching to a different database driver? Rebuild and redeploy every service that uses a database. A security CVE in an adapter library requires coordinated redeployment across the fleet. Infrastructure concerns create application-level change propagation.

Testing fights the wrong battle.
A significant portion of test setup is dedicated to mocking or configuring infrastructure that isn't the application's concern. Integration tests need containers for databases, message brokers, caches. The test is verifying business logic, but the setup is provisioning resources.

Separating the Concerns

What if assembly and provisioning were handled by different mechanisms, at different layers?

Assembly — connecting internal components — can be fully automated. If a use case depends on a repository, and both are part of the application, the wiring is deterministic. No configuration file needed. Annotation processing can resolve it at compile time.

Provisioning — providing access to external resources — belongs to the runtime environment, not the application. The application declares what it needs: "I need a SQL connection," "I need a notification channel," "I need a stream." The runtime decides how to provide it based on the deployment environment.

This separation has immediate consequences:

pom.xml contains only business dependencies. Infrastructure dependencies belong to the runtime.
Same artifact deploys to any environment without configuration changes.
Credentials never touch the application. The runtime handles authentication with the infrastructure.
A security patch in a database driver is a runtime update — zero application rebuilds, zero redeployments.
Tests focus on business logic. No mock infrastructure, no test containers for resources the application doesn't own.

The application becomes what it should have been from the start: pure business logic with declared resource requirements. Everything between the business logic and production is the runtime's responsibility.

The Boundary

This isn't an argument against DI. Inversion of Control remains one of the best ideas our field has produced. The argument is against overloading DI with a concern it wasn't designed for — and paying the price in dependency sprawl, configuration complexity, and operational coupling.

The boundary is clear: if it's your code, assemble it. If it's infrastructure, declare it and let the environment provide it.

This is the fifth article in the "We Should Write Java Code Differently" series. Previous: Frictionless Prod.

We Should Write Java Code Differently: Frictionless Prod

Sergiy Yevtushenko — Thu, 02 Apr 2026 21:51:07 +0000

We Should Write Java Code Differently: Frictionless Prod

It's not a secret that modern production deployment is extremely complex. Following "best practices" and deploying in Kubernetes "for scalability" makes things even more complex. But how complex exactly? Let's look at the numbers.

The Setup

A mid-sized e-commerce platform. Nothing exotic -- catalog, cart, checkout, orders, payments, shipping, inventory, pricing, promotions, notifications. Standard bounded contexts, standard domain decomposition.

In a microservices architecture, this translates to roughly 30 services. Not because someone wanted 30 -- because the domain naturally decomposes into ~10 core services, ~10 supporting services (integrations, async processing, admin), and ~10 platform services (gateway, auth, search, analytics, event processing).

30 is not a large number. It is a realistic baseline for a system that does what mid-sized e-commerce systems do.

What 30 Services Actually Cost

Each service needs to be built, deployed, configured, monitored, and kept alive -- independently. On managed Kubernetes, the standard deployment substrate for this scale, here is what the numbers look like.

Production environment:

12-18 shared platform components (ingress controller, cert manager, external DNS, metrics stack, logging pipeline, tracing collector, secrets integration, policy controller, autoscaler, GitOps controller, backup controller, image registry integration)
220-280 Kubernetes workload objects (deployments, services, config maps, secrets, service accounts, network policies, autoscalers, pod disruption budgets, ingress rules, worker/consumer deployments)
260-340 configuration sets (image tags, rollout strategies, replica counts, CPU/memory limits, probes, environment variables, feature flags, secret references, IAM permissions, network exposure rules, alerting configs -- per service)

Staging environment:

Topologically similar to production. You save on capacity, not on configuration complexity. 190-250 workload objects. 220-300 configuration sets.

Testing environment:

80-160 workload objects in a shared cluster with ephemeral namespaces. 100-180 configuration sets.

Across all three environments: 500-700 managed runtime objects and 580-820 configuration surfaces.

This is before counting databases, message brokers, CDN, object storage, and external SaaS integrations. The application itself -- the business logic that actually generates revenue -- is a small fraction of this surface.

The Team That Manages This

This infrastructure does not manage itself. For a 30-service system on managed Kubernetes:

Minimum viable: 3-5 platform/DevOps engineers
Typical realistic: 5-8 engineers
Comfortable/mature: 8-12 engineers

This is platform and SRE combined -- not including the feature development teams that write the actual business logic. These engineers manage pipelines, rollout policies, cluster security, network configuration, secrets, observability, capacity planning, incident response, and the endless stream of version upgrades across 30 independent deployment units.

The dominant complexity is not code. It is coordination: version coexistence (new service talking to old service), schema evolution (new code on old database), deployment ordering (which service goes first), and failure propagation (one bad deploy cascading through dependent services).

A mid-sized organization pays for 5-8 engineers whose entire job is keeping the deployment machinery running. Not building features. Not serving customers. Managing the gap between code and production.

Where This Complexity Comes From

This is not accidental. The complexity has three structural sources, each one a consequence of architectural decisions made so long ago that they feel like laws of nature. They are not.

The Monolith Turned Inside Out

A microservices system is a monolith turned inside out. Every internal interaction -- a method call, a shared data structure, a module boundary -- transforms into infrastructure configuration. What was a function call within a single process becomes a network call that needs discovery, routing, serialization, timeout handling, retry logic, and circuit breaking. What was an internal module boundary becomes a deployment boundary with its own pipeline, versioning, and rollout policy.

The problem is not microservices as a concept. The problem is that there are no predefined patterns or limits on how services interact. The infrastructure must be infinitely flexible to accommodate every possible communication topology. Infinite flexibility means every single interaction path must be configured -- sometimes multiple times in different places. A call from the order service to the inventory service touches ingress rules, network policies, service discovery, load balancing, timeout configuration, and retry policy. Each one configured separately. Each one a potential source of misconfiguration.

A 30-service system with 50-100 service-to-service interactions does not have 30 configuration problems. It has a combinatorial configuration problem that grows with the interaction graph, not with the service count.

This creates an inherent contradiction. The ideal service boundary is determined by the business domain -- by cohesion, coupling, and team ownership. But the configuration and operational cost of each additional service is so high that it becomes a technical factor in the decomposition decision. Teams merge services that should be separate to avoid operational overhead, or keep services together that should be split because nobody wants to set up another pipeline. The result is almost inevitably a suboptimal split -- service boundaries driven by infrastructure cost rather than domain structure.

And there is a human cost too. Every service boundary is a communication boundary. Two services owned by two teams means coordination meetings, API contracts, versioning negotiations, shared testing environments, deployment ordering discussions. Conway's Law works in reverse here -- the architecture forces organizational communication patterns that would not exist if the split were different. The more services, the more cross-team coordination. The more coordination, the slower the delivery. The very thing microservices promised to fix -- team independence -- is undermined by the infrastructure overhead of maintaining the boundaries between them.

The Substrate-Application Disconnect

Kubernetes runs containers. It starts a binary, monitors a health endpoint, restarts it if it fails. That is the extent of the relationship. Once the binary is running, it is on its own.

This creates a two-way blindness. The application cannot trust the environment -- it must assume that any network call can fail, any service can be unavailable, any response can be delayed. So the application implements its own retries, its own circuit breakers, its own service discovery, its own health reporting. All of this requires configuration.

The blindness goes the other direction too. The substrate knows nothing about the application. It does not know which services talk to each other, what constitutes a meaningful health check for this specific business logic, which services must be deployed before others, or whether a particular service's "healthy" status actually means it can process requests. The cluster is fault-tolerant at the container level, but the application gets no benefit from that -- it must build its own fault tolerance on top.

The result: the application carries infrastructure concerns that the runtime should handle, and the runtime cannot provide services that would require understanding the application. Both sides are doing extra work because neither side can see the other.

There is a particularly painful consequence of this disconnect: the application and its infrastructure share a lifecycle. Every microservice bundles its own web server, serialization library, HTTP client, connection pool, metrics agent, and retry framework. When any of these components needs a security patch -- a CVE in Netty, a vulnerability in Jackson, an update in the connection pool -- the business logic must be rebuilt, retested, repackaged, and redeployed. All 30 services. Zero changes to business logic. Pure infrastructure maintenance.

This is not a deployment -- it is a tax. A Netty CVE means 30 rebuilds, 30 pipeline runs, 30 test suites, 30 rollouts. Each one risks introducing regressions in business logic that nobody touched. The operational burden scales with the service count, and the trigger has nothing to do with the business. The application and the runtime are monolithically coupled inside every single service, even as the services themselves are distributed.

The Tool Multiplication Effect

Because the substrate and application are disconnected, the gap between them must be filled. Each gap spawns a tool:

Routing and mTLS between services? Service mesh.
TLS certificate lifecycle? Certificate manager.
Configuration across environments? Config service.
Database schema evolution? Migration tool.
Connection management? Connection pooler.
Metrics and tracing? Observability agents.
Deployment orchestration? GitOps controller.
Secret management? Vault or cloud secrets integration.

Each tool has its own configuration language, its own upgrade cycle, its own failure modes, and its own operational surface. Each tool solves a real problem -- but the problem only exists because the substrate and application cannot communicate.

A 30-service system on managed Kubernetes typically depends on 9-12 distinct operational tools beyond Kubernetes itself. Each one was added to solve a legitimate gap. Together, they are the gap. The complexity is not in any single tool -- it is in the interaction between all of them. A certificate renewal that breaks a service mesh sidecar that causes a health check failure that triggers a cascading restart -- this class of incident exists only because the tools operate independently, each with partial knowledge, none with the full picture.

What If the Gap Didn't Exist?

The three sources of complexity share a root cause: the application and the runtime are strangers. The runtime starts a binary and watches a health endpoint. The binary assumes a hostile environment and brings its own infrastructure. The gap between them fills with tools. The tools fill with configuration. The configuration fills with inconsistencies. The inconsistencies fill incident postmortems.

What changes if the runtime understands the application?

Unification: From Multiplication to Addition

In a Kubernetes-based system, configuration complexity is multiplicative. Each service multiplied by each environment multiplied by each configuration surface produces the 580-820 number we saw earlier. Every new service adds a full column of config. Every new environment multiplies the entire matrix.

This multiplication exists because nothing is shared. Each service configures its own database connection, its own TLS, its own retries, its own health checks, its own metrics, its own log format. Even when two services use the same database, they each carry their own connection configuration -- independently managed, independently misconfigured.

A unified runtime changes the math. When the runtime handles TLS, there is one TLS configuration -- not 30. When the runtime handles database connections, there is one database configuration per database -- not one per service. When the runtime handles metrics, there is one observability configuration -- not 30 agents with 30 scrape configs.

The dependency structure changes from a product of factors to a sum of components. 30 slices sharing 3 databases, 1 TLS configuration, and 1 observability setup produce roughly 35 configuration surfaces -- not 340. The complexity scales with the number of distinct resources, not with the number of services that use them.

Integration: The Cluster Becomes Service-Aware

When the application is embedded into the runtime -- not just started by it -- the two-way blindness disappears.

The runtime knows what slices exist, what resources they need, which slices communicate with each other, and what "healthy" means for each one. It knows because the application declared it: this slice needs a database, that slice publishes to a stream, this slice depends on that one. The declarations are not configuration files scattered across repositories. They are part of the application itself -- compiled in, type-checked, deployed as a single artifact.

From the application's perspective, the environment becomes trustworthy. Retries, circuit breaking, load balancing, service discovery -- these are not application concerns anymore. The runtime handles them because the runtime knows the topology. When slice A calls slice B, the runtime knows where B lives, which instances are healthy, how to route the request, and what to do if it fails. The application code is a method call. Everything between the call and the response is the runtime's responsibility.

This is not a framework providing libraries. It is a managed runtime providing services -- the way an operating system provides networking and storage to applications. The application does not implement TCP. It calls an API. The same principle, applied one level up.

The Communication Fabric

The deepest integration point is inter-slice communication. In a microservices system, service-to-service calls cross process boundaries, network boundaries, and trust boundaries. Each crossing adds latency, failure modes, and configuration.

When slices run inside the runtime, the communication fabric is built in. A call from one slice to another is a typed method invocation. The runtime resolves the target, handles serialization, routes the request -- potentially to the same node (microsecond latency, zero network overhead) or to a remote node (transparent, with automatic retry and failover). The slice developer writes inventory.check(items) and gets back a Promise<Availability>. The infrastructure between the call and the response is invisible.

This is not RPC dressed up as a method call. The type system guarantees that the caller and callee agree on the contract at compile time. There are no surprise serialization failures, no version mismatches discovered in production, no "the other service changed its API and nobody told us." The contract is a Java interface. The compiler enforces it.

The same fabric carries pub/sub, streaming, and scheduled task execution. All inter-slice communication -- synchronous, asynchronous, event-driven -- flows through the same runtime-managed infrastructure. One communication model, one set of guarantees, one thing to understand.

Resource Provisioning: Declare, Don't Configure

In the traditional model, the application includes its dependencies and configures them. A service that needs a database brings a connection pool library, configures the URL, credentials, pool size, timeouts, and retry behavior. A service that needs messaging brings a client library, configures the broker address, topics, serialization, and consumer groups. Each dependency is another library, another config surface, another thing to upgrade.

In a unified runtime, the application declares what it needs. A slice annotated with @Sql gets a database connection -- provisioned, pooled, health-checked, and monitored by the runtime. A slice that declares a stream gets a stream -- partitioned, replicated, persistent. The slice does not know or care how the database connection is managed. It declares intent. The runtime delivers.

This is why 30 slices do not produce 30× configuration. The resources are shared by design. Three slices using the same database share one connection pool. Ten slices publishing to the same stream share one stream configuration. The configuration count tracks resources, not consumers.

Different Tradeoffs: Splitup Without Penalty

When the operational cost of each additional slice is zero -- no pipeline, no deployment descriptor, no config set, no monitoring surface -- the decomposition decision changes fundamentally.

In a microservices system, splitting a service in two is an infrastructure project: new repository, new pipeline, new deployment config, new monitoring, new network policies, new on-call surface. This cost discourages splitting, leading to oversized services that bundle unrelated logic because nobody wants to pay the operational tax of separation.

When slices are the unit, splitting is a code decision. Extract an interface, annotate it with @Slice, implement the business logic. The runtime handles deployment, routing, scaling, and monitoring automatically. There is no operational penalty for having 50 slices instead of 10. The only consideration is the domain: does this logic belong together, or should it be independent?

This aligns perfectly with vertical slicing. Each slice is a complete vertical: an interface (the contract), an implementation (the logic), and resource declarations (what it needs). No horizontal layers spread across packages. No shared mutable state between slices. Each slice is independently deployable, independently scalable, and independently understandable.

The scaling is linear -- in development, not just in production. Adding a new slice to the system does not require understanding the deployment topology, the network configuration, or the CI/CD pipeline. It requires understanding the business domain. Write the interface. Implement the logic. Deploy.

JBCT: Structure That Carries Across Boundaries

This is where the code methodology meets the runtime. JBCT's six structural patterns -- Sequencer, Fork-Join, Condition, Iteration, Aspects, Leaf -- are not just coding rules. They are the structural language of business processes. A Sequencer is a sequence of dependent steps. A Fork-Join is parallel independent operations. A Condition is a routing decision. These map directly to BPMN constructs -- the same notation business analysts use to describe processes.

When every slice follows the same six patterns, several things happen at once:

The code becomes the specification. A business analyst who understands the process can review the code structure and verify that it matches the intended workflow. Not because the code is simple -- because the structure is familiar. The patterns are the same shapes they draw on whiteboards.

AI-assisted development becomes predictable. The six patterns constrain the generation space. An AI that produces JBCT code generates variations of known structures, not arbitrary architectures. The mechanical rules mean less manual correction, less review overhead, less accumulated drift.

Developer onboarding compresses. A developer who learns the six patterns can read and contribute to any slice in the system. There is no per-service learning curve, no "this team does it differently." The patterns are the same everywhere.

The entire stack speaks the same language. The business process is described in BPMN. The code implements it in JBCT patterns that mirror the BPMN structure. The runtime deploys and operates it without configuration. From business requirement to production, the structure is consistent. No translation layers. No impedance mismatches. No "we need a meeting to explain what the code does."

Independent Lifecycles

Remember the Netty CVE problem -- 30 rebuilds, 30 pipelines, 30 rollouts, zero business logic changes?

When the application and the runtime are separate layers, their lifecycles decouple completely. The runtime handles web serving, TLS, connection pooling, serialization, metrics, retry logic. The application handles business logic. When Netty needs a patch, the runtime updates -- once, across all nodes, without touching a single slice. When business logic changes, the slice deploys -- without rebuilding the runtime.

Update the runtime: roll out new nodes, slices continue serving. Update a slice: deploy a new version, the runtime handles routing. Update the database driver: runtime concern, not application concern. Update Java itself: runtime update, slices are unaffected.

Two independent update cadences. Two independent test surfaces. Two independent rollout schedules. The security patch that used to trigger 30 rebuilds is now a single runtime update that applications never see.

Aether: What This Looks Like in Practice

Everything described above is not a thought experiment. It is a working system called Aether.

Here is what the 30-slice e-commerce application looks like in practice.

The Application

A slice is a Java interface:

@Slice
public interface OrderService {
    Promise<OrderResult> placeOrder(PlaceOrderRequest request);

    static OrderService orderService(InventoryService inventory,
                                     PricingService pricing) {
        return request -> inventory.check(request.items())
                                   .flatMap(pricing::calculate)
                                   .map(OrderResult::placed);
    }
}

That is the entire service. The interface is the contract. The factory method parameters are the dependencies. The implementation is the business logic. There is no framework, no annotations for routing or serialization or retry, no configuration file. The runtime handles all of it.

The Deployment

The blueprint is a TOML file that describes the desired state:

id = "org.example:commerce:1.0.0"

[[slices]]
artifact = "org.example:order-service:1.0.0"
instances = 3

[[slices]]
artifact = "org.example:inventory-service:1.0.0"
instances = 5

# ... remaining slices

The Maven plugin packages the blueprint automatically -- along with database schema migration scripts and application configuration -- into a single deployable JAR. The entire build-to-production workflow:

# Build and install to local Maven repository
mvn install

# Push artifacts from local Maven repo to production cluster
aether artifact push org.example:commerce:1.0.0

# Deploy
aether deploy org.example:commerce:1.0.0

Three commands. The runtime resolves artifacts, runs schema migrations, distributes slice instances across nodes, registers routes, and starts serving traffic. No Docker images, no Helm charts, no deployment descriptors, no pipeline configuration.

The Cluster

[deployment]
type = "aws"
region = "eu-west-1"

[deployment.instances]
core = "m5.large"

[cluster]
name = "production"
core.count = 5

[cluster.auto_heal]
enabled = true

aether cluster bootstrap --config cluster.toml

Five nodes. Auto-healing. TLS derived from a shared secret -- no external certificate authority, no cert-manager. Service discovery via consensus -- no Consul, no etcd. Metrics and tracing built in -- no Prometheus scrape configs, no observability agents. QUIC transport with mandatory TLS 1.3 between all nodes.

Scaling

aether cluster scale --core 7

Two additional nodes join the cluster automatically -- same binary, same config. Worker nodes can scale independently via gossip protocol, adding capacity without touching the consensus layer. A 5-node cluster grows to 50 nodes without architecture changes. The runtime includes a reactive scaling controller that adjusts capacity based on CPU, latency, queue depth, and error rate.

Local Development

# Build your slices
mvn install

# Start a 5-node cluster on your laptop with your application deployed
aether-forge --blueprint org.example:commerce:1.0.0

A full cluster on your laptop. Real consensus, real routing, real failure scenarios. Web dashboard with live metrics. Kill a node, watch recovery. Deploy a new slice version, watch traffic shift. The same runtime that runs in production runs on your machine -- not a simulation, not a mock, the actual system. When it works in Forge, it works in production.

The Numbers

For the same 30-slice e-commerce application:

Configuration sets (production): 260-340 on Kubernetes. ~15 on Aether.
Configuration sets (all environments): 580-820 on Kubernetes. ~18 on Aether.
Platform components: 12-18 per environment on Kubernetes. 1 binary on Aether.
Deployment: 30 independent pipelines on Kubernetes. 3 commands on Aether.
Runtime security patch: 30 rebuilds on Kubernetes. 1 rolling update on Aether.
Operational team: 5-8 dedicated engineers on Kubernetes. 1 person on Aether.

One person does not mean zero operational work. Monitoring the cluster, watching for bottlenecks, checking alerts, reviewing scaling behavior, planning capacity -- that is enough work for one person. But it is one person, not eight. And that person spends time on operational judgment, not on managing the configuration machinery that connects 12 tools to 30 services across 3 environments.

Running Java should be as easy as writing it.

With Aether, it is.

pragmaticalabs.io

Previously: Introduction to Pragmatic Functional Java (2019) | We Should Write Java Code Differently (2021) | We Should Write Java Code Differently: Let's Get Practical (2026)

We Should Write Java Code Differently: Let's Get Practical

Sergiy Yevtushenko — Sun, 22 Mar 2026 21:54:48 +0000

We Should Write Java Code Differently: Let's Get Practical

A few years ago I wrote about why we should write Java code differently. The core argument: most of what slows us down is not the amount of code — it's the amount of context we lose while writing it. Nullable variables, business exceptions, framework magic — each one eats information that should have been explicit.

That article diagnosed the problem. This one delivers the tools.

Three types — Option, Result, and Promise — cover virtually every return value in a Java backend. They compose with the same map/flatMap vocabulary you already know from Streams. Once you internalize them, the code you write becomes shorter, safer, and — this is the part that surprised me — significantly easier to read months later.

Option: A Value That Might Not Be There

If you've used Streams, you already understand the core mechanic — transform the value inside, chain transformations, extract at the end. Option applies the same thinking to absent values.

findUser(id).flatMap(user -> findAddress(user.addressId())
            .map(address -> new Profile(user, address)));

If any step returns Option.none(), the whole chain short-circuits. No null checks, no early returns, no branching. The absent-value case propagates automatically.

Where does Option come from? At adapter boundaries — wrapping nullable external APIs:

Option<String> name = Option.option(request.getParameter("name"));

Inside business logic, Option is the container for everything genuinely optional. The type makes the absence visible in the signature, not hidden in a javadoc comment.

A few things that make Option practical:

// Pattern matching with sealed types
switch (option) {
    case Option.Some(var value) -> process(value);
    case Option.None() -> handleAbsence();
}

// Convert to Result when absence is an error
option.toResult(NOT_FOUND);

// Combine multiple Options — all must be present
Option.all(firstName, lastName, email)
      .map(Contact::new);

The conversion methods matter. Option is not an island — it flows into Result and Promise when the context demands it.

Result: Errors Without Exceptions

This is where things change fundamentally.

Consider typical Java error handling:

public User registerUser(RegistrationRequest request) {
    if (request.email() == null || request.email().isBlank()) {
        throw new ValidationException("Email is required");
    }
    if (userRepository.existsByEmail(request.email())) {
        throw new DuplicateEmailException(request.email());
    }
    try {
        String hash = passwordHasher.hash(request.password());
        return userRepository.save(new User(request.email(), hash));
    } catch (HashingException e) {
        throw new RegistrationFailedException("Password hashing failed", e);
    }
}

The method signature says it returns User. It lies. It can throw three different exceptions, and the compiler won't tell you about any of them. The caller has no idea what to catch. The next developer reading this code has to trace every path to understand what can go wrong.

With Result:

public Result<User> registerUser(RegistrationRequest request) {
    return Email.email(request.email())
                .flatMap(this::ensureUnique)
                .flatMap(email -> hashAndCreateUser(email, request.password()))
                .flatMap(userRepository::save);
}

private Result<Email> ensureUnique(Email email) {
    return userRepository.existsByEmail(email)
           ? EMAIL_ALREADY_EXISTS.result()
           : Result.success(email);
}

private Result<User> hashAndCreateUser(Email email, String password) {
    return passwordHasher.hash(password)
                         .map(hash -> new User(email, hash));
}

The return type tells the truth — this operation can fail. Every failure path is visible in the chain. No exceptions thrown, no exceptions caught. The compiler enforces that the caller handles the Result.

How Errors Work

Errors are values, not exceptions. They implement the Cause interface:

public sealed interface RegistrationError extends Cause {
    enum General implements RegistrationError {
        EMAIL_ALREADY_EXISTS("Email already registered"),
        TOKEN_GENERATION_FAILED("Token generation failed");

        private final String message;

        General(String message) { 
            this.message = message; 
        }
        @Override 
        public String message() { 
            return message; 
        }
    }
}

Fixed messages become enum constants. Dynamic messages become records. All are sealed — the compiler knows every possible failure. Pattern matching works:

switch (result) {
    case Result.Success(var user) -> sendWelcome(user);
    case Result.Failure(var cause) -> logAndRespond(cause);
}

Composition

The real power shows in composition. Result.all() collects independent validations:

record ValidRegistration(Email email, Password password, PhoneNumber phoneNumber) {
    public static Result<ValidRegistration> validRegistration(Registration raw) {
        return Result.all(Email.email(raw.email()),
                          Password.password(raw.password()), 
                          PhoneNumber.phoneNumber(raw.phone()))
                     .map(ValidRegistration::new);
    }    
}

All three validations run. All failures are collected — not just the first one. The map only executes if all three succeed. One line replaces the usual cascade of if-checks-and-early-returns.

Interfacing with Legacy Code

The world throws exceptions. lift() catches them at the boundary:

Result.lift(DatabaseError::new, () -> legacyDao.findById(id));

Exception goes in, Result comes out. The boundary is explicit. Business logic stays clean.

Promise: Result, But Async

Promise is Result where the answer hasn't arrived yet. Same map, same flatMap, same mental model — just non-blocking:

public Promise<EnrichedUser> loadEnriched(UserId userId) {
    return findUser(id).flatMap(this::loadUserWithOrders);
}

private Promise<EnrichedUser> loadUserWithOrders(User user) {
    return findOrders(user.id()).map(orders -> new EnrichedUser(user, orders));
}

If findUser fails, the chain short-circuits — just like Result. If loadUserWithOrders fails, same thing. Errors are Cause values, same as in Result. The only difference: the chain executes asynchronously.

Parallel Operations

Independent operations run in parallel with Promise.all():

record Dashboard(Profile profile, List<Order> orders, List<Notification> notifications) {}

public Promise<Dashboard> loadUserDashboard(UserId userId) {
    return Promise.all(fetchProfile(userId), 
                       fetchOrders(userId), 
                       fetchNotifications(userId))
                  .map(Dashboard::new);
}

Three async calls, all independent, all in parallel. Result combined when all complete. If any fails, the whole thing fails — with a meaningful Cause.

For "first success wins" semantics:

Promise<Value> fetch(Key key) {
    return Promise.any(fetchFromPrimaryCache(key), 
                       fetchFromReplicaCache(key), 
                       fetchFromDatabase(key));
}

Side Effects

Promise distinguishes between dependent and independent actions:

findUser(id).flatMap(this::validateAccess)       // dependent — runs in sequence
            .flatMap(this::loadProfile)          // dependent — runs after validation
            .onSuccess(metrics::recordAccess)    // independent — runs async, doesn't block chain
            .onFailure(logger::warn);            // independent — runs async on failure

Dependent actions (map, flatMap) execute in order and can fail the chain. Independent actions (onSuccess, onFailure) run asynchronously and never affect the chain's outcome. This distinction eliminates an entire class of bugs where logging or metrics accidentally break the business flow.
There are also dependent side effects, for the cases when ordering matters:

findUser(id).flatMap(this::validateAccess)       // dependent — runs in sequence
            .flatMap(this::loadProfile)          // dependent — runs after validation
            .withSuccess(metrics::recordAccess)  // dependent — runs on success, in order like map/flatMap
            .withFailure(logger::warn);          // dependent — runs on failure, in order like map/flatMap

Timeouts and Recovery

fetchFromRemoteService(request).timeout(timeSpan(5).seconds())
                               .recover(cause -> cachedFallback(request));

If the remote call doesn't resolve in 5 seconds, it fails. recover converts the failure back to success using a fallback. Clean, composable, no try-catch.

The Three Types Together

The real picture emerges when all three work together. Consider a realistic operation — processing an incoming order:

public Promise<OrderConfirmation> processOrder(RawOrderRequest raw) {
    return ValidOrder.validOrder(raw)              // Result<ValidOrder> — sync validation
                     .async()                      // → Promise<ValidOrder>
                     .flatMap(this::enrichOrder)
                     .flatMap(orderRepository::save)
                     .onSuccess(eventBus::publishOrderCreated);
}

private Promise<EnrichedOrder> enrichOrder(ValidOrder order) {
    return Promise.all(inventoryService.check(order.items()),
                       pricingService.calculate(order.items()),
                       customerService.find(order.customerId()))
                  .map((availability, pricing, customer) ->
                           new EnrichedOrder(order, availability, pricing, customer));
}

What happens here:

Validation — ValidOrder.validOrder() returns Result<ValidOrder>. Parse, don't validate. If the input is malformed, a Cause explains why. No exception.
Sync to async — .async() lifts the Result into a Promise. From here, everything is non-blocking.
Parallel fetch — enrichOrder calls three independent services simultaneously. All must succeed.
Enrichment — results combined into EnrichedOrder. The map only runs if all three calls succeed.
Persistence — saved to repository. Returns Promise<OrderConfirmation>.
Side effect — event published asynchronously. Does not affect the response.

No try-catch. No null checks. No if (result == null) return error. Every failure path handled by the type system. Every step clearly visible.

The Decision Tree

Choosing the right type is mechanical:

Can this operation fail?
├── NO: Can the value be absent?
│   ├── NO → return T
│   └── YES → return Option<T>
└── YES: Is it async/IO?
    ├── NO → return Result<T>
    └── YES → return Promise<T>

Four return kinds. No judgment calls. The decision tree covers every method in a Java backend.

One allowed combination: Result<Option<T>> — when the value is genuinely optional but validation can still fail. Example: an optional referral code that, if provided, must match a specific format.

One forbidden combination: Promise<Result<T>> — double error channel. Promise already carries failure semantics. Nesting Result inside it means two places to check for errors.

What Changes In Practice

After a few weeks of writing code this way, something shifts. You stop thinking about error handling as a separate concern. It's not something you add after the happy path — it's embedded in the types. The compiler catches what used to be runtime surprises.

Code reviews get faster. When every method returns one of four types, the shape of the code becomes predictable. You don't need to trace exception paths through five layers. The return type tells you everything.

Testing simplifies. Each step in a chain is independently testable. Failures are values you can assert on — not exceptions you have to catch. Mock a dependency to return EMAIL_ALREADY_EXISTS.result() and verify the chain handles it correctly.

And the types compose. A Result from validation flows into a Promise for async processing, which fans out into parallel Promise.all(), which combines back into a single response. Each piece connects to the next with flatMap. The vocabulary is always the same.

Naming That Scales

Types solve the "what can happen" question. But there's another source of friction — naming. Every code review has that moment: "should this be fetchUser or loadUser or getUser?" The debate is real, and it wastes time because there's no shared vocabulary.

Zone-based naming eliminates this. The idea, adapted from Derrick Brandt's systematic approach to clean code: verbs belong to abstraction levels. Use the wrong verb at the wrong level, and the name signals something misleading.

Zone 2 — orchestration steps. These coordinate other operations. They don't touch databases or parse bytes. They organize.

Verb	When to use
`validate`	Checking rules and constraints
`process`	Transforming or interpreting data
`load`	Retrieving data for use
`save`	Persisting changes
`resolve`	Determining ambiguous cases
`build`	Assembling complex objects
`notify`	Informing others of events

Zone 3 — leaf operations. These do the actual work. One responsibility, specific and concrete.

Verb	When to use
`fetch`	Pull from external source
`parse`	Break down structured input
`format`	Build structured output
`calculate`	Perform computation
`hash`	Cryptographic transformation
`send`	Transmit over network
`extract`	Pull piece from larger structure

The pattern:

// Zone 2 — step interface, orchestration verb
interface LoadUserProfile {
    Promise<UserProfile> apply(UserId id);
}

// Zone 3 — leaf, implementation verb
private Promise<User> fetchFromDatabase(UserId id) { ... }
private Option<CachedUser> extractFromCache(UserId id) { ... }

If you see fetch on a step interface — something's wrong. If you see process on a leaf — same thing. The verb tells you the abstraction level before you read the parameters.

This matters for the same reason the four return types matter: it makes code predictable. A developer scanning an unfamiliar codebase can tell from the name alone whether they're looking at orchestration or implementation. No need to open the method body.

Getting Started

If your codebase currently uses exceptions for business errors and null for absent values, you don't need to rewrite everything. Start at the boundaries:

Pick one new feature. Write it with Result returns instead of exceptions.
Wrap legacy calls with Result.lift() and Option.option() at the adapter boundary.
Let the types propagate. Once one method returns Result, its callers naturally follow.

The types are available in Pragmatica Core — a focused library with no transitive dependencies.

This is the foundation that JBCT (Java Backend Coding Technology) builds on. Six structural patterns, four return kinds, mechanical rules that make code deterministic and AI-friendly. But the types come first. Everything else follows from getting the types right.

Previously: Introduction to Pragmatic Functional Java (2019) | We Should Write Java Code Differently (2021)

No Framework, No Pain: Writing Aether Slices

Sergiy Yevtushenko — Thu, 19 Feb 2026 10:08:28 +0000

No Framework, No Pain: Writing Aether Slices

The previous article introduced Aether's philosophy: return Java to managed runtimes, let the runtime handle infrastructure, and let developers handle business logic. This article shows what that looks like in practice -- what you actually write, how dependencies work, how testing works, and how existing code migrates in.

Your Microservice Is Just an Interface

Here's an entire deployable service:

@Slice
public interface OrderService {
    Promise<OrderResult> placeOrder(PlaceOrderRequest request);

    static OrderService orderService(InventoryService inventory,
                                     PricingEngine pricing) {
        return request -> inventory.check(request.items())
                                   .flatMap(pricing::calculate)
                                   .map(OrderResult::placed);
    }
}

That's not a simplified example. That's the actual thing. The annotation processor sees @Slice, reads the factory method signature and generates the wiring code, the proxy for remote calls, and the deployment metadata. You write one interface. You get a service that scales, fails over, and routes transparently across a distributed cluster.

No @Autowired. No application.yml. No @Configuration class. No @Bean method. No component scan. No service locator. No dependency injection container at all.

The factory method is dependency injection. Its parameters are the declared dependencies. The compiler verifies them. The annotation processor wires them. Nothing to configure, nothing to forget, nothing to debug at 2 AM.

Notice what the factory returns: a lambda. No implementation class. The interface has one method, so the factory returns a lambda that implements it directly. Business logic as a function. For slices with multiple methods, a private record captures the dependencies and implements the interface -- still no separate Impl class, no file to maintain, and no indirection to trace.

Two Rules, Zero Boilerplate

Every slice follows two rules:

1. The factory method declares dependencies. What the slice needs from the outside world appears in one place: the factory method signature.

static OrderService orderService(InventoryService inventory,
                                 PricingEngine pricing) {
    return request -> inventory.check(request.items())
                               .flatMap(pricing::calculate)
                               .map(OrderResult::placed);
}

Read the factory; know the dependencies. No configuration file can contradict it. No runtime surprise can introduce a dependency the compiler hasn't seen.

2. Promise return types. Every method returns Promise<T>. This isn't a stylistic choice -- it's what makes transparent distribution possible. Whether the call is in-process or cross-network, the caller sees the same type.

That's it. Two rules. Everything else follows from them.

The Magic Is in the Factory Method

The annotation processor looks at each factory parameter and classifies it automatically:

What the processor sees	What it does
`@PrimaryDb SqlConnector db`	Resource -- provisions from config
`InventoryService inventory`	External slice -- generates a network proxy
`OrderValidator validator`	Local interface with factory -- calls the factory directly

You don't configure this. You don't annotate dependencies with @Inject or @Qualifier (except for infrastructure resources). You just list what you need, and the processor figures out how to provide it.

Consider what this means. A parameter annotated with @ResourceQualifier is infrastructure -- a database connection, an HTTP client, or a message queue. The processor provisions it from configuration:

@ResourceQualifier(type = SqlConnector.class, config = "database.primary")
public @interface PrimaryDb {}

@Slice
public interface OrderRepository {
    Promise<OrderResult> findOrder(FindOrderRequest request);

    static OrderRepository orderRepository(@PrimaryDb SqlConnector db) {
        return request -> db.query(request.orderId())
                            .map(OrderResult::fromRow);
    }
}

A parameter that's a @Slice interface from another package is a remote dependency. The processor generates a proxy record that delegates to the runtime's invocation fabric. Your code calls inventory.check(request) as a method call. The proxy handles serialization, routing, retry, and failover.

A parameter that's a plain interface with a static factory method is local. The processor calls the factory directly. No proxy, no network, no overhead.

All three categories coexist in one factory:

static LoanService loanService(@PrimaryDb SqlConnector db,
                               CreditBureau creditBureau,
                               RiskCalculator riskCalculator) {
    return request -> riskCalculator.assess(request)
                                    .flatMap(risk -> creditBureau.check(request.applicant()))
                                    .flatMap(credit -> persistDecision(db, request, credit));
}

Database from config. Credit bureau via network proxy. Risk calculator instantiated locally. One line declares it all. The processor handles the rest.

Errors Without Exceptions

Frameworks train you to throw exceptions. Spring converts them to HTTP status codes. Jackson serializes error responses. Exception handlers map types to messages. It works until someone throws an unexpected exception, and the generic 500 response tells the caller nothing.

Slices use sealed Cause hierarchies:

public sealed interface OrderCause extends Cause {
    OrderCause EMPTY_ORDER = new EmptyOrder("Order must have items");
    OrderCause INSUFFICIENT_STOCK = new InsufficientStock("Insufficient stock");

    static OrderCause insufficientStock(StockStatus stock) {
        return new InsufficientStock("Insufficient stock: " + stock);
    }

    record EmptyOrder(String message) implements OrderCause {}
    record InsufficientStock(String message) implements OrderCause {}
}

Every failure mode is a type. The compiler knows all of them. Pattern matching handles them exhaustively. No surprise NullPointerException masquerading as a business error. No catch (Exception e) swallowing context.

When something fails, you return a failed promise using fluent style:

return inventory.checkStock(stockRequest)
                .flatMap(this::verifyAvailability);

private Promise<StockStatus> verifyAvailability(StockStatus stock) {
    return stock.sufficient()
        ? completeOrder(stock)
        : OrderCause.insufficientStock(stock).promise();
}

The runtime propagates the Cause across the network. The caller gets a typed failure, not a string message. The error handling contract is part of the API, not an afterthought in a @ControllerAdvice.

Testing: It's Just Java

No test containers to spin up. No mock server to configure. No @SpringBootTest annotation that loads half the universe. No mocking frameworks either -- dependencies are interfaces, so you pass lambdas that return exactly what you need:

class OrderServiceTest {
    @Test
    void placeOrder_succeeds_whenInventoryAvailable() {
        InventoryService inventory = request -> Promise.success(new StockResult("RES-123", true));
        PricingEngine pricing = request -> Promise.success(new PriceResult("ORD-456", 99.99));

        var service = OrderService.orderService(inventory, pricing);

        service.placeOrder(request)
               .await()
               .onFailure(Assertions::fail)
               .onSuccess(result -> assertEquals("ORD-456", result.orderId()));
    }

    @Test
    void placeOrder_fails_whenInventoryUnavailable() {
        InventoryService inventory = request -> OrderCause.INSUFFICIENT_STOCK.promise();
        PricingEngine pricing = request -> Promise.success(new PriceResult("ORD-456", 99.99));

        var service = OrderService.orderService(inventory, pricing);

        service.placeOrder(request)
               .await()
               .onSuccess(Assertions::fail);
    }
}

Dependencies are interfaces. Pass lambdas that return success; pass lambdas that return failure. The factory method wires them in. No reflection, no classpath scanning, no context initialization. No Mockito, no when(...).thenReturn(...), no verify(...).

Test startup is instant because there's nothing to start. No container. No framework. No bean resolution. Just objects calling objects.

Slices at Any Granularity

A single Maven module can contain as many slices as make sense:

commerce/
  src/main/java/org/example/
    order/
      OrderService.java       # @Slice
    payment/
      PaymentService.java     # @Slice
    shipping/
      ShippingService.java    # @Slice

Each @Slice generates its own factory, its own API artifact, its own deployment metadata. The Maven plugin packages them separately. They deploy and scale independently. But they develop together -- shared domain types, shared build, and one repository.

A slice can be as small as a single method. There's no operational overhead for small slices -- no container to configure, no load balancer to provision, and no monitoring to set up per service. This enables granular scaling that would be operationally insane with traditional microservices: one slice serving 50 instances during peak load while another idles at minimum. With Aether, it's the default.

What's Actually Happening

Let's trace what the annotation processor generates for a simple slice with one external dependency:

@Slice
public interface OrderService {
    Promise<OrderResult> placeOrder(PlaceOrderRequest request);

    static OrderService orderService(InventoryService inventory) {
        return request -> inventory.check(request.items())
                                   .map(OrderResult::fromAvailability);
    }
}

The processor sees InventoryService is from a different package and has @Slice annotation -- external dependency. It generates:

A proxy record that implements InventoryService and delegates every method call to the runtime's SliceInvokerFacade. Your code calls inventory.check(request). The proxy serializes the request, routes it to a node hosting InventoryService, deserializes the response, and returns it as a Promise.
A factory class that accepts an Aspect and the SliceInvokerFacade, creates the proxy, and wires everything together.
Deployment metadata in META-INF/slice/ -- the slice name, its methods, its dependencies. The runtime reads this to build the dependency graph and determine deployment order.

All generated. All verified at compile time. All invisible to your business logic.

Your Existing Code Is Already Halfway There

You don't need to start from scratch. Any existing Java code becomes a slice with one line:

// Your existing Spring service
@Service
public class OrderService {
    @Autowired private InventoryRepository inventory;
    @Autowired private PricingService pricing;

    @Transactional
    public OrderResult processOrder(OrderRequest request) {
        var availability = inventory.checkAvailability(request.getItems());
        if (!availability.isAvailable()) {
            return OrderResult.outOfStock(availability.getMissingItems());
        }
        var quote = pricing.calculateQuote(request.getItems(), request.getCustomerId());
        // ... payment, order creation, notification ...
        return OrderResult.success(order);
    }
}

Wrap it:

@Slice
public interface OrderProcessor {
    Promise<OrderResult> processOrder(OrderRequest request);

    static OrderProcessor orderProcessor() {
        var legacyService = createLegacyService();
        return request -> Promise.lift(() -> legacyService.processOrder(request));
    }
}

Promise.lift() wraps the synchronous call, catches any exception, and returns a proper Promise with a typed failure instead of a stack trace.
Your legacy code runs unchanged inside. The slice deploys to the Aether runtime (initially as a one-process cluster called Ember) alongside your existing application -- same JVM, no new risk. Move to a full Aether cluster when ready. That's a configuration change, not a code change.

The Peeling Pattern

The wrapped slice works, but it's a black box. The peeling pattern opens it up incrementally -- one layer at a time, working code at every step.

Peel the outer structure. Replace the opaque lift() with a Sequencer where each step is still wrapped:

return Promise.lift(() -> legacyCheckInventory(request))
              .flatMap(inv -> Promise.lift(() -> legacyCalculatePricing(inv)))
              .flatMap(quote -> Promise.lift(() -> legacyProcessPayment(quote)))
              .flatMap(payment -> Promise.lift(() -> legacyCreateOrder(payment)));

Now the pipeline is visible. You can see the steps, test them individually, and reason about the flow.

Peel one step deeper. Take the hottest lift() and expand it:

private Promise<Availability> checkInventory(OrderRequest request) {
    return Promise.all(Promise.lift(() -> legacyCheckWarehouse(request)),
                       Promise.lift(() -> legacyCheckSupplier(request)))
                  .map(this::combineAvailability);
}

The outer call is now clean JBCT. The inner calls are still wrapped. Tests pass at every step. Stop anywhere -- mixed JBCT and legacy code works fine. The remaining lift() calls mark exactly where legacy code lives. When they're all gone, you have a clean slice. But there's no deadline. Each peeling step delivers value on its own.

The full migration walkthrough covers the complete path -- from initial wrapping through fault tolerance to clean JBCT code.

The Shift

Traditional microservice development is a negotiation with frameworks. You learn their abstractions, their lifecycle hooks, their configuration DSLs, their annotation model, their error-handling conventions, and their testing utilities. The framework becomes the center of gravity. Your business logic orbits around it.

Slices invert this. Business logic is the center. The interface defines the contract. The factory method declares dependencies. The implementation is a lambda. Everything else -- serialization, routing, scaling, failover, and configuration -- is the runtime's problem.

You don't learn a framework. You write Java interfaces and implement them. Two rules. The rest is just your domain.

No framework. No pain.

Pragmatica Aether -- distributed Java runtime
GitHub Repository -- source code
Slice Development Guide -- full reference

Pragmatica Aether: Let Java Be Java

Sergiy Yevtushenko — Fri, 13 Feb 2026 14:38:14 +0000

The Aberration

We build Java applications like Go or Rust programs. Fat JARs. Docker images. Kubernetes deployments. Everyone does it, so it looks normal.

It contradicts Java's design DNA.

Java has always been a language for managed environments. Applets ran inside browsers. Servlets ran inside application servers. EJBs ran inside containers like JBoss and WebLogic. OSGi bundles ran inside runtime containers like Eclipse Equinox. In every generation, the pattern was the same: a managed runtime hosts the application. The application handles business logic. The runtime handles infrastructure.

The fat-jar era threw that away. We stopped letting Java be Java. We started bundling web servers, serialization frameworks, service discovery clients, configuration management, health checks, metrics libraries, and logging frameworks into every application. Then we wrapped the result in a Docker container and deployed it to an orchestration platform that reimplements — poorly — the infrastructure management that Java runtimes used to provide natively.

This article introduces Pragmatica Aether: a distributed runtime that returns Java to its natural habitat. Application handles business logic. Runtime handles infrastructure. This isn't radical — it's returning to what Java was designed for.

The Problem: Infrastructure Wearing a Business Logic Mask

Think of what a typical Java microservice carries. A web server (Tomcat, Netty, Undertow). A serialization framework (Jackson, Gson). A dependency injection container (Spring, Guice). A service discovery client (Eureka, Consul). Health check endpoints. Configuration management (Spring Cloud Config, Consul KV). A metrics library (Micrometer, Dropwizard). A logging framework (Logback, Log4j2). Retry logic (Resilience4j). Circuit breakers. HTTP client configuration. The application is wearing a heavy winter coat of infrastructure, armed to the teeth to survive in a hostile environment.

Now consider the coupling this creates.

Update Java version — rebuild and test every service. Change your message broker from RabbitMQ to Kafka — modify, rebuild, and redeploy every application that touches messaging. Add a new observability tool — update dependencies in every microservice. Switch cloud providers — rewrite configuration, SDK calls, and deployment manifests across the entire fleet. Each change ripples through dozens or hundreds of services because infrastructure is entangled with business logic at the dependency level.

This is the coupling trap. Your application's pom.xml doesn't distinguish between business dependencies and infrastructure dependencies. They compile together, deploy together, and break together. A security patch in Netty requires a new build of every service that embeds a web server — which is all of them.

Framework lock-in makes this worse. It isn't a vendor problem — it's an architecture problem. Spring's dependency injection fights with Kubernetes service mesh for control over service routing and circuit breaking. The framework's configuration system overlaps with Consul KV and Kubernetes ConfigMaps. Your cloud SDK's retry logic conflicts with Resilience4j. Every layer claims authority over the same cross-cutting concerns, and the conflicts surface as subtle bugs in production — not during development.

This is an architecture problem. Architecture problems have architectural solutions.

Aether: The Core Idea

What you write: an interface annotated with @Slice, plus business logic implementation.

@Slice
public interface OrderService {
    Promise<OrderResult> placeOrder(PlaceOrderRequest request);

    static OrderService orderService(InventoryService inventory, PricingEngine pricing) {
        return request -> inventory.check(request.items())
                                   .flatMap(available -> pricing.calculate(available))
                                   .map(priced -> OrderResult.placed(priced));
    }
}

What you don't write: everything else.

No HTTP clients — inter-slice calls are direct method invocations via generated proxies. No service discovery — the runtime tracks where every slice instance lives. No retry logic — built-in retry with exponential backoff and node failover. No circuit breakers — the reliability fabric handles failure automatically. No serialization code — request/response types are serialized transparently.

A method call via imported interface is the only visible contract. The only hint that the actual call might be remote is a design requirement: slice methods should be idempotent. This isn't a limitation — it's what enables retry, scaling, and fault tolerance to work transparently. The same request, processed by any available instance, producing the same result. Most read operations are naturally idempotent. For writes, standard patterns like idempotency keys and conditional writes handle it cleanly.

Everything else is the environment's job: resource provisioning, scaling, transport, discovery, retries, circuit breakers, configuration, observability, logging, tracing, monitoring, security. None of these are application concerns and none should be handled at the business logic level.

The JBCT Leaf pattern serves two purposes here: it documents the design ("what we expect from an external implementation") and encourages exactly one interface per dependency. Different implementations may have different technical properties — performance, latency, memory consumption — but as long as they're compatible with the interface, business logic works unchanged.

You write basically pure business logic that scales from your local computer to a global multi-zone distributed deployment, transparently.

Under The Hood: What Makes It Work

Five architectural decisions make this possible.

Consensus KV Store. A single source of truth for all configuration, deployment state, and service discovery. Based on the Rabia protocol — a crash-fault-tolerant, leaderless consensus algorithm published in 2021. Any node can propose; agreement is reached through a two-round voting protocol with a fast path when super-majority agrees in round one. No external config servers. No etcd. No Consul. Configuration changes propagate through consensus and take effect cluster-wide.

Built-in Artifact Repository. DHT-based storage with configurable replication — 3 replicas with quorum reads/writes in production, full replication in development. Artifacts are chunked into 64KB pieces, distributed across nodes via consistent hashing, and integrity-verified with MD5 and SHA-1 on every resolve. No external Nexus or Artifactory needed. During development, slices resolve from your local Maven repository. In production, the cluster is self-contained.

ClassLoader Isolation. Each slice runs in its own SliceClassLoader with child-first delegation. Two slices can use different versions of the same library without conflict. Shared dependencies like Pragmatica Lite core are loaded once in a parent classloader. No dependency conflicts. No classpath hell between slices.

Declarative Deployment. Blueprints — TOML files — describe the desired state: which slices, how many instances.

id = "org.example:commerce:1.0.0"

[[slices]]
artifact = "org.example:inventory-service:1.0.0"
instances = 3

[[slices]]
artifact = "org.example:order-processor:1.0.0"
instances = 5

Apply with one command: aether blueprint apply commerce.toml. The cluster resolves artifacts, loads slices, distributes instances across nodes, registers routes, and starts serving traffic. The cluster converges to the desired state automatically.

Infrastructure Independence. Aether nodes are identical — there's only one deployment artifact to manage at the infrastructure level. Node updates and application deployments run on completely independent schedules. Update Java — roll it out across nodes without touching applications. Update the Aether runtime — same. Update business logic — deploy new slice versions without touching infrastructure. Each independently, each without downtime. This is the fundamental benefit of proper separation: when layers don't share a deployment unit, they don't share a deployment schedule.

Fault Tolerance: The 50% Rule

The system survives failure of less than half the nodes. Performance may degrade until replacements spin up, but functionality remains intact — actual redundancy, not just graceful degradation. A 5-node cluster tolerates 2 simultaneous failures. A 7-node cluster tolerates 3. The same request, processed by any available node, producing the same result. Quorum requires (N/2) + 1 nodes — as long as a majority is alive, the cluster operates normally.

Leader failover is consensus-based and near-instant. Node replacement happens automatically — the Cluster Deployment Manager detects the deficit and provisions a replacement through the NodeProvider interface. The entire recovery sequence — from failure detection through state restoration to serving traffic — completes without human intervention.

When a node fails, the recovery is automatic. Requests to slices on the failed node are immediately retried on healthy nodes. A replacement node is provisioned. It connects to peers, restores consensus state from a cluster snapshot, re-resolves artifacts from the DHT, and re-activates assigned slices. Dead nodes are automatically removed from routing tables. The new leader reconciles stale state. No human intervention required.

Rolling updates leverage this fault tolerance for zero-downtime deployments with weighted traffic routing:

aether update start org.example:order-processor 2.0.0 -n 3
aether update routing <id> -r 1:3    # 25% to v2, 75% to v1
aether update routing <id> -r 1:1    # 50/50
aether update complete <id>          # 100% to v2, drain v1

Deploy during business hours. Shift traffic gradually — 10% canary, then 25%, 50%, 75%, 100%. Monitor health metrics at each step. If health degrades — error rate exceeds thresholds, latency spikes — instant rollback with one command: aether update rollback <id>. Traffic immediately shifts back to the old version. The 3 AM pager alert becomes an audit log entry.

For Every Project: Legacy, Greenfield, And Everything Between

Legacy Migration

Your legacy Java system doesn't need a complete rewrite. It needs a path forward.

Pick a relatively independent part of your system — something hitting limits, something with clear boundaries. Extract an interface. Annotate it with @Slice. Wrap the legacy implementation:

private Promise<Report> generateReport(ReportRequest request) {
    return Promise.lift(() -> legacyReportService.generate(request));
}

One line to enter the Aether world. Promise.lift() wraps the legacy call, catches exceptions, and returns a proper Result inside a Promise. Your legacy code keeps running. Call sites don't change. You haven't added risk — the initial deployment in Ember runs in the same JVM as your existing application, which means it's no worse than what you have today. You've laid the foundation for removing risk, not adding it. Moving from Ember to a full Aether cluster is a configuration change, not a code change — and that's when the 50% rule starts to apply.

From there, it's the strangler fig pattern. Extract a hot path, deploy it as a slice, route traffic, repeat. Each extracted slice can be gradually refactored using the peeling pattern: first wrap everything in Promise.lift(), then decompose into a Sequencer with each step still wrapped, then peel individual steps into clean JBCT patterns. Tests pass at every step. The lift() calls mark exactly where legacy code remains, making progress visible and remaining work obvious.

No rewrite required. No big bang migration. One sprint to first slice in production. The migration article covers the full path in detail — from initial wrapping through gradual peeling to clean JBCT code.

Greenfield Development

For new projects, slices enable a granularity that's impossible with traditional microservices.

Each slice can be as lean as a single method — and that's the recommended approach. There are no operational or complexity tradeoffs for small slices because Aether handles all the infrastructure overhead. No container to configure, no load balancer to provision, no monitoring to set up per service. You get per-use-case scaling: one slice serving 50 instances during peak load while another idles at minimum. That kind of granularity would be operationally insane with traditional microservices — each needing its own container, load balancer, monitoring, and deployment pipeline. With Aether, it's the default.

JBCT patterns — Leaf, Sequencer, Fork-Join, Condition, Iteration, Aspects — compose naturally within slices. Each slice method is a data transformation pipeline: parse input, gather data, process, respond. The patterns provide consistent structure within slices. Slices provide consistent boundaries between them.

The Spectrum

Same slice model, different granularity. A service slice wraps an entire legacy component. A lean slice implements a single method. Both coexist in the same cluster, deployed and scaled independently.

Slice is the executable unit. It can be big or small as necessary and convenient. The architecture accommodates both monolith migration and greenfield development simultaneously. Your legacy system gains fault tolerance while new features get maximum deployment flexibility.

Scaling: Two Levels, Three Tiers of Intelligence

Two-Level Horizontal Scaling

Aether scales in two dimensions independently:

Slice scaling: Spin up more instances of a specific slice on existing nodes. Classes are already loaded — scaling takes milliseconds, not seconds.
Node scaling: Add more machines to the cluster. The node connects, restores state, and begins accepting work.

Independent controls, combined effect. Each node hosts at most one instance of a given slice, so scaling a slice beyond the current node count requires adding nodes first. Add 2 more nodes to a 3-node cluster, then scale a hot slice to 5 instances — one per node. No coordination between the two dimensions required.

Three-Tier Decision System

Tier 1 — Decision Tree (1-second intervals). Instant reactive decisions based on CPU utilization, request latency, queue depth, and error rate. CPU above 70%? Add an instance. Below 30% sustained? Remove one (if above minimum). Latency exceeding P95 threshold? Scale up. Error rate above 1% due to timeouts? Scale up. Deterministic, predictable, fast. Handles routine load changes with configurable cooldown periods — 30 seconds for scale-up, 5 minutes for scale-down — to prevent oscillation.

Tier 2 — TTM Predictor (60-second intervals). An ONNX-based machine learning model (Tiny Time Mixers) analyzing a 60-minute sliding window of metrics — CPU usage, request rate, P95 latency, active instances. Forecasts load and adjusts the Decision Tree's thresholds preemptively. If TTM predicts a load increase, it lowers the scale-up CPU threshold by 20% so the reactive tier responds earlier. The cluster scales before the spike arrives, not after. The key design principle: the cluster always survives on Tier 1 alone. TTM enhances; it doesn't replace. If TTM fails — model load error, insufficient data, inference failure — the Decision Tree continues with default thresholds. The error is logged and recorded in metrics. No scaling disruption.

Tier 3 — LLM-based (planned). Long-term capacity planning and cluster health monitoring. Seasonal pattern prediction, maintenance window planning, anomaly investigation. This tier is not yet implemented — the current system operates with Tiers 1 and 2.

Fault tolerance makes preemptible instances viable for burst scaling. If a spot instance gets reclaimed, the cluster survives — it was designed for nodes to disappear.

You don't need a PhD in distributed systems or a dedicated platform team. The scaling system manages itself.

Development Experience: From Laptop To Production

Three Environments, Zero Code Changes

Ember. Single-process runtime with multiple cluster nodes running in the same JVM. Fast startup, simple debugging. Deploy your slices alongside your existing application — slices call each other directly in-process. No network overhead. Standard debugger breakpoints work as expected. Perfect for local development and unit testing.

Forge. A 5-node cluster simulator running on your laptop. Real consensus. Real routing. Real failure scenarios. Kill nodes, crash the leader, trigger rolling restarts — and watch the cluster recover in real time through a web dashboard with D3.js topology visualization, per-node metrics (CPU, heap, leader status), and event timeline. Configurable load generation with TOML-based multi-target configuration lets you stress-test realistic scenarios — set request rates, define body templates, and run duration-limited load tests. Chaos operations include node kill, leader kill, and rolling restart. Forge validates the entire dependency graph before starting anything.

Aether. Production cluster. Same slices, same code, different scale. Your code doesn't know which environment it's running in. Whether inter-slice calls are in-process or cross-network is transparent.

Tooling

37 CLI commands cover deployment, scaling, updates, artifacts, observability, controller configuration, and alerts — in both single-command and interactive REPL modes. A web dashboard streams real-time metrics via WebSocket — no polling. 30+ REST management endpoints enable full programmatic control of everything the CLI can do. Prometheus-compatible metrics export (/metrics/prometheus) integrates with existing monitoring stacks. Metrics are push-based at 1-second intervals, with zero consensus overhead — they bypass the consensus protocol entirely. Per-method invocation tracking with P50/P95/P99 latency and configurable slow-invocation detection strategies (fixed threshold, adaptive, per-method, composite) surfaces performance issues before users notice. Dynamic aspects let you toggle LOG/METRICS/LOG_AND_METRICS modes per method at runtime via REST API, without redeployment.

Test realistic failure scenarios on your laptop. Deploy to production with a config change, not a code change.

Maturity

Aether is a working system, not a concept paper.

81 end-to-end tests run against real 5-node clusters in Podman containers, validating cluster formation, quorum establishment, slice deployment and scaling, blueprint application with topological ordering, multi-instance distribution, artifact upload and cross-node resolution with integrity verification, leader failure and recovery, node restart with state restoration, and orphaned state cleanup after leader changes.

The recovery and fault tolerance claims come from automated tests against real clusters, not marketing slides.

Let Java Be Java

Java's lineage leads here. From applets managed by browsers, through servlets managed by application servers, through EJBs managed by enterprise containers, through OSGi managed by runtime frameworks — to Aether, managed by a distributed runtime.

The fat-jar era was a detour. An understandable one — when Docker emerged, it offered a universal packaging format, and the industry standardized on it regardless of language. Java adopted the patterns of languages that were designed to produce standalone binaries. We started treating Java applications like Go programs with a heavier runtime. But it was never the destination. Java was designed for managed environments. The JVM makes it possible. The runtime manages the application. That's the lineage. Aether continues it.

Two entry points exist today. Wrap your legacy monolith behind a @Slice interface in one sprint and gain fault tolerance without rewriting anything. Or start fresh with maximum clarity — lean slices, explicit contracts, per-use-case scaling. Both paths converge on the same runtime, the same cluster, the same operational model. Both paths can coexist — legacy service slices and new lean slices running side by side.

Fault tolerance is not an afterthought — it's the foundation. Scaling is not your problem — it's the environment's. Infrastructure is not your code — it's the runtime's. The heavy winter coat comes off. The application breathes.

Pragmatica Aether — project site
GitHub Repository — source code

Let Java be Java. Let infrastructure be infrastructure. Write business logic that scales from your laptop to global deployment without changing a line of code.

Why Interface + Factory? The Java Pattern That Makes Everything Replaceable

Sergiy Yevtushenko — Sat, 07 Feb 2026 21:39:17 +0000

Why Interface + Factory? The Java Pattern That Makes Everything Replaceable

The Pattern

Every component — use case, processing step, adapter — is defined as an interface with a static factory method:

public interface ProcessOrder {
    record Request(String orderId, String paymentToken) {}
    record Response(OrderConfirmation confirmation) {}

    Result<Response> execute(Request request);

    interface ValidateInput {
        Result<ValidRequest> apply(Request raw);
    }
    interface ReserveInventory {
        Result<Reservation> apply(ValidRequest req);
    }
    interface ProcessPayment {
        Result<Payment> apply(Reservation reservation);
    }
    interface ConfirmOrder {
        Result<Response> apply(Payment payment);
    }

    static ProcessOrder processOrder(ValidateInput validate,
                                     ReserveInventory reserve,
                                     ProcessPayment processPayment,
                                     ConfirmOrder confirm) {
        return request -> validate.apply(request)
                                  .flatMap(reserve::apply)
                                  .flatMap(processPayment::apply)
                                  .flatMap(confirm::apply);
    }
}

Four steps. Each is a single-method interface. The factory method accepts all dependencies as parameters and returns a lambda implementing the use case. The body reads exactly like the business process: validate, reserve, process payment, confirm.

This isn't arbitrary convention. There are three specific reasons this structure exists.

Reason 1: Substitutability Without Magic

Anyone can implement the interface. No framework. No inheritance hierarchy. No annotations.

Testing becomes trivial:

@Test
void order_fails_when_inventory_insufficient() {
    var useCase = ProcessOrder.processOrder(
        request -> Result.success(new ValidRequest(request)),  // always valid
        req -> INSUFFICIENT_INVENTORY.result(),                // always fails
        reservation -> { throw new AssertionError("unreachable"); },
        payment -> { throw new AssertionError("unreachable"); }
    );

    useCase.execute(new Request("order-1", "tok_123"))
           .onSuccess(Assertions::fail);
}

No mocking framework. No @Mock annotations. No when().thenReturn() chains. The test constructs the exact scenario it needs with plain lambdas.

Stubbing incomplete implementations during development is equally straightforward:

// Payment gateway isn't ready yet? Stub it.
var useCase = ProcessOrder.processOrder(
    realValidator,
    realInventoryService,
    reservation -> Result.success(new Payment("stub-" + reservation.id(), Money.ZERO)),
    realConfirmation
);

The team working on inventory doesn't need to wait for the payment team. Each step is independently implementable.

Reason 2: Implementation Isolation

Each implementation is self-contained. No shared base classes. No abstract methods to override. No coupling between implementations whatsoever.

Compare with the typical abstract class approach:

// The abstract class trap
public abstract class AbstractOrderProcessor {
    protected final Logger log = LoggerFactory.getLogger(getClass());

    public final Result<Response> execute(Request request) {
        log.info("Processing order: {}", request.orderId());
        var result = doExecute(request);
        log.info("Order result: {}", result);
        return result;
    }

    protected abstract Result<Response> doExecute(Request request);
    protected abstract Result<ValidRequest> validate(Request request);

    // "Shared utility" that every subclass now depends on
    protected Result<Money> calculateTotal(List<LineItem> items) {
        // 47 lines of logic that one subclass needed once
    }
}

Now every implementation is coupled to the base class. Change calculateTotal and you need to understand every subclass. Add logging to execute and every implementation gets it whether appropriate or not. The base class becomes a gravity well — accumulating shared code that creates invisible dependencies between implementations that should have nothing in common.

With interface + factory, there is no shared implementation code. Period. Each intersection between implementations is unnecessary coupling with corresponding maintenance overhead — up to needing deep understanding of two projects instead of one, with zero benefit.

// Implementation A: uses database
static ProcessPayment databasePayment(PaymentRepository repo) {
    return reservation -> repo.charge(reservation.paymentToken(), reservation.total())
                              .map(Payment::fromRecord);
}

// Implementation B: uses external API
static ProcessPayment stripePayment(StripeClient client) {
    return reservation -> client.createCharge(reservation.total(), reservation.paymentToken())
                                .map(Payment::fromStripe);
}

These implementations don't know about each other. They don't share code. They don't share a base class. They share a contract — the interface — and nothing else.

Reason 3: Disposable Implementation

Here's the subtle one. The factory method returns a lambda or local record. It can't be referenced externally by class name.

static ProcessOrder processOrder(ValidateInput validate,
                                 ReserveInventory reserve,
                                 ProcessPayment processPayment,
                                 ConfirmOrder confirm) {
    return request -> validate.apply(request)          // this lambda IS the implementation
                              .flatMap(reserve::apply)
                              .flatMap(processPayment::apply)
                              .flatMap(confirm::apply);
}

No code anywhere says new ProcessOrderImpl(). No code depends on the implementation class. The implementation is replaceable by definition — because nothing can reference it.

The interface is the design artifact. The implementation is incidental.

This might sound academic until you need to:

Replace a synchronous implementation with an async one
Swap a database adapter for an API adapter
Add a caching layer around an existing step
Completely rewrite a step's internals

In each case, the interface stays. The factory method signature stays. The implementation — which nothing references — gets replaced. No downstream changes. No adapter layers. No "backwards compatibility."

The Compound Effect

Each reason is valuable on its own. Together, they create a system where:

Testing is configuration. You assemble the exact combination of real and stubbed components you need. No mocking framework overhead. No "mock everything" test fragility.

Refactoring is safe. Replacing an implementation can't break other implementations because they don't share code. The compiler enforces the contract through the interface.

Complexity is bounded. Understanding one implementation requires understanding only that implementation and the interfaces it consumes. Not a base class hierarchy. Not shared utilities. Not other implementations.

Incremental development is natural. Stub what's not ready. Replace stubs with real implementations one at a time. Each step can be developed, tested, and deployed independently.

When Does This Not Apply?

When there genuinely is one implementation and always will be. Pure utility functions, mathematical computations, simple data transformations — these don't need the interface + factory treatment. A static method is fine.

The pattern pays for itself when there's any possibility of multiple implementations — including the test implementation, which almost always exists.

The Shift

Most Java codebases default to classes. Interface extraction happens later, reluctantly, when testing forces it or when the second implementation appears.

Flip this. Start with the interface. Define the contract. The implementation follows naturally — and when it needs to change, nothing else does.

The interface is what you design. The implementation is what you happen to write today.

Fail-Safe Your Legacy Java in One Sprint

Sergiy Yevtushenko — Tue, 27 Jan 2026 12:24:03 +0000

Fail-Safe Your Legacy Java in One Sprint

The Scaling Wall

Your Java system works. It's been working for years. But lately, it's showing strain. Response times creep up during peak hours. That batch job that used to finish overnight now runs into morning operations. Users notice.

The conventional answer is microservices. Decompose the monolith, deploy to Kubernetes, hire a platform team. Eighteen months, significant budget, and a team with specialized skills you don't have. Meanwhile, every deployment feels like Russian roulette. One bad release, one server failure, and the business stops.

For middle-sized businesses, this isn't a technology problem. It's a survival problem. The system that runs your operations is both essential and fragile. You can't afford to replace it, and you can't afford to lose it.

The 50% Rule

What if half your servers could fail and users wouldn't notice?

Aether, the runtime behind the slice architecture, provides exactly this guarantee. When your code runs across a cluster, failure of less than half the nodes affects only performance, not functionality. Requests automatically route to surviving nodes. No manual intervention, no pager alerts at 3 AM.

This isn't eventual consistency or graceful degradation. It's actual redundancy. The same request, processed by any available node, producing the same result. Your business keeps running while you fix the failed hardware.

For a C-level executive, this translates simply: business continuity without enterprise budget. The system that runs your operations becomes the system that survives failures.

The Simplest Migration Path

Here's how to start. Pick a relatively independent part of your system. Something that's already hitting limits. Something with clear boundaries.

Step 1: Extract an interface. This is mechanical. Any Java developer can do it. The interface defines what the component does, not how.

@Slice
public interface ReportGenerator {
    Promise<Report> generateReport(ReportRequest request);
}

Step 2: Make it idempotent. The same request should produce the same result, even if processed multiple times. Pragmatica Lite provides built-in support for this pattern. For most code, it's a small change.

Step 3: Deploy Ember. Ember runs multiple cluster nodes in the same JVM as your existing application. Your legacy code calls the interface exactly as before. No changes to call sites.

That's it. Your first slice is running.

Important caveat: This initial step is not fault-tolerant. You're still running in a single JVM, which means a single point of failure. But here's the key insight: it's no worse than what you have today. You haven't added risk. You've laid the foundation for removing it.

From Foundation to Fault Tolerance

The foundation is in place. Now you can build on it.

Moving from Ember to full Aether deployment is a configuration change, not a code change. Your slices, your interfaces, your business logic—all unchanged. You're just telling the runtime to distribute across multiple machines instead of running in-process.

Now the 50% rule applies. Your report generator runs on three nodes. One dies. The other two handle the load. You fix the failed node when convenient, not when panicked.

Each step in this path delivers value:

Ember in-JVM: Foundation laid, no new risk
Ember multi-node: Development and testing environment
Aether cluster: Production fault tolerance

You control the pace. Extract another slice when ready. Expand the cluster when needed. The architecture grows with your confidence.

The Peeling Pattern

Once your slice is running, you have a choice: leave the internals as-is, or gradually refactor them. The peeling pattern lets you do the latter without risk.

Phase 1: Wrap everything. Your initial slice wraps the entire legacy method:

private Promise<Report> generateReport(ReportRequest request) {
    return Promise.lift(() -> legacyReportService.generate(request));
}

Phase 2: Peel the outer layer. Refactor into a Sequencer, but keep each step wrapped:

private Promise<Report> generateReport(ReportRequest request) {
    return validateRequest(request)
        .flatMap(valid -> Promise.lift(() -> legacyFetchData(valid)))
        .flatMap(data -> Promise.lift(() -> legacyProcess(data)))
        .flatMap(result -> Promise.lift(() -> legacyFormat(result)));
}

Phase 3: Peel deeper. Take one wrapped step and expand it:

private Promise<RawData> fetchData(ValidRequest request) {
    return Promise.all(
        Promise.lift(() -> legacyFetchFromDb(request)),
        Promise.lift(() -> legacyFetchFromApi(request))
    ).map(this::combineData);
}

Each phase keeps the code working. Tests pass at every step. You can stop anywhere—the system runs fine with mixed JBCT and wrapped legacy code. The lift() calls mark exactly where legacy code remains, making progress visible and the remaining work obvious.

What You Don't Need

Traditional modernization projects require capabilities most middle-sized businesses don't have. Aether is different.

No Kubernetes expertise. Aether manages its own clustering. You don't need to learn pod configurations, service meshes, or container orchestration.

No platform team. The runtime handles deployment, discovery, and failover. Your existing operations team can manage it.

No new infrastructure. Start with Ember in your existing JVM. Add machines only when you're ready for fault tolerance.

No retraining. Same Java. Same IDE. Same debugging. Your developers write slice interfaces exactly like they write any other interface. The patterns are familiar; only the deployment model changes.

The migration path is designed for teams that have a business to run, not a technology transformation to execute.

The Path Forward

Once the foundation is working, possibilities open up.

More slices mean more of your system becomes fault-tolerant. The relatively independent parts you migrated first are now proven. You understand the pattern. The next extraction is faster.

Aether's operational model scales beyond manual management. A three-tier control system handles increasingly complex decisions:

Decision trees handle routine scaling—deterministic, predictable, fast
TTM (predictive models) detect patterns and scale preemptively
LLM agents (planned) handle capacity planning and anomaly investigation

You're not just surviving anymore. You're building toward a system that manages itself.

Conclusion

The legacy Java system running your business doesn't need a complete rewrite. It needs a path forward that doesn't bet the company on an 18-month transformation project.

Start with one slice. Run it in Ember alongside your existing code. Prove it works. Then decide: add fault tolerance, extract another slice, or pause and let the system prove itself in production.

The 50% rule isn't a promise for someday. It's a capability you can reach in weeks, not years. Your business deserves infrastructure that survives failures. Now there's a path to get there.

Part of Java Backend Coding Technology - a methodology for writing predictable, testable backend code.

Slices: The Right Size for Microservices

Sergiy Yevtushenko — Sun, 18 Jan 2026 21:49:19 +0000

Slices: The Right Size for Microservices

The Granularity Trap

Every team that adopts microservices eventually hits the same wall: how big should a service be?

Go too small and you drown in network calls, distributed transactions, and deployment complexity. Your simple "get user profile" operation now involves five services, three of which are just proxies for database tables. Latency compounds. Debugging becomes archaeology.

Go too large and you're back to the monolith. Different teams step on each other. Deployments require coordination. The "micro" in microservices becomes ironic.

The standard advice—"one service per bounded context" or "services should be independently deployable"—sounds reasonable but provides no actionable guidance. Where does one context end and another begin? What exactly makes something "independently deployable"?

Teams oscillate between extremes, refactoring services that are "too small" into larger ones, then splitting services that grew "too large." The cycle repeats because the fundamental question remains unanswered: what determines the right boundary?

Boundaries Before Size

The problem isn't size. It's boundaries.

A well-defined boundary has specific properties:

Clear contract: callers know exactly what they can request and what they'll receive
Explicit dependencies: the component declares what it needs from outside
Internal freedom: implementation details can change without affecting callers

Size follows from boundaries, not the other way around. A component is the right size when it fully owns its boundaries—when everything needed to fulfill its contract lives inside, and everything outside is accessed through explicit dependencies.

This is where most microservice designs fail. They draw boundaries based on technical layers (API gateway, business logic, database access) or organizational structure (team ownership). Neither approach produces stable boundaries because neither focuses on the actual contracts between components.

What Is a Slice?

A slice is a deployable unit defined by its contract. You write an interface with a single annotation:

@Slice
public interface OrderService {
    Promise<OrderResponse> createOrder(CreateOrderRequest request);
    Promise<OrderResponse> getOrder(GetOrderRequest request);
    Promise<Unit> cancelOrder(CancelOrderRequest request);
}

That's it. The annotation processor generates everything else—factory methods, dependency wiring, deployment metadata. You define the contract; the tooling handles the infrastructure.

This interface is the boundary:

Methods define the contract: each takes a request, returns a promise of response
Request/response types are explicit: no hidden parameters, no ambient context
Async by default: Promise<T> handles both success and failure paths

The implementation lives behind this interface. It might be simple or complex. It might call other slices or be completely self-contained. The boundary doesn't care.

Aether and Forge: Development Made Simple

Slices run on Aether, a distributed runtime designed around slice contracts. You don't configure service discovery, serialization, or inter-slice communication—Aether handles it based on what the slice interfaces declare. Every inter-slice call eventually succeeds if the cluster is alive; the runtime manages retries, failover, and recovery transparently.

Forge provides a development environment for testing slices under realistic conditions—load generation, chaos injection, backend simulation. Instead of deploying to staging to see how your slices behave under pressure, you run Forge locally and observe.

The development experience stays simple: write @Slice interfaces, implement them, test with Forge, deploy to Aether. The annotation processor generates all the boilerplate—factories, dependency wiring, routing metadata.

Dependencies That Don't Lie

Traditional service architectures bury dependencies in configuration files, environment variables, or runtime discovery. You find out what a service needs by reading its code, tracing its network calls, or waiting for it to fail in production.

Slices declare dependencies in the interface:

@Slice
public interface OrderService {
    Promise<OrderResponse> createOrder(CreateOrderRequest request);
    // Other methods...

    // Factory method declares dependencies explicitly
    static OrderService orderService(InventoryService inventory, PaymentService payment) {
        return OrderServiceFactory.orderService(Aspect.identity(), inventory, payment);
    }
}

The annotation processor generates the factory that wires everything:

public final class OrderServiceFactory {
    private OrderServiceFactory() {}

    public static OrderService orderService(
            Aspect<OrderService> aspect,
            InventoryService inventory,
            PaymentService payment) {
        return aspect.apply(new OrderServiceImpl(inventory, payment));
    }
}

The factory method signature declares dependencies. No service locators, no runtime discovery, no configuration files that might or might not match reality. Dependencies are visible at compile time and verified before deployment.

This explicitness matters. You can trace the dependency graph by reading code. You can test with substitutes by passing different implementations. Forge validates the entire graph before starting anything.

Same Code, Different Environments

The same slices run unchanged across three runtime modes:

Ember: Single-process runtime with multiple cluster nodes. Fast startup, simple debugging. Perfect for local development.
Forge: Ember plus load generation and chaos injection. Test how slices behave under pressure without deploying anywhere.
Aether: Full distributed cluster. Production deployment with all the resilience guarantees.

Your code doesn't know which mode it's running in. Slice interfaces, implementations, and dependencies stay identical. The runtime handles the difference—whether inter-slice calls are in-process or cross-network is transparent.

This changes the development workflow. You write and debug in Ember. You stress-test in Forge. You deploy to Aether. At no point do you modify slice code to accommodate the environment.

Right-Sized by Definition

With boundaries explicit and deployment flexible, the "right size" question dissolves.

A slice is the right size when:

Its interface captures a coherent set of operations
Its dependencies accurately reflect what it needs
Its implementation can fulfill its contract

There's no minimum or maximum. An authentication slice might have two methods. An order processing slice might have twenty. Size follows from the domain, not from arbitrary rules about lines of code or team structure.

More importantly, getting it wrong is recoverable. Split a slice that grew too complex? The boundary changes, but callers just see a new interface. Merge slices that were artificially separated? Same story. Refactoring slices is refactoring code, not rewriting infrastructure.

The JBCT Connection

Slices are where JBCT patterns live.

Each slice method is a data transformation pipeline:

Parse input (validated request types)
Gather data (dependencies, other slices)
Process (business logic)
Respond (typed response)

The six patterns—Leaf, Sequencer, Fork-Join, Condition, Iteration, Aspects—compose within and across slice methods. A slice is simply the deployment boundary around a set of related transformations.

This is why the combination works. JBCT gives you consistent structure within slices. Slices give you consistent boundaries between them. Together, they eliminate the two sources of architectural entropy: inconsistent implementation patterns and unclear service boundaries.

Conclusion

The microservices granularity problem persists because it asks the wrong question. "How big should a service be?" has no good answer. "What are the contracts between components?" has a precise one.

Slices shift focus from size to boundaries. Define the interface. Declare dependencies explicitly. Let deployment topology adapt to operational needs rather than dictating code structure.

The result: boundaries that are clear by construction, dependencies that are visible by design, and deployment flexibility that doesn't require rewriting code.

Part of Java Backend Coding Technology - a methodology for writing predictable, testable backend code.

The Six Patterns That Cover Everything

Sergiy Yevtushenko — Wed, 14 Jan 2026 23:12:12 +0000

The Six Patterns That Cover Everything

The Complete Vocabulary

Every data transformation you'll ever write falls into one of six patterns:

Leaf - One thing. No substeps. Atomic.
Sequencer - This, then that. Output becomes input.
Fork-Join - These together, then combine. Independent operations merging.
Condition - Which path? Route based on value.
Iteration - Same thing, many times. Transform a collection.
Aspects - Wrap it. Add retry, timeout, logging around an operation.

That's it. Six patterns. They cover everything.

Not "cover most cases." Not "work well for common scenarios." Everything. Every piece of request processing logic you'll ever write is one of these six, or a composition of them.

Why Only Six?

These aren't design patterns someone invented. They're the fundamental ways data can flow:

Transform a value (Leaf)
Chain dependent transforms (Sequencer)
Combine independent transforms (Fork-Join)
Choose between transforms (Condition)
Apply transform to many values (Iteration)
Enhance a transform (Aspects)

There's no seventh option. Data either transforms, chains, combines, branches, iterates, or gets wrapped. That's the complete set of possibilities.

This is why learning six patterns gives you everything. Not because JBCT is comprehensive - because reality is constrained.

The Strange Coincidence

Here's what's remarkable: these same six patterns describe every business process.

Think about any workflow in your domain:

Leaf: "Validate the email format" - one check, atomic
Sequencer: "First verify identity, then check permissions, then grant access" - dependent chain
Fork-Join: "Get user profile, account balance, and recent transactions, then build the dashboard" - independent data gathering
Condition: "If premium user, apply discount; otherwise, standard pricing" - routing
Iteration: "For each item in cart, calculate tax" - collection processing
Aspects: "Log every payment attempt" - cross-cutting concern

Business processes and code patterns use the same vocabulary. This isn't coincidence. It's because both describe how information flows and transforms. Business logic IS data transformation - we just use different words for it.

The Common Language

This equivalence creates something powerful: a shared language between developers and business stakeholders.

Watch the precision gain:

Before: "Get the user's stuff and show it"

After: "Fork-Join: fetch profile, preferences, and history in parallel, then combine into dashboard view"

Same requirement. One is vague. One is implementable.

When a developer asks "Can these operations run in parallel?" they're really asking "Do these steps depend on each other's results?"

When business says "First we verify, then we process, then we notify" - that's a Sequencer. Directly translatable to code.

When business says "We need the user's profile, their preferences, and their history to show the dashboard" - that's a Fork-Join. Three independent fetches, one combined result.

The translation becomes mechanical:

"Check if..." → Leaf → Single validation
"First... then... then..." → Sequencer → .flatMap() chain
"Get X and Y and Z, then..." → Fork-Join → Promise.all()
"If... otherwise..." → Condition → Ternary/switch
"For each..." → Iteration → .map() / loop
"Always log/retry/timeout..." → Aspects → Wrapper function

No translation layer. No impedance mismatch. The same six concepts, different vocabulary.

Gap Detection

Here's where it gets interesting. When you model business processes using these patterns, gaps become visible.

Missing validation:
You're building a Sequencer: verify -> process -> notify. But what validates the input before "verify"? The pattern demands something produces the input for step one. If nothing does, you've found a gap.

Unclear dependencies:
Business describes five things that need to happen. Are they a Sequencer (dependent chain) or Fork-Join (independent operations)? If they can't tell you which outputs feed which inputs, the process isn't fully defined.

Missing error handling:
Every Leaf can fail. Every step in a Sequencer can fail. When you map business process to patterns, you naturally ask: "What happens when this fails?" If they don't know, you've found a gap.

Inefficient flows:
Business describes a sequential process: get A, then get B, then get C, then combine. But if A, B, and C don't depend on each other, this should be Fork-Join, not Sequencer. The pattern reveals the inefficiency.

The patterns don't just implement requirements - they validate them.

The Right Questions

Once you think in patterns, the right questions emerge naturally:

At the start (Leaf/Validation):

"How do we know this request is valid?"
"What makes an email/phone/amount valid in your domain?"
"What's the first thing we need to verify?"

For sequences (Sequencer):

"What do we need from step 1 to perform step 2?"
"Can step 3 ever happen if step 2 fails?"
"Is this order fixed, or could steps be reordered?"

For parallel work (Fork-Join):

"Do these operations depend on each other?"
"Can we fetch user profile while also fetching their orders?"
"What do we do if one succeeds and another fails?"

For branching (Condition):

"What determines which path we take?"
"Are these paths mutually exclusive?"
"Is there a default path?"

For collections (Iteration):

"Do we process all items or stop at first failure?"
"Does order matter?"
"Can items be processed independently (in parallel)?"

For cross-cutting concerns (Aspects):

"Should we retry on failure? How many times?"
"Is there a timeout?"
"What needs to be logged/measured?"

You're not inventing questions. The patterns generate them. Each pattern has a fixed set of things that must be defined. If they're not defined, you ask.

From Patterns to Process Design

The flow works both ways.

Forward: Business describes a process -> you identify patterns -> you implement code

Backward: You see the patterns -> you notice gaps -> you ask questions -> business clarifies -> process improves

This backward flow is underrated. Developers who think in patterns become process consultants. They don't just implement what they're told - they improve what they're told by making implicit assumptions explicit.

"You said first A, then B, then C. But B doesn't use A's output. Can B and A happen at the same time? That would be faster."

"You said validate the request. What exactly are we validating? Email format? Email exists in system? User is active? Each is a separate check."

"You said handle the error. Which error? Network timeout? Invalid data? User not found? Each might need different handling."

The patterns force precision. Vague requirements become concrete when you have to place them in one of six boxes.

The Result

When developers and business share this vocabulary:

Requirements discussions become technical design sessions
Gaps surface during conversation, not during implementation
Code structure mirrors business process (because they're the same thing)
Changes in business process map directly to code changes
New team members understand both business and code faster

Six patterns. Complete coverage. Shared language. Gap detection built in.

This is why pattern-based thinking isn't just a coding technique. It's a communication framework that makes the implicit explicit and the vague precise.

The irony? You'll spend an hour asking the right questions. The coding takes 30 seconds. Turns out the "coding technology" is mostly about not coding.

Part of Java Backend Coding Technology - a methodology for writing predictable, testable backend code.

Previous: The Underlying Process of Request Processing