adam bien's blog

"Spring Gateway vs nginx vs cloud API gateways: nginx and HAProxy as proxies, cloud gateways transforming HTTP into CloudEvents, authentication, JWTs and content-based routing, BCE as the show's most used term, BCE namespaces from domain ideas, BCE applied to static pages where folders are menu items and cards are feature components without JavaScript, HTMLDB released today: a database built on HTML as valid XML in ~550 lines of Java 25 with no external libraries, tables and rows via CLI, data viewed in the browser as semantic HTML, HTMLDB motivated by agent memory since agents understand XML well, watching agent memory live in a zero-dependency web server, Agent Smith migrated to HTMLDB, symbolic links as convention over configuration for multiple schemas, HTMLDB in the Z family, not an Oracle or Postgres replacement, floci.io: Quarkus-based emulation of Lambda, DynamoDB, Neptune, CodeBuild and ElastiCache with ~20k GitHub stars in 5 months, always reviewing LLM-generated code to refine skills and AI rails, why web frameworks may disappear: LLMs understand the web platform and do not need React, Angular or Svelte developer experience, agents generating perfect web component code without frameworks, an airhacks.live web components workshop deriving a JTree-like structure from design.md, Jakarta EE Core covering ~80% with CDI, bean validation and JAX-RS, exclusive grounding against MicroProfile so code runs on Quarkus without the agent knowing Quarkus, AI rails updates: AWS CDK skill mapping BCE to CDK constructs, static web and vanilla JavaScript sprinkles, a vanilla Java agent on AWS agent core runtime in ~40 lines with 60ms startup and 5KB, ZDMD turning design.md into design tokens for framework-free web components, ported from TypeScript with shorter Java code, time machine to episode 49 from April 2018: WebStart, JavaFX revival since LLMs understand JavaFX well, no frameworks over JSF-to-Angular, JWT system tests with real test tokens, thin WARs, EclipseLink on Payara over shipping Hibernate, query caching from EHCache to Infinispan, a YouTube course on BCE, and a workshop at Munich airport in December"

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

The most asked BCE question is not what the layers mean, but which dependencies are allowed. Inside a business component the dependencies point downwards.

1. boundary to control, control to entity. The boundary offers coarse grained, easy to use methods, the control finer grained, reusable ones, the entity holds the data, as a smart domain object or an anemic record.
2. boundary to entity, directly. A control is only needed for the more complex use cases. For the simple ones, skipping the control is the default.
3. Never entity to control, never entity to boundary. An entity that needs something from above emits an event instead. Any layer of any component can process it, and the entity stays unaware of the receiver.

Between business components three cases matter:

1. boundary to boundary: avoid it. A boundary is designed for external actors, not for other business components. Acceptable at the very beginning, later a control takes over.
2. control to control: allowed, and direct. No interfaces in between required. In Quarkus and MicroProfile applications the control is injected.
3. entity to entity: allowed. Relations between persistent objects would be impossible without it.

Then count the links. A component that communicates less with itself than with its neighbors was cut in the wrong place.

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

Episode 6 of the free Screaming Architecture with BCE series applies the rules to two components of the example project:

The full course is available at airhacks.io.

1. BCE/ECB (Boundary-Control-Entity) for ...with static, semantic pages
2. floci.io AWS cloud emulator
3. "the role of the platform in LLM-assisted development" by Ondro at LinkedIn
4. announcement: htmldb
5. Free course: BCE: The Screaming Architecture For Humans and LLMs 👉 airhacks.io
6. New AWS-CDK and web-platform skills 👉 airails.dev
7. One seat left 👉 airhacks.university
8. unscripted: plain HTML showcase 👉 unscripted
9. Time machine: 100 episodes back (49th episode):

   Swing without WebStart, Preventing Web Sessions, Performance Testing with JWT, JPA query result caching, SAML Java Frameworks, JavaScript databinding with WebSockets, Asynchronous Java EE, Using embedded container testing with container resources, When Numbers Are More Important Than Quality

Any questions left? Ask now: gist.github.com/AdamBien/e58d00a2cb06d6ca5e6039bf48f3b1db 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

Subscribe to airhacks.fm podcast via: spotify| iTunes

Web frameworks solve human problems. Readable abstractions, conventions a team can share, a line on a CV that outlasts the project. All of it is about people, and all of it assumes a human types the code and another human reads it.

An agent has no career to build, and gets nothing from an abstraction whose purpose is to be read. Consistency across a codebase comes from the skill the agent follows, not from the framework.

React, Angular, Vue and Svelte all render through the same DOM. The abstraction leaks, the way all non-trivial abstractions leak, so debugging any of them ends in the platform underneath. The platform knowledge is required either way; only the framework is optional.

An agent writes against the web platform instead. A list component is about twenty lines, imports and registration included. The application ships without a package.json, a bundler or a transpiler: an import map resolves the imports, so what the browser loads is what is on disk.

There is also no install step, and no lockfile, transitive graph or postinstall script to audit, which matters more with agents than without: an agent adds packages on its own, and checking what it pulled in is the review that stops happening first.

What frameworks were invented for keeps arriving as standards:

• Custom Elements and Shadow DOM for the component model;
• form-associated custom elements with ElementInternals for validation and form participation;
• ES modules and import maps for dependency resolution without a build step;
• structuredClone() for immutable state updates, in place of Immer;
• Navigation API and URLPattern for routing;
• <dialog>, popover and View Transitions for overlays and animated view changes;
• CSS nesting, :has(), container queries and cascade layers for what used to need a preprocessor.

The gap keeps closing, and it closes faster than it used to. Ideas that start in frameworks now reach the specifications within a release cycle or two, and the Interop project gets them into all three engines in months instead of years, tracked by Baseline. Custom elements already carry the interfaces of GitHub, YouTube, Photoshop on the web, SAP UI5 and Adobe Spectrum. React 19 added proper custom element support, so the frameworks are moving toward the platform rather than away from it.

What the standards do not cover is small enough to stop calling a framework. Templating is lit-html at a few KB. State management is a hundred lines of unidirectional store code. Neither locks the application in.

Widget libraries are needed either way. React and Angular do not ship a data grid or a rich text editor, so both stacks add one, and the interface decides which one an agent can drive. A custom element exposes attributes, properties, events and slots, and that interface is specified, so an agent knows the calling convention for an element it never saw during training. A React component exposes arbitrary props that change between major versions, and the agent needs correctly versioned documentation to drive it.

Platform code outlives the conventions that produced it. Revise the conventions in a skill, and the code generated last year still runs. Move from one framework major version to the next, and the code itself has to move.

Agents Love The Web Platform's Backward Compatibility covers why the specifications are also the better grounding for an agent.

Without further instructions, an agent writes web code from everything it saw during training: tutorials, framework docs, Stack Overflow answers, blog posts from 2014. The output mixes all of it. Restricting the grounding to normative Web Platform specifications (HTML, DOM, CSS, ECMAScript, ARIA) removes the mix.

The Web Platform is unusual as a corpus, because it hardly contradicts itself. A DOM example from 2012 and a DOM example from today still describe the same platform, so old and new material reinforce each other. Documentation for two major versions of the same framework contradicts itself instead, and an agent that read both has no way to tell which half applies.

Public specifications and multiple independent implementations help as well. Neither would be worth much without the strict backward compatibility: a public specification that gets replaced every few years produces the same contradictions as a framework.

Grounded against the specifications, the usual mistakes get rare:

• presenting Chrome behavior as a standard;
• confusing React or Angular conventions with browser requirements;
• inventing APIs that only exist in a framework;
• declaring an older API invalid because a newer one exists;
• treating browser error recovery as authoring advice.

The generated code uses the platform directly: semantic HTML, DOM APIs, Custom Elements, form-associated elements, standard events and CSS. Fewer dependencies and less ceremony. The code also survives longer, because a build tool changing its internals does not force a rewrite.

One catch: backward compatibility also preserves what the platform got wrong. Browsers keep supporting obsolete markup and historical quirks, because existing sites depend on them. Browser support is not an authoring recommendation. An agent grounded in the specifications has to know the difference, and it has to check the browser versions the project supports, not only the specification text.

The web platform section at airails.dev ships the skills that encode this: web-conventions, web-static, web-components, and web-latest.

An agent running on the AWS Bedrock AgentCore Runtime has to implement a minimal HTTP contract: POST /invocations answers requests, GET /ping reports health, both on port 8080. The JDK's built-in jdk.httpserver is sufficient.

The AWS Java Agent Core Runtime CDK quickstarter project implements the contract in vanilla Java 25 with zero external dependencies. The complete contract is implemented in a single interface:

public interface AgentRuntime {

    int AGENT_CORE_PORT = 8080;

    static String invokeAgent(String payload) {
        IO.println("invocation: " + payload);
        return """
            {"time":"%s"}""".formatted(Instant.now());
    }

    static String checkHealth() {
        return """
            {"status":"Healthy"}""";
    }

    static void serve() {
        HttpEndpoint.start(AGENT_CORE_PORT, AgentRuntime::invokeAgent, AgentRuntime::checkHealth);
    }
}

A second interface, HttpEndpoint, wires both routes on the JDK's HttpServer. Every import comes from the JDK. The sample agent answers each invocation with the current UTC time as JSON. Packaged with zb, the complete agent.jar is 5,440 bytes, and the endpoints are serving about 60 ms after JVM start (OpenJDK 25, Apple Silicon).

Deployment is also Java. The project ships with an AWS CDK app (the cdk module) that builds the agent's four-line Dockerfile (Amazon Corretto 25, the jar, an ENTRYPOINT) into an ARM64 container image asset and provisions the AgentCore runtime from it. The image is built and pushed during cdk deploy. The system tests invoke the deployed agent with the AWS SDK's BedrockAgentCoreClient.

The project was developed with /sbce, the spec-driven BCE workflow: the AgentCore contract is declared as EARS requirements (Easy Approach to Requirements Syntax) in the business component's package-info.java, and @Requirement annotations (trimmed from the listing above) trace the boundary methods back to the spec.

The project is part of constructions.cloud, a collection of Java CDK templates and quickstarters.

Subscribe to airhacks.fm podcast via: spotify| iTunes

The /aws-cdk skill generates and reviews Java AWS CDK v2 projects organized as BCE (Boundary-Control-Entity) business components. Infrastructure code follows the same structure as a business application instead of accumulating as a flat list of resources. It ships as an AIrails skill: /aws-cdk.

The main tenet is the separation of stacks from constructs. A stack decides which resources deploy together and lives in boundary. A construct defines how a capability is configured, is reusable across stacks, and lives in control as a stateless factory, preferably an interface with static methods. Immutable data that describes infrastructure without creating it, like build specs and typed value objects, lives in entity.

The remaining ideas follow from that split:

1. Packages are business components named after the AWS capability they provision: s3, cloudfront, cognito, route53, stepfunctions. A component spanning multiple services is named after its domain responsibility.
2. A single CDKApp entry point loads configuration as typed Java records, applies tags, wires stacks in dependency order, and calls app.synth(). Stacks never read CDK context or environment variables; they receive typed records.
3. Regions are pinned in a central Stacks interface exposing StackProps constants. Account and region are never inlined in stack classes.
4. Stacks stay independent. A producing stack passes resource interfaces like IBucket or ITable to consumers, never stack instances.
5. For IAM, grant* methods on the target construct generate least-privilege policies. Explicit PolicyStatements are the fallback.
6. Synthesis stays deterministic and side-effect free: no SDK calls, no timestamps, no randomness during construction. Tests assert on the synthesized CloudFormation template instead of snapshots.

The skill composes with /bce and /java-conventions and ships with a domain-neutral project blueprint. It is also compatible with /sbce, the spec-driven BCE workflow: a capability spec describes one business component, and the code is iterated until it matches the spec. A compilable starter is available at AdamBien/aws-cdk-plain, and constructions.cloud collects example constructs and CDK applications.

A business component is a package named after a single responsibility, and the structure of a system is the sum of these components. The hard part is finding the names. Here is the simplest approach I know, three steps.

1. Say it. Describe what the system does in one sentence, in one breath.
2. Name it. Underline the essential verbs and nouns. Those are your component candidates, and verbs become nouns.
3. Test it. Drop every name that would fit another project. A name that transplants into any system says nothing about this one.

The method reverse-engineers reality. Take zb, a zero dependency builder:

"It discovers the Java sources, compiles them, packs an
 executable JAR, and runs the test hook after the build."

Verbs become nouns: discovers becomes discovery, compiles becomes compiler, packs becomes packer, and hook is already a noun. Open zb and you find exactly those packages: discovery, compiler, packer, hook. That sentence took about ten iterations. packer started as "jar creator", discovery started as "source", and hook did not exist yet.

An online shop: "customers browse the catalog, put products into a cart, place orders, and pay." That gives catalog, cart, orders, payments. Browse collapses into catalog, products are entities inside it. Customers is borderline: a component only when the system manages them, otherwise an entity inside orders.

Say it. Name it. Test it.

Part of the free Screaming Architecture with BCE course.

The airails.dev skills ship as a single "Any agent" bundle: a zip that contains a skills/ folder. Installing it is two steps.

1. Download the bundle.
2. Unzip it into your agent's config directory.

curl -LO https://github.com/AdamBien/airails/releases/download/skills/airails-skills.zip

unzip airails-skills.zip -d ~/.claude     # Claude Code
unzip airails-skills.zip -d ~/.copilot    # GitHub Copilot CLI
unzip airails-skills.zip -d ~/.agents     # Codex
unzip airails-skills.zip -d ~/.vibe       # Vibe

The zip carries a skills/ folder, so the parent directory is the only thing that changes. Unzip into ~/.claude and the skills land in ~/.claude/skills. The same bundle works for every agent, including Claude Code, GitHub Copilot CLI, Codex, and Vibe.

A business component (BC) is a package named after a single responsibility. Inside are up to to three sub-packages, always the same three names:

• boundary: the public API of the component. Coarse-grained, simple, opinionated.
• control: fine-grained, generic functions and methods.
• entity: the data.

Boundary, control, entity is the maximum, not a requirement. A component takes only the layers its responsibility needs. From zsmith, an agent harness:

• skills has all three. A public API, enough logic for a control, and its own data.
• memory is boundary and entity, no control. The logic is simple enough to sit in the boundary.
• claude, configuration, and llm are control only. claude is the class that talks to Anthropic, configuration reads properties. No exposed API, no data of their own.

The tools component shows all three from the implementation side:

zsmith.tools
├── boundary   execute a tool, check whether it runs in parallel
├── control    the tool implementations, like the read-file tool
└── entity     the annotations, the tool result, the tool use

The three layers have been stable since 1992. They never changed, there were no version updates, and they are well described across books and articles. That stability is also why LLMs work well with them.

A business component is a top-level package named after a single responsibility or feature, not after a technology. discovery, compiler, checkout, invoicing: reading the package names tells you what the system does. That is Screaming Architecture. The structure of a system is the sum of its business components.

Business components are not designed up front. They are created on the go: every new requirement becomes a new component.

zb, a zero dependency builder, grew exactly this way. The first requirement was finding the code. Sources can sit in src or src/main/java, so convention over configuration became a responsibility of its own: discovery.

Found code has to be compiled, then packaged into an executable JAR, then verified. Each need became its own component:

discovery, compiler, packer, hook

The packer creates the JAR. The first name was jar creator, too long. jc was too cryptic. A business component name is descriptive but short: no compound names, no abbreviations. The hook runs after a successful build, so zunit can execute the tests.

discovery, compiler, packer, and hook are domain components. They are first class: reading them reveals what zb does and how it is structured.

Subscribe to airhacks.fm podcast via: spotify| iTunes

I noticed that coding agents reach for Quarkus developer mode by default. They start quarkus:dev and keep it running.

An agent edits, then it has to observe the result before deciding the next move: compile error, test verdict, endpoint response.

• Live reload on the next request. The agent edits a resource. The system tests, running on a second Quarkus in Dev Mode, hit the live-reloaded endpoint over HTTP and report back. No rebuild, no restart on either side.
• Continuous Testing. Tests re-run on the affected code automatically. The agent gets red or green without asking for it.

The math is simple. A thirty-second restart is an annoyance for a developer who hits it five times an hour. For an agent iterating two hundred times, it is the entire budget. Cut the loop to a second and the agent spends its time changing code instead of waiting for the JVM.

The continuous-testing skill at airails.dev encodes this loop: after every change it builds, starts the server, and runs the unit, integration and system tests.

Fast iteration was always the point of Dev Mode. Agents just run into the payoff far more often than people do.

For java-cli applications there is no Dev Mode, but zb builds them so fast (< 1s) the loop stays just as tight. Another excuse to use it. 😀

The structure of a system should reveal its purpose. Robert C. Martin coined the term Screaming Architecture for this idea roughly 15 years ago. In the first episode of my BCE screencast course, I put it to the test: can you tell what a project does by reading its top-level package names? Production sources only, no tests.

zb:

compiler, hook, packer

zb stands for zero dependency builder. It compiles Java code, creates executable JARs, and runs unit tests as a hook. The packages describe exactly that.

lightmetal:

prompting, sampling, tokenization, tools

With basic LLM terminology, the packages point to local inference. lightmetal runs LLMs on the Apple Metal API via llama.cpp.

zsmith:

agent, memory, skills, tools, tui

zsmith is an agent harness. The structure explains itself.

All three projects organize code by domain responsibility, the idea behind BCE business components. A new tool goes into tools, agent persistence lives in memory, and code is found where expected. This applies to LLMs as well: an agent navigating packages named after responsibilities locates code without scanning the whole project.

Subscribe to airhacks.fm podcast via: spotify| iTunes

zbaseline is a zero-dependency Java 25 CLI that fetches the complete web platform feature set (currently ~1,171 features) from the webstatus.dev API and renders it into a single markdown snapshot with the Google Baseline status of every CSS, HTML and JavaScript feature.

The snapshot, written to stdout, is one markdown table sorted by feature id: Feature id, Name, Status (widely / newly / limited), and the dates a feature became newly or widely available. The header carries the snapshot date, the data source URL, and the rule for misses: a feature not in the snapshot is treated as uncertain.

The markdown format is intentional. The airails.dev web-conventions skill bundles such a snapshot for HTML and CSS generation.

zbaseline has zero external dependencies: JSON parsing relies on copied org.json sources, the build is plain zb, and the project was generated from the java-cli-app template following sbce.space principles.

Clone, run, and your agents stop guessing: github.com/adamBien/zbaseline

zws is a development web server in a single Java 25 source file on top of the built-in jdk.httpserver. It serves static files from a directory, sends no-cache headers, and opens the browser. Java 25 is the only prerequisite:

curl -O https://raw.githubusercontent.com/AdamBien/zws/main/zws
chmod +x zws
./zws [root-directory] --live --single

Without root-directory, zws serves the current directory.

With --live, zws watches the site root recursively with WatchService and injects a single line into every served HTML page:

The /reload endpoint speaks server-sent events: the connection stays open on a virtual thread, and every file change pushes an event that reloads the page. Save a file, the browser refreshes. Pure web standards, no WebSockets, no client library, no build step.

With --single, zws serves Single Page Applications with client-side routing: GET requests for paths that do not exist on disk and have no file extension (routes like /add) are answered with index.html, so deep links and reloads reach the application. Requests with a file extension still return 404, keeping typos visible.

The flags are independent and compose: with both active, SPA-fallback responses reload as well.

The airails.dev skills bundle zws as the development server: the generic web-conventions skill ships a copy, web-static serves generated sites with it for authoring (--live) and for the verification loop, and web-components relies on --single for SPA routing during development.

zws is part of z, a collection of zero-dependency Java projects.

DESIGN.md stores a design system as YAML token blocks inside a markdown file. Agents and developers can read, review, and diff it like any other document.

zdmd is a Java port of the reference TypeScript CLI: a zero-dependency Java 25 application packaged as a single executable JAR. It lints, diffs, and exports DESIGN.md token files. One JAR replaces node_modules for anyone working with design systems on the JVM:

zdmd                    # convert DESIGN.md into all formats, write tokens.css + tokens.json
zdmd lint  [--format json|md]
zdmd diff   [--format json|md]
zdmd export  --format  [--prefix ]

The bare launch is built for agents: it reads DESIGN.md from the current directory, writes every supported format (tokens.css and tokens.json), and prints the written filenames. No flags to remember.

Only web-standard export formats are supported: CSS custom properties and W3C Design Tokens (DTCG) JSON. Tailwind is intentionally out of scope. lint exits with 1 on errors and diff exits with 1 on regressions, so both plug directly into CI pipelines.

Installation requires nothing but Java 25+:

curl -fLO https://raw.githubusercontent.com/AdamBien/zdmd/main/zdinstall
chmod +x zdinstall
./zdinstall

zdmd was built with the spec-driven BCE workflow (sbce.space): each capability lives in its own business component, and the spec in package-info.java is the boundary contract. It is part of z, a collection of zero-dependency Java projects.

The bce.design quickstarter lost its entire build system: Node.js, npm, rollup, lockfiles. 777 lines deleted.

The toolchain existed for one reason: Redux Toolkit. It ships with transitive dependencies (immer, redux, reselect), so a bundler had to flatten it into a browser-loadable module.

Then Redux Toolkit got replaced with reduction.js, a 70-line, standards-based implementation of the used API, relying on structuredClone instead of Immer.

The only dependency left: lit-html. And lit-html is a single, self-contained, dependency-free ES module. The bundler's output was byte-for-byte its input. The whole machinery reduced to:

curl -fsSL https://registry.npmjs.org/lit-html/-/lit-html-3.3.3.tgz \
    | tar -xzO package/lit-html.js > app/src/libs/lit-html.js

Straight from the npm registry: no CDN, no middleman, the exact bytes npm install would deliver.

The vendored module is mapped with a standard import map in index.html:

<script type="importmap">
{
  "imports": {
    "lit-html": "/libs/lit-html.js",
    "@reduxjs/toolkit": "/reduction.js"
  }
}
</script>

Routing is implemented with the Navigation API and URLPattern, so there is no router dependency either.

Remove a dependency, and the tooling it dragged in disappears with it. Web standards are the best dependency: nothing to install, nothing to build, nothing to migrate.

A Package per Feature and Semantics over Bureaucracy showed BCE in a Java CLI application and claimed the convention is cross-technology. Proof: an events application built with web components and lit-html on plain web standards. No framework, no build; the store is reduction.js, 77 lines on structuredClone, and lit-html is the only runtime dependency. The src directory is a list of BCs:

src
├── creation
├── filter
├── inputs
├── localstorage
├── overview
├── preview
└── status

Inside each BC, the fixed names return. The filter component carries all three layers:

filter
├── boundary
│   └── Filter.js
├── control
│   └── FilterControl.js
└── entity
    └── FilterReducer.js

The mapping to the browser is direct. The boundary is the custom element: it renders the lit-html view and receives the DOM events, because in a frontend the external actor is the user. The control is a function that creates and dispatches an action. The entity is the state slice with its reducer: state has a home, here it is literally the store.

The dependency direction survives the technology switch: boundary calls control, control updates entity through the store, and the store re-renders the boundary. And layers stay optional: localstorage is control-only, preview is boundary-only.

A Java developer navigates this frontend without learning a new layout, and a frontend developer navigates lightmetal the same way. That is what fixed names buy.

Subscribe to airhacks.fm podcast via: spotify| iTunes

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.