adam bien's blog

A Package per Feature made the case for the Business Component (BC): one package per responsibility. Inside a BC the next question appears immediately: where does a class go? In most projects that question spawns bureaucracy: naming debates, layout documents, style-guide meetings. BCE answers it once, with three fixed packages. The generation BC from lightmetal:

lm.generation
├── boundary
│   ├── LightMetal.java
│   ├── LightMetalChat.java
│   └── LightMetalText.java
├── control
│   └── TokenAccumulator.java
└── entity
    ├── Response.java
    └── Tps.java

The motivations:

1. No placement debates. Every class has exactly one obvious home. The three names are fixed, so reviews argue about the semantics, not bureaucracy, and every BC in every project reads the same way. The convention is cross-technology: the same three package names structure a Java server, a web frontend, or infrastructure code. MVC only names roles, and every MVC framework invented its own directory layout. BCE is the only architectural standard where the layer names are the structure itself, fixed for over three decades.
2. One entry point for the outside world. The boundary is the facade actors talk to: the CLI, an HTTP client, a test. It adapts external protocols and carries cross-cutting concerns like mapping or authorization. Other BCs may call control directly; external actors never do.
3. Logic stays procedural. control holds stateless, function-like units. They are implementation details, trivially unit-testable and freely replaceable.
4. State has a home. entity holds the domain objects. They can be rich, carrying behavior next to their data, or anemic records passed between controls. Both are fine; what is fixed is where they live.

Dependencies flow in one direction: boundary calls control, control uses entity, never the reverse. And a BC only gets the layers its responsibility demands: lm.tokenization is a single control package, and that is fine.

See bce.design for the pattern rules. And yes, LLMs also like stability and predictability: airails.dev.

A feature request never arrives as "change all DTOs", it arrives as "implement support for NVIDIA Nemotron". Such a requirement lands in one main responsibility, with minor adjustments rippling into a few neighboring ones. Code organized by responsibility makes this visible: the package names tell you where the work happens and what gets touched as collateral. This is the idea behind the Business Component (BC): a package named after a responsibility, not a technology.

lightmetal, a zero-dependency Java 25 CLI application for GPU LLM inference on Apple Silicon, is structured this way. Every direct child of the lm package is a BC:

lm
├── catalog
├── configuration
├── generation
├── prompting
├── sampling
└── tokenization

Reading the package names tells you what the application does. No services, no utils, no helpers.

Inside, every BC follows the same convention from the BCE (Boundary-Control-Entity) pattern: up to three layers named boundary, control, and entity. The pattern goes back to Ivar Jacobson's use-case-driven OOSE from 1992, and the layer names have stayed stable for over three decades, while the industry cycled through DAOs, DTOs, Managers, Services, and Repositories.

See bce.design for the pattern and sbce.dev for the spec-driven workflow built on it.

TLDR: a static site splits into business components (BCs), each a directory exposing an index.html built with semantic markup and web standards only.

The BCE pattern is usually explained with Java: JAX-RS resources as boundaries, stateless logic as controls, Records or JPA entities. A static website has no code at all, and the mapping still works.

A static site built using only semantic HTML and modern CSS, with no JavaScript or build system, can be easily broken down into the three BCE layers:

1. Boundary: semantic HTML pages. The entry points for all external actors: users, crawlers, assistive technology. Landmarks, heading hierarchy, labeled forms, skip links. Exactly what a boundary does: expose the component to the outside world in coarse-grained operations. Here the operation is a page view.
2. Control: CSS-only interactivity. Behavior without scripts: details/summary accordions, :target modals, :checked tabs and hamburger menus, :hover + :focus-within dropdowns. State lives in native HTML elements, transitions are pure CSS. Stateless, declarative logic: a control layer with zero failure modes.
3. Entity: content and design tokens. Custom properties on :root are the domain model of the design: colors, spacing, typography, radii. Page rules reference tokens, never raw values. The same discipline as entities owning the data and everything else referencing them.

The business component structure carries over too. Content areas become BC directories named after domain topics:

site/
├── index.html
├── css/style.css
├── workshops/
│   ├── index.html
│   └── checks.md
└── trainings/
    ├── index.html
    └── checks.md

The boundary, control, and entity folders inside each component are omitted for the sake of simplicity.

Each component ships its own checks.md: observable, browser-verifiable expectations per page. Verification happens from the outside, by driving a real browser against the rendered pages: the interaction rules of a system with no code.

BCE is about separating entry points, behavior, and data. Turns out that separation exists even when the whole application is files on a web server. The approach is also fully Spec-Driven Design compatible: each BC maps to a capability spec (sbce.space).

Details: bce.design/web-static.html

1. Spec-Driven Development (SDD) on top of the Boundary Control Entity (BCE) pattern
2. why decades-old, well-documented BCE (traced to Objectory, 1992) lets LLMs generate lean, idiomatic code
3. SBCE as a single ~180-line text-file skill with "new" and "apply" actions, no CLI, no binary dependencies
4. the spec is "done" when all tests are green
5. inversion of control: tech stacks (Java CLI, MicroProfile server, web components, web static) declare participation, SBCE knows nothing about them
6. a business component is a package in Java and a folder on the web
7. exclusive reliance on open, crawlable standards: MicroProfile, Jakarta EE, BCE, JSRs, JAX-RS, EARS requirement syntax from Rolls-Royce
8. token economy via convention over configuration: reported 30-80% savings vs generic spec-kit / OpenSpec
9. package-info.java as the only coupling to the SDD process, specs living in Javadoc rendered via JMarkDoc
10. traceability between EARS requirements and generated tests
11. live demo: a Quarkus MicroProfile "episodes" component generated with SBCE new + apply, producing records, JAX-RS resources, resource clients and integration/system tests with requirement markers
12. live demo: a web static airhacks.tv episodes site built with BCE and static pages
13. standards-based CSS with custom properties / design tokens and Google Baseline, served by a zero-dependency ~60-line Java 25 web server
14. answering an 8-year-old ECB question from 2018 (episode 48) live via an LLM
15. Time Machine: revisiting ECB/BCE, JSF status, JSON-B vs JSON-P (preferring JSON-P with LLMs), Kafka / CQRS / event-driven architecture, closing JDBC connections back to the pool, and Light4J still going strong after ~10 years
16. where to put exceptions, repositories and utility classes in BCE: inside the owning business component, JAX-RS WebApplicationException subclasses, a project-wide "faults" package only if genuinely needed
17. BCE scales horizontally as a flat list of business components
18. BCE works with other languages, but LLMs generate Java more reliably (Tencent study)
19. keeping command line Maven as source of truth and upgrading the VS Code Java runtime to Java 25
20. CQRS / event-driven use cases: Kafka streams from wearables, DynamoDB streams and materialized views
21. a minimal event-listening router as a Vaadin Router replacement
22. local inference with Light Metal (Llama.cpp + Java 25, zero dependencies) running Nemotron and Gemma, with "lm list/prompt/serve" exposing OpenAI/Anthropic-compatible APIs
23. zsmith: a pure Java 25 agent framework with virtual-thread sub-agents and JFR events (viewable in JProfiler or JDK Mission Control), connecting to Claude, OpenAI, Bedrock and Light Metal
24. LLM-assisted legacy migration to Java 25 using SDD, OpenRewrite and BCE
25. skills downloadable as a zip, installed via a Java 25 script, no Node.js required

Ask questions during the show via twitter mentioning me: https://twitter.com/AdamBien (@AdamBien),using the hashtag: #airhacks or built-in chat at: airhacks.tv. You can join the Q&A session live each first Monday of month, 8 P.M at airhacks.tv

1. airhacks.tv became a YouTube show
2. Spec-Driven ("space" SBCE) BCE Demo
3. VS Code Java tooling issues
4. JMarkDoc announcement
5. LightMetal and zsmith news
6. BCE for ...static pages
7. Time machine: 100 episodes back (48th episode):

   JSON-B serialisation and deserialization, Automating Jenkins CI with Groovy, light4j, embedded SQL, CQRS streams and Java EE, 40k rows with JSF, Logging and debugging nasty libraries, Monitoring EJB transactions, JMS queue monitoring, REST authentication, Marshal and unmarshal JAX-B objects, ECB pattern in larger applications, Is JSF deprecated, Migrating Java EE projects, DataSource within Java EE: how to close a JDBC connection?

Any questions left? Ask now: gist.github.com/AdamBien/3a3090b3f6a6c1a686cdc8ca8a54d367 and get the answers at the next airhacks.tv. Some questions are also answered with a short video: 60 seconds or less with Java

See you at: youtube.com/bienadam/live

Subscribe to airhacks.fm podcast via: spotify| iTunes

SBCE (say "space"), short for Spec-Driven BCE, is a workflow: every capability is declared as a single spec, and the spec is the boundary contract (package-info.java or package-info.md for Web Components) of exactly one Boundary-Control-Entity business component (e.g. one Java package) with the same name. It ships as a AIrails skill: /sbce. No CLI, no dependencies.

BCE (skill: /bce) sets the architecture invariants: boundary/control/entity layering, package structure, naming rules. /sbce owns the workflow on top: declare a capability, then iterate on the code until it matches. SBCE provides the spec, BCE places the code, and a tech stack skill (java-cli-app, microprofile-server, web-components, web-static) adds code idioms and verification.

The spec lives in the BC's package doc: package-info.java as Markdown JavaDoc (JEP 467), co-located with the code it governs. No separate specs/ tree. The spec is just a better version of the JavaDoc a developer had to write anyway:

greetings
package-info.java   the spec: boundary ops + EARS requirements
boundary/           one method per declared operation
control/            implementation -- no spec section
entity/             maps to ## Entities

For a greetings BC, the entire spec is the package-info.java:

/// # Greetings
/// > Return a personalised greeting for a name.
///
/// ## Boundary
/// - `greet-visitor` — return a greeting for a name
///
/// ## Requirements
/// ### R1: Greet a visitor
/// - R1.1 — When a name is submitted, the BC shall return a
///   greeting containing that name.
/// - R1.2 — If the name is blank, then the BC shall reject
///   the request.
///
/// ## Out of scope
package airhacks.reception.greetings;

Everything in the spec is what, never how: the operation is verb-noun and transport-neutral (greet-visitor, not GET /greetings), and there is no frontmatter, because the BC name comes from the package. greet-visitor becomes the boundary's public method; each statement id (R1.1, R1.2) is stable and traces to at least one test that embeds it; the optional ## Entities section is simply omitted, because this BC owns no stateful domain nouns. Anything in the code without a spec counterpart is drift.

Every notation in SBCE is a stable, public standard: EARS for requirements, JavaDoc and package-info.java for placement, JEP 467 for the syntax, Mermaid for the generated BC map, and the decades-old Boundary-Control-Entity pattern itself. All of it is already in the LLM weights, so the skill never has to teach it: the complete workflow fits in roughly 4,000 tokens of SKILL.md. A self-invented spec DSL would burn thousands of extra tokens in every session.

Two modes drive the lifecycle:

/sbce new greetings         declare: author the spec, scaffold the layers
/sbce new "greet visitors"  declare from free text (github issue, Jira ticket): carves one or several BCs, new or existing
/sbce apply greetings       converge: close the spec-code gap, run tests until green

new loops clarifying questions until no boundary operation or EARS requirement has to be guessed. apply reads the gap in both directions: missing methods and tests are generated from the spec; undeclared methods or orphan trace ids are surfaced as drift, never silently absorbed. "Done" is a green run of the stack's own test loop, never the model's opinion.

/bce tells the code where to live; /sbce tells it what to promise.

jmarkdoc is a JavaDoc doclet that generates Markdown API documentation from Java sources and comments, ready for RAG pipelines, developer portals, and AI agents.

In Spec-Driven BCE: SBCE (say "space"), jmarkdoc generates the Markdown capability specs from package-info.java files, keeping the spec and the code in a single source. It requires Java 25, relies only on the jdk.javadoc and jdk.compiler modules, supports Markdown JavaDoc comments (JEP 467), adds nine contract tags for preconditions, postconditions, thread-safety, and idempotency, and links methods to EARS requirement IDs.

Subscribe to airhacks.fm podcast via: spotify| iTunes

SBCE is live at sbce.space (you say "space"). It is spec-driven development loop built on bce.design: the spec lives in your code, not in a markdown folder beside it.

Usually spec tools maintain the spec / Markdown files in a separate source tree. SBCE keeps it in the boundary package's own doc:

/// # Checkout
/// > Accept a cart and turn it into a confirmed, cancellable order.
///
/// ## Boundary
/// - `place-order`  — submit a cart for fulfilment
/// - `cancel-order` — withdraw an unfulfilled order
///
/// ## Requirements
/// ### R1: Place an order
/// - R1.1 — When a cart with at least one item is submitted, the BC shall create and confirm an order.
/// - R1.2 — If the cart is empty, then the BC shall reject the request.
package airhacks.checkout;

JEP 467 Markdown in /// comments. The same file is the source of truth and the published Javadoc. The BC name is the only identity: no frontmatter, no second file to sync.

Two modes. new writes the spec. apply converges the code until your stack's tests pass. "Done" is a green test run, not a checkbox.

No CLI, no dependencies, no installation. SBCE is a skill your agent reads, built on bce.design for the architecture and your stack skill for the code and tests.

ships with: airails.dev.

Subscribe to airhacks.fm podcast via: spotify| iTunes

Subscribe to airhacks.fm podcast via: spotify| iTunes

"Reflection and annotations: less needed at runtime as infrastructure becomes less dynamic, but annotations still valuable for type-safe metadata that LLMs can consume, AI token maxing and code quality: degraded LLM performance on chaotic codebases versus well-structured J2EE applications, building a career in Java with focus on continuous improvement and transferable fundamentals across languages, LightMetal: a thin Java 25 wrapper around llama.cpp using FFM bindings to run models locally with zero external dependencies and GPU-based inference, the ZSmith agent: an agentic stack with local models, BCE architecture, virtual-thread sub-agents, and a sandboxed file system implemented as Java tools, agent sandboxing via tiny Java tools with allow/deny/confirm permissions, AI Rails refactoring: extracting shared Java conventions into a reusable skill consumed by Java CLI, MicroProfile server, and BCE skills, standards and inference cost: Jakarta EE and MicroProfile are version-stable and well-known to LLMs, reducing token usage by an estimated 30-80 percent, API/SPI separation prevents hallucinations during code generation, a live demo generating a MicroProfile/Jakarta EE business component with Cloud Code, system tests, and a continuous testing loop, web frontends with web components and CSS instead of Angular or React, revisiting episode 47 from eight years prior: SSH database authentication, JSF, WAR modularization, identity preservation, JDBC revival, long-running transactions, and parallels to AI agents, workflow engines and agents: XState and AWS Step Functions specs as lightweight state-machine approaches"

GPU LLM inference on Apple Silicon, packaged as one Java 25 executable JAR, zero dependencies. lightmetal binds a Metal-enabled libllama.dylib through the Foreign Function & Memory API and runs Mistral- and Gemma-architecture GGUF models locally.

Build it with zb, point it at a GGUF, prompt it:

zb build
java --enable-native-access=ALL-UNNAMED -jar zbo/lightmetal.jar \
     -model ~/models/Mistral-Medium-3.5-128B-UD-Q5_K_XL-00001-of-00003.gguf \
     -prompt "What is Java?"

Add -serve and the same JAR exposes an Anthropic-compatible POST /v1/messages and an OpenAI-compatible POST /v1/chat/completions. xisting clients (zsmith, vibe) only need a base URL switch — the loaded GGUF wins, the model field is accepted and ignored.

Embedding into another Java app needs no compile-time dependency. lightmetal.jar registers a BinaryOperator via META-INF/services:

var generator = ServiceLoader.load(BinaryOperator.class).iterator().next();
var response  = generator.apply("/path/to/model.gguf", "What is Java?");

Just Java 25, llama.cpp, FFM, Metal — and a GGUF on disk.

1. In the Java 25 / JUnit 5 era, is reflection obsolete, or only for designing libraries/APIs rather than your own code? (Simon Richter)
2. Should I continue building my career in Java, or move toward AI given the current market and MNC layoffs? (Fanib)
3. jfrdoc on zSmith (Rıdvan)
4. airails.dev refactoring (java-conventions)
5. Time machine: 100 episodes back (47th episode):

   Database Authentication: SSH vs. username / password, Microservices with JSF frontend, How to modularize WARs, Dealing with denormalized databases, Java EE authentication (Active Directory), Identity preservation and audits in DB, JAX-RS authentication and principal delegation to EJB / CDI, Development in intranet environment, Reducing coupling between JavaScript components, Developers and operations -- their roles in the future, DeltaSpike project review, Impact of 3rd party libraries on build performance, Unpredictable, long running transactions, Propagating principals from JAX-RS to EJBs, Why it is a bad idea to resend a password on each request?, Dealing with security in credit card processing

Any questions left? Ask now: gist.github.com/AdamBien/33ece0569d45516d95163859aaaf8e1d and get the answers at the next airhacks.tv. Some questions are also answered with a short video: 60 seconds or less with Java

Ask questions during the show via twitter mentioning me: https://twitter.com/AdamBien (@AdamBien),using the hashtag: #airhacks or built-in chat at: airhacks.tv. You can join the Q&A session live each first Monday of month, 8 P.M at airhacks.tv

1. Devoxx Poland 2026: Token-Efficient, Well-Crafted Java #livecoding
   conference talk Devoxx Poland 2026 Krakow, Poland 18 June 2026
   https://devoxx.pl/talk?id=15451
2. VibeKode Conference: How To Write Great Code with LLMs #vibeless
   conference talk VibeKode Conference Munich, Germany 24 June 2026
   https://vibekode.it/speaker/adam-bien/
3. Spec-Driven Java Development at LLM Speed[online event]
   online workshop 2 July 2026
   https://workshops.adam-bien.com
4. LLM-Assisted Web Components: No Frameworks, No Dependencies. Just Web Standards[online event]
   online workshop 16 July 2026
   https://workshops.adam-bien.com
5. Entwickler Summit 2026: Fewer Tokens, Better Apps: With Standards and Java
   conference talk Entwickler Summit 2026 Berlin, Germany 17 September 2026
   https://entwickler.de/entwickler-summit/
6. airhacks.tv Questions and Answers #livestream[online event]
   live streaming show first monday of the month, 8pm CET
   https://www.meetup.com/airhacks/

The in-person edition of airhacks is back at MUC Airport: "Architect-Grade Java with LLMs" airhacks.university

Subscribe to airhacks.fm podcast via: spotify| iTunes

Java projects are still plagued by outdated habits: excessive layers, unnecessary abstractions, more YAML/XML than code, tests for obvious things like getters, "Stats and Ticket-d riven Development" and systems where everything is configurable but nothing varies, leaving business logic buried under unnecessary complexity. It’s time to focus on code again. This session will demonstrate how modern Java 25 and standards can help us to reduce unnecessary complexity. The focus is on shipping real business logic with greater simplicity and maintainability.

Two Time Machines: Revisiting the 45th Episode After 9 Years, Java 25 Scripting With Zero Dependencies, Java vs. Kotlin in 2025, Web Components and Standards Without Frameworks, Multiple Datasources With Different Permissions for AI Agents, Connection Pools and JPA Cache in Serverless Environments, Why XA Transactions Are a Bad Idea, JavaFX Revival With Official Oracle Support, EJBs vs. CDI Pooling and Jakarta EE 12 Native Pooling Plans, BCE Design and AI Rails for AI Agents, Jakarta Data and Delta Spike Evolution, Docker Swarm vs. Kubernetes vs. OpenShift for Java Developers, Server Push With WebSockets and SSE in the MCP Era, Role-Based Access With MicroProfile JWT and @RolesAllowed, Scala vs. Rust vs. Java 25 Analysis, Why LLMs Understand Java Better Than Other Languages, zsmith Agent Harness in Pure Java 25, LangChain4j With Quarkus and Native Compilation, Zero-Dependency JUnit Runner Under 1 Second, JAX Frankfurt, AirHacks Munich Airport Workshop December 2026, Summer AirHacks Online, JCon Cologne, Devoxx Greece, JavaOne, Devoxx London, Geekon Krakow

Subscribe to airhacks.fm podcast via: spotify| iTunes

1. Opinion about the Rust programming language (asked by @Pscheidl on LinkedIn)
2. Time machine: the 46th airhacks.tv from January 2018

   Application metrics and monitoring in Java EE, ServerSockets vs higher-level alternatives, SSE, WebSockets, DAO anti-patterns, JPA historisation, SLSB tuning, Docker, Kubernetes, OpenShift and more

3. Time machine: the 45th airhacks.tv from December 2017

   Kotlin in Java EE, JasperReport alternatives, custom REST headers, two persistence units in CDI, JPA internals, JWT authentication, Web Components, offline-first PWAs and more

4. airhacks workshops return to Munich Airport
5. conference report

Any questions left? Ask now: gist.github.com/AdamBien/4c2a1c099321bac29ecb6ebc262ae196 and get the answers at the next airhacks.tv. Some questions are also answered with a short video: 60 seconds or less with Java

LLMs know Java's normative APIs, specifications, and implementations. That changes how you write code. Code structure, naming conventions, and adherence to standards directly affect what LLMs generate. Well-structured, zero-dependency Java produces more consistent, more predictable LLM output and scales to big projects. Starting from a blank project, each step demonstrates how code organization, standard API usage, and consistent patterns influence LLM-assisted development. The same principles that make code readable for developers also make it processable for LLMs. No slides. No theory. Just code. Questions welcome at any time.