The structure of a project (6): the kitchen that's set up the night before
By Dorian Chávez · co-founder and Chief Executive Officer of Hábil ·
The same orders API, from Spring Boot to Quarkus: what changes in each package, measured startup time and memory, and what a startup number doesn't tell you.
The structure of a project · installment 6 of 7 · Quarkus
Scenario: the characters and the story are made up. The technical data and the quotes carry their source at the end.
In 1 minute
- It's the same restaurant as in installment 5:
apiis the waiter,servicethe cook,repositorythe pantry. What changes is the kitchen: the tool each role uses. - Quarkus's central idea is to do «at build-time what traditional frameworks do at runtime» [1]. The kitchen is set up the night before, and that's why it opens fast.
- Measured on the template, up to the first order created: Spring Boot, 2.2 s and 437 MiB; Quarkus on the JVM (the virtual machine that runs Java), 1.2 s and 270 MiB; Quarkus compiled to native (an executable that doesn't need the JVM), 46 ms and 60 MiB.
- Opening fast isn't cooking fast. In the official guide's benchmark, native serves ~59% fewer requests per second than the JVM [2]. You choose native for startup and memory, with the measurement in hand.
- The arrows still point inward, and the same architecture test turns red if someone flips them. There's one mistake no test in the template sees: you find it with a
grep. - For Monday: search for
extends PanacheEntityin your project. Each result is a file card that also acts as the pantry.
In this article
- What happened on Monday at 9:12?
- What changes and what doesn't?
- What does "the night before" mean?
- What changes in each package?
- How fast does it open?
- Do the arrows still point inward?
- What are five frequent mistakes?
- Exercise: can you hide the file card in the receipt?
- Key takeaways
- What's next?
- The template and the course
- What does Hábil do?
- References
What happened on Monday at 9:12?
Iván watched an API start in 46 milliseconds and wanted to move everything to native. Lucía asked him two questions.
Monday, 9:05. Third floor.
The new orders API had the usual folders: api, facade, service. Iván looked for the waiter and found PedidoResource. There was no @RestController, no class with a main, and the pantry wasn't where he expected it: it lived inside model/.
He built it and started it. The log said:
pedidos 0.1.0 on JVM (powered by Quarkus 3.40.1.2) started in 1.540s.
Listening on: http://0.0.0.0:8080. Management interface listening on http://0.0.0.0:9000.Two ports. He wrote the question down and kept going.
Monday, 9:12.
Lucía stopped by his desk, coffee in hand.
"Now run it like this."
She gave him a command that took more than a minute to finish. It left a 78 MiB file in target/. Iván ran it, sent an order and the order was created. From the moment he launched the process to the first response, 46 milliseconds went by.
"Forty-six? The Spring one takes two seconds. We have to move everything to this."
"How long did it take to compile?"
"A minute and something."
"And how many orders per second does it handle?"
Iván didn't know. Nobody had measured it.
"Tomorrow we're having breakfast at the diner," Lucía said. "Get there early."
Tuesday, 7:30. The diner across the street.
The kitchen wasn't open yet. The cook had already chopped the onion, made the salsas and put the beans on. At one o'clock she would only be putting plates together.
"The kitchen is set up the night before," Lucía said. "That's why it opens fast. But opening fast isn't cooking fast."
What changes and what doesn't?
The restaurant doesn't change: the tools of each role do.
This installment's template, estructura-quarkus, is the same API as in installment 5: it takes and looks up a store's orders, asks the inventory supplier how many pieces there are and at what price, and stores them in H2, an in-memory database. The root package is the same, mx.habil.pedidos, and so are the roles. The cook's rules, the exact measures (Dinero, Correo) and the one who writes up the clean copy came over almost unchanged.
| Role | In Spring Boot (installment 5) | In Quarkus (this installment) |
|---|---|---|
The waiter, api | PedidoController, ResponseEntity | PedidoResource, RestResponse |
| The pantry | repository/ with Spring Data: an interface | model/repository/ with Panache: a class |
The supplier, client | RestClient; timeout and retry in the configuration | REST Client; @Timeout and @Retry on the interface itself |
The complaints book, exception | @RestControllerAdvice | An ExceptionMapper and the quarkus-http-problem extension |
| Health | :8080/actuator/health | :9000/q/health, on another port |
| The restaurant's fittings | application.yml | application.yaml |
| Who starts everything | PedidosApplication, with its main | Nobody: Quarkus generates it |
estructura-quarkus/
├── pom.xml · mvnw · .mvn/ bibliotecas, construcción y el Maven del proyecto
├── Dockerfile · docs/ARCHITECTURE.md
├── herramientas/
│ ├── probar-frontera.sh la frontera que sabe fallar
│ └── medir-arranque.py el arranque y la memoria
├── src/main/java/mx/habil/pedidos/
│ ├── api/ el mesero
│ ├── facade/ el jefe de cocina
│ ├── service/ el cocinero
│ ├── client/ el proveedor de afuera
│ ├── model/
│ │ ├── request/ la comanda
│ │ ├── response/ el ticket
│ │ ├── entity/ la ficha del archivo
│ │ ├── vo/ las medidas exactas
│ │ └── repository/ la despensa
│ ├── mapper/ config/ exception/ observability/ utils/
├── src/main/resources/application.yaml
└── src/test/java/mx/habil/pedidos/ el mismo árbolWhy did the pantry move to model/repository/? Because of a house decision: Hábil's standard for Quarkus puts the Panache repository next to the file cards it stores. The arrows don't change: only the cook reaches the pantry.
What does "the night before" mean?
That the work of preparing the kitchen is done when building, not when opening.
When a Java application starts, someone has to read the configuration, find the classes that are components, decide who receives whom and wire all of that up in memory. In a traditional framework that happens every time the application opens. Quarkus says it in one sentence: its central idea is to do «at build-time what traditional frameworks do at runtime: configuration parsing, classpath scanning, feature toggle based on classloading, and so on» [1].
At the diner, the cook chops the onion before opening. Quarkus reviews the classes when you build, and at startup it already knows who the waiter is and whom it calls.
That review is done by ArC, its way of wiring components. It follows the Jakarta CDI specification («based on the Jakarta Contexts and Dependency Injection 4.1 specification»), but not all of it: «It implements the CDI Lite specification, with selected improvements on top, and passes the CDI Lite TCK. It does not implement CDI Full.» [10]. CDI is Java's standard for what Spring's container did in installment 5: you declare "the waiter needs a head chef" and someone hands it one.
In the code you barely notice. The waiter receives its helpers through the constructor, just like in installment 5:
public PedidoResource(PedidoFacade facade, PedidoService service, PedidoMapper mapper) {What changes is when it's resolved. That's why Quarkus doesn't need a class with a main: it generates one at build time. The entry point is target/quarkus-app/quarkus-run.jar, inside a folder, and not a single .jar.
And there's something else you can do with a kitchen set up the night before: compile all of it, ahead of time, into an operating system executable. That's native: a program that runs without the Java virtual machine. It's what Lucía gave Iván.
What changes in each package?
The waiter, the pantry, the supplier, the complaints book and health use other tools. Each one keeps its "never".
api, the waiter
@Path("/v1/pedidos")
public class PedidoResource {
@POST
@RunOnVirtualThread
public RestResponse<PedidoResponse> crear(@Valid @NotNull CrearPedidoRequest comanda) {
PedidoResponse creado = facade.crear(comanda);
return RestResponse.ResponseBuilder.<PedidoResponse>create(RestResponse.Status.CREATED)
.header(HttpHeaders.LOCATION, "/v1/pedidos/" + creado.id())
.entity(creado)
.build();
}Quarkus REST is «a new Jakarta REST (formerly known as JAX-RS) implementation» [4]: @Path, @POST and @GET come from that standard, not from Quarkus. In Jakarta REST, the class that serves a route is called a resource. @RunOnVirtualThread asks for a virtual thread for each request, as in installment 5, because the waiter waits on the supplier; the guide sets the limit: «Virtual threads are useful for I/O-bound workloads only» [18].
One measured difference: if you request /v1/pedidos/hola, which isn't an identifier, installment 5 answered 400 and this one answers 404. It isn't an oversight. The Jakarta REST specification requires it: if a path parameter can't be converted, «an implementation MUST generate an instance of NotFoundException (404 status)» [14]. For Jakarta REST, that route doesn't exist.
Never goes here: a business rule. Same as in installment 5.
model/repository, the pantry
@ApplicationScoped
public class PedidoRepository implements PanacheRepositoryBase<PedidoEntity, UUID> {
}Panache is Quarkus's layer for storing with Hibernate. It offers two styles. In the first, the file card stores itself: the entity inherits from PanacheEntity and brings its own queries, like Person.findByName(…). That's the active record pattern. The second is this template's: «the more classical repository pattern via PanacheRepository» [5]. The file card is a normal JPA entity, and the pantry is another class. PanacheRepositoryBase is used because the identifier is a UUID; for that the guide says to «extend PanacheRepositoryBase instead of PanacheRepository and specify your ID type» [5].
Why a separate pantry? Because of installment 5's third rule: what comes in, what is stored and what goes out are different things. If the file card also stores and queries, it brings along methods like persist(): anyone holding a file card could try to write to the database, even the waiter, and inside a transaction they'd succeed [5]. With a separate pantry, only the cook reaches it, and the architecture test watches over that.
Never goes here: a decision. And never: extends PanacheEntity on the file card. It's the first mistake on the list, and the quietest.
client, the outside supplier
@RegisterRestClient(configKey = "inventario")
@Path("/productos")
public interface InventarioApi {
@GET
@Path("/{sku}.json")
@Timeout(2000)
@Retry(maxRetries = 2, delay = 200, jitter = 50,
retryOn = {TimeoutException.class, ProcessingException.class})
@ExponentialBackoff(factor = 2)
InventarioClient.Producto producto(@PathParam("sku") String sku);
}In installment 5, the client was a class that made HTTP calls. Here it's an interface: you declare the route and Quarkus writes the call [6]. The supplier's address goes in application.yaml, under the inventario key.
The two usual precautions are on the interface itself, with MicroProfile Fault Tolerance annotations. The extension offers several, such as @CircuitBreaker [7]; this interface uses three: @Timeout, @Retry and @ExponentialBackoff. Two seconds of timeout per attempt and up to two retries: three attempts in total. It retries only on a timeout or a network failure. A "doesn't exist" from the supplier is an answer and isn't repeated. Measured with the supplier turned off: the API answers 503, with "error_code":"PROVEEDOR_NO_DISPONIBLE", in half a second (0.534s), after the three attempts.
Never goes here: an order rule. Nor a call without a timeout.
exception, the complaints book
@Provider
public class PedidosExceptionMapper extends ExceptionMapperBase<PedidosException>
implements ExceptionMapper<PedidosException> {
@Override
protected HttpProblem toProblem(PedidosException queja) {
return queja.codigo().aProblema(queja.getMessage());
}
}The shape of the response is the same as in installment 5: Problem Details, RFC 9457 [16]. It comes from a community extension, quarkus-http-problem: «Unified error responses for Quarkus REST APIs via Problem Details for HTTP APIs (RFC9457 & RFC7807)» [15]. An ExceptionMapper is the Jakarta REST piece that turns an exception into a response [4]. Measured, asking for four mugs when there are three:
{"type":"https://pedidos.example/errors/sin_existencias","status":409,
"title":"No hay existencias suficientes","detail":"De TAZA-01 se pidieron 4 y hay 3",
"instance":"/v1/pedidos","error_code":"SIN_EXISTENCIAS",
"request_id":"e8cc3ea5-44a3-47ef-8e39-275e4e584861"}The request_id is the same as in the X-Request-ID header and in the log: with it you find the visit. Never goes here: an error format of your own.
Health, on another port
Quarkus publishes health at /q/health/live and /q/health/ready [8]. The template sends it, along with the metrics [20], to the management interface: with quarkus.management.enabled=true, those routes come out on port 9000 and not on the API's [9].
curl -s localhost:9000/q/health/readyIt answers (it comes out on several lines; here it's joined):
{"status":"UP","checks":[{"name":"Database connections health check","status":"UP","data":{"<default>":"UP"}}]}Measured: curl -s localhost:8080/q/health answers 404. What's inside doesn't go out through the customers' door. It's like the diner's kitchen: the inspector comes in through the service door, not through the dining room.
config, the restaurant's fittings
application.yaml with the quarkus-config-yaml extension [11]. It carries a warning on its first line, because it happened to us: a misspelled key doesn't stop Quarkus. We'll see it in mistake 4.
How fast does it open?
Measured: native creates its first order in 46 milliseconds and weighs 60 MiB. Building it took 80 seconds and asked for 4 GiB.
What was measured. The time from launching the process to the first 201 response to a POST /v1/pedidos. It's not enough for the port to open: that response forces two calls to the inventory supplier and a write to H2. Right after receiving that 201, ps reads the memory the process takes up (RSS, resident set size: the physical memory it holds). Five runs in a row of each, and the median. The script is herramientas/medir-arranque.py, and it comes with the template so you can repeat it.
Where. A Mac with Apple Silicon (macOS arm64, 10 cores, 32 GB), on November 18, 2026. Both JVM ones with Java 25 (Temurin 25.0.5+8), with no memory options; Quarkus 3.40.1.2 and Spring Boot 4.1.2, the template from installment 5.
| The same API, on… | First response (median of 5) | Memory (RSS) | The five runs |
|---|---|---|---|
| Spring Boot, JVM | 2,241 ms | 437 MiB | 2181, 2241, 2377, 2301, 2207 ms |
| Quarkus, JVM | 1,220 ms | 270 MiB | 1515, 1250, 1220, 1145, 1175 ms |
| Quarkus, native | 46 ms | 60 MiB | 150, 67, 46, 38, 44 ms |
We repeated the batch on the same Mac, with Temurin 25.0.4+7: Spring Boot, 2,617 ms and 427 MiB; Quarkus on the JVM, 1,378 ms and 266 MiB; native, 47 ms and 60 MiB. The JVM milliseconds move from one batch to another; the order doesn't.
What it costs. Building native required GraalVM, the compiler that turns the set-up kitchen into an executable. In SDKMAN it's installed as the 25.5.5.0+3-graalce candidate [21]. On the same Mac it took 80 seconds (72 of them compiling), reached 4.11 GiB of memory and left a 78 MiB executable, which only works on the system where it was built: one built on a Mac doesn't run on Linux. The JVM one builds in seconds. The official guide agrees: «native compilation takes minutes, JVM builds take seconds» [2].
What that table doesn't tell you. The Quarkus guide has its own comparison, with its own application and machine: in its benchmark, native reaches the first request in 581 ms versus 4,417 for the JVM and takes up 95 MiB versus 304. But it serves 5,411 requests per second versus 13,265: «~59% below JVM» [2]. The same guide gives the reason: on the JVM, the compiler optimizes while the application runs, and in long-running services that beats native [2]. We didn't measure requests per second, and that's why we don't give a figure of our own.
It's Lucía's question. Native opens fast and takes up little. Cooking fast, for hours, is something else.
So, which one? The template runs on the JVM: it builds in seconds, it's checked with the usual tools and it starts in a little over a second, which for an API that lives for days doesn't matter. Native is worth it when startup and memory do matter: functions that are born with each request, many small replicas, scaling from zero. In this template it's the same code: deciding means changing the build command, not the layers. In another application you may have to declare what gets loaded through reflection [2][3]. And at Hábil it's decided in writing, with the measurement that backs it.
Do the arrows still point inward?
Yes, and the same test watches over it. This time the script plants four errors instead of one.
For Java, the cook knowing the waiter still isn't an error: it compiles. The rule is watched by CapasTest, written with ArchUnit, which checks the compiled classes [17]. The layers are the same as in installment 5:
.whereLayer("api").mayNotBeAccessedByAnyLayer()
.whereLayer("facade").mayOnlyBeAccessedByLayers("api")
.whereLayer("service").mayOnlyBeAccessedByLayers("api", "facade")
.whereLayer("repository").mayOnlyBeAccessedByLayers("service")
.whereLayer("client").mayOnlyBeAccessedByLayers("facade", "service")And a separate rule: no class in api may depend on an entity. The waiter hands over the receipt, never the file card.
herramientas/probar-frontera.sh works on a temporary copy. First it runs the control: the project as it is has to pass. Then it plants four errors, one at a time. Each one has to compile, and CapasTest has to fail on a single rule, for the exact reason. This is the real output, trimmed:
1/5 control: el proyecto tal como está; el cocinero no conoce al mesero y el mesero no entrega la ficha
✅ compiló y CapasTest pasó: 4 reglas, 0 fallas
2/5 violación: se siembra en PedidoService un método que recibe un PedidoResource
✅ CapasTest falló en una sola regla, lasFlechasSoloVanHaciaAdentro
3/5 fuga: se siembra en PedidoResource un método que entrega la PedidoEntity tal cual
✅ CapasTest falló en una sola regla, elMeseroNoConoceLaFichaDelArchivo
4/5 fuga: la misma PedidoEntity, escondida en una List<PedidoEntity>
✅ CapasTest falló en una sola regla, elMeseroNoConoceLaFichaDelArchivo
5/5 fuga: la misma PedidoEntity, escondida en una RestResponse<PedidoEntity>
✅ CapasTest falló en una sola regla, elMeseroNoConoceLaFichaDelArchivo
✅ frontera: se sostiene (la violación y las tres fugas salieron en rojo, cada una por su razón)And what if the script lies? We sabotaged it. With the file card rule pointing at another package, it stops in red at the first leak. Without the api layer rule, it stops at the violation. A script that can't fail proves nothing.
There are 82 tests, counted in the reports in target/surefire-reports/, not in the BUILD SUCCESS. The ones that start the application use @QuarkusTest. The ones that share a profile reuse the same Quarkus instance; a test with another profile, like the one with the supplier turned off, restarts it [23].
What are five frequent mistakes?
Three are a role doing another one's job, as in installment 5. Two are new: confusing opening with cooking, and trusting what doesn't warn you.
1. The file card that is also the pantry
The entity inherits from PanacheEntity and stores itself.
It's the style the Panache guide teaches first [5], and it works. We measured it on a clone of the template: we made PedidoEntity inherit from PanacheEntityBase and ran everything. 82 of 82 green. No test in the template sees it, because the arrows are still fine: the file card doesn't import anyone. What changed is that the file card now brings persist(), and anyone holding a file card, inside a transaction, could write to the database.
What gives it away is a search:
grep -rn 'extends PanacheEntity' src/mainZero results is what you want. It's Monday's task.
2. Moving everything to native because it opens fast
Measuring startup and drawing conclusions about performance.
It's Iván's. Native opens in milliseconds, but in the official guide's benchmark it serves ~59% fewer requests per second, and building it takes minutes and asks for gigabytes of memory [2]. One question gives it away: what actually costs you, opening or serving?
3. The binary that starts and dies on its first order
Testing native with health and not with a real order.
When compiling to native, only what the compiler sees being used gets in. What a library loads by name, on the fly, can be left out. The Quarkus guide describes the worst case: there's no exception, but «the JSON result would be completely empty» [3]. Health can answer UP while the first order comes out empty. That's why the template doesn't accept native just because it starts: it asks it for an order that calls the supplier and writes to the database. We measured it like this: native answered 201, 404, 409, 422 and 400 with its Problem Details, and 503 with the supplier turned off.
4. A key that is silently ignored
A misspelled configuration doesn't fail: it does nothing.
It happened to us with the template. To shorten the timeout in the tests, we wrote the key with the interface's name, InventarioApi/producto. Quarkus didn't complain, and the timeout stayed at 2 seconds. The correct key carries the name of the class Quarkus generates for the interface, InventarioApi$$CDIWrapper/producto. Quarkus does warn about a key it doesn't recognize, with «Unrecognized configuration key», but only for the ones that start with quarkus.; measured with a fake one of each kind. What gives it away is a test that depends on that key: the timeout test turns red if the key isn't applied.
5. Copying Spring's annotations
Looking for @RestController, @Service and @Autowired in a Quarkus project.
In Quarkus, the waiter is a Jakarta REST resource, and components are wired with CDI [4][10]. Quarkus has extensions that understand some Spring annotations [19], but the template doesn't use them: if the project is Quarkus, it's written as Quarkus, and whoever reads it later finds what the official documentation teaches. If a team decides to use them, let it be in writing, not because someone copied an example.
| Mistake | What gives it away | Source |
|---|---|---|
| 1. The file card that is also the pantry | grep -rn 'extends PanacheEntity' src/main | [5] · measurement |
| 2. Everything to native because it opens fast | Requests per second, not just startup | [2] |
| 3. Native that dies on its first order | A real order, not health | [3] · measurement |
| 4. A key that does nothing | A test that depends on that key | measurement |
| 5. Spring annotations in Quarkus | @RestController or @Autowired in src/main | [4][10][19] |
Exercise: can you hide the file card in the receipt?
You're going to make the waiter hand over the file card inside a response, see that Java accepts it, and see how the test and the script warn you.
You need Java 25 (java -version), Git 2.23 or newer (for git restore), bash and curl; about 25 minutes. Not Maven: the project brings it. If you don't have Java 25 yet, installment 5 and the template's README explain how to install it with SDKMAN; on Windows, use WSL. Native isn't needed for the exercise.
Step 1. Clone it and check that everything is green.
git clone https://github.com/HabilMX/estructura-quarkus
cd estructura-quarkus
./mvnw verify
bash herramientas/probar-frontera.shThe first time takes a while: it downloads Maven and the libraries. You should see Tests run: 82, Failures: 0, Errors: 0, Skipped: 0, then BUILD SUCCESS and, at the end of the script, ✅ frontera: se sostiene.
Use this clone only for practice. That way, every change you see in it belongs to the exercise.
Step 2. Predict before you touch. You're going to add to the waiter, PedidoResource, a route that returns the PedidoEntity inside a RestResponse. Write it down: does it compile? What does CapasTest say? And the boundary script?
Step 3. Hide the file card. The first line removes the class's last brace and leaves a .bak copy; the second adds the route and closes the class. The syntax works on macOS and on Linux; the full exercise was tested on macOS.
sed -i.bak '$d' src/main/java/mx/habil/pedidos/api/PedidoResource.java
printf ' @GET\n @Path("/{id}/ficha")\n public org.jboss.resteasy.reactive.RestResponse<mx.habil.pedidos.model.entity.PedidoEntity> ficha(@PathParam("id") UUID id) {\n return org.jboss.resteasy.reactive.RestResponse.ok(service.buscar(id));\n }\n}\n' \
>> src/main/java/mx/habil/pedidos/api/PedidoResource.java
./mvnw -q test-compile
./mvnw -q test -Dtest=CapasTesttest-compile finishes without saying anything: it compiled. The test doesn't. Among many lines, the ones that matter:
Tests run: 4, Failures: 1, Errors: 0, Skipped: 0
Method <mx.habil.pedidos.api.PedidoResource.ficha(java.util.UUID)> has generic return type <org.jboss.resteasy.reactive.RestResponse<mx.habil.pedidos.model.entity.PedidoEntity>> with type argument depending on <mx.habil.pedidos.model.entity.PedidoEntity> in (PedidoResource.java:0)ArchUnit didn't look at the type the method returns, but at what it depends on: the file card was hidden inside the response, and it still found it.
Step 4. Ask the script.
bash herramientas/probar-frontera.shIt turns red, without getting past the control:
❌ el control NO pasó: tu proyecto, tal como está, ya rompe una regla de CapasTest:That's the control at work: it can't prove the test knows how to fail if your project already has it failing.
Step 5. Revert only what you touched. First, look at what changed:
git diff --stat -- src/main/java/mx/habil/pedidos/api/PedidoResource.javaYou should see 1 file changed, 5 insertions(+): the new route. If you see anything else, it's yours: save it before going on. If only the exercise is there, revert that file. git restore only touches the paths you give it [22]:
git restore src/main/java/mx/habil/pedidos/api/PedidoResource.java
bash herramientas/probar-frontera.sh
git status --shortThe boundary goes back to green, and git status shows what's left, the copy sed made:
?? src/main/java/mx/habil/pedidos/api/PedidoResource.java.bakKeep it until you're sure you don't need it. Then delete it with rm -i, which asks first.
How you know you did it right: you ran six times and saw three outcomes. Green, four times: the two in step 1, test-compile in step 3 and the boundary in step 5. Red from the test, once: Failures: 1 in step 3. And the script's red, «el control NO pasó», in step 4. If in step 3 test-compile reports an error, check that PedidoResource.java ends with a single brace }.
To go further (optional): turn the file card into a pantry. In PedidoEntity, make the class inherit from PanacheEntityBase (add import io.quarkus.hibernate.orm.panache.PanacheEntityBase; and change public class PedidoEntity { to public class PedidoEntity extends PanacheEntityBase {). First, predict: how many tests fail? Measured answer: none, 82 of 82. Run grep -rn 'extends PanacheEntity' src/main: that one does find it. Revert the same way as in step 5.
Key takeaways
Three questions to ask your repository this week.
- How many file cards in your project inherit from
PanacheEntity? Each one is an entity that brings its own methods to store itself. - If you use native, what measurement justified it: startup, memory or requests per second? Was it written down?
- Which test turns red if a key in your configuration stops being applied? If the answer is "none", that key may have been doing nothing for months.
What's next?
The restaurant also has a dining room.
One Friday, Iván was asked to move a button on the screen where the store sees its orders. The project was in React. He opened the src/ folder and found eighty loose files, all at the same level: buttons, screens, API calls, all together.
He had learned to ask whose job each piece of work is. This time he couldn't even find the roles. On Sunday, December 13, in installment 7, the last one in the series: how to arrange a frontend with React, what goes in each folder, and the template that checks it.
The template and the course
- Template: github.com/HabilMX/estructura-quarkus. Use it as a GitHub template or clone it. The README explains each package with its "never", the path of an order, what changed compared to Spring Boot, how to measure startup and memory, what it doesn't include (authentication, a real database, an OpenAPI contract), when to add each thing and how to remove the example. The code is MIT; the text and explanations are CC BY-SA 4.0.
- To see it working: the README has the
curlcommands. The example inventory supplier is a folder with two JSON files, served withjwebserver, which the JDK already ships. The database is H2, in memory: the simplest thing that runs on the first try; the data is erased on shutdown. Health and metrics, on port 9000. - Versions: Java 25 with Temurin 25.0.5+8. Quarkus 3.40.1.2: 3.40 is its most recent long-term support version [13], and a long-term support version is maintained for 12 months, with a new one every six [12]. Maven through the Wrapper. GraalVM CE
25.5.5.0+3-graalce, only for native. It was tested on macOS arm64. Not on Linux yet: the CI is written for Ubuntu and macOS, and it runs once the public repository exists. - Hábil's Java course: if
records, Maven or testing with JUnit are new to you, start there: Java course. And if you didn't read installment 5, read it first: this one takes the restaurant's roles as known.
I write from what we see every day at Hábil, where we build systems for banking, insurance and companies in Mexico. If at work or at school you run into a repository nobody knows where to touch, let's talk: habil.mx
What does Hábil do?
We teach programming with the same things we use to build: tested, explained and open code.
This series comes from the same place as our courses. The Java course teaches today's Java: types that express the model, tests, concurrency and a finished program, packaged as a JAR, and we publish it openly, under a Creative Commons license; its lesson 3 covers the records and its lesson 6 the Maven project, the same foundation this article's template uses. And the catalog has more programming courses, free and with code tested and explained step by step.
See the Java course and the Programming courses catalog.
If your team inherits a system nobody knows where to touch, or needs to build one that can keep being maintained, we do that too: see Build your custom system. Request your first conversation, at no cost. In it we review whether it makes sense to configure what you already have, use a product or build, and what you would get in each case. Write to us on WhatsApp.
Sources accessed on November 18, 2026. Quotes in English are reproduced as is.
References
- Quarkus, «Container First»: «Build Time Processing». https://quarkus.io/container-first/
- Quarkus, «Building a Native Executable»: «Comparing JVM, Leyden AOT, and native modes» (benchmark from Apr 21, 2026, Quarkus 3.34.3, JDK 25.0.2, 4 CPU). https://quarkus.io/guides/building-native-image
- Quarkus, «Tips for writing native applications». https://quarkus.io/guides/writing-native-applications-tips
- Quarkus, «Writing REST Services with Quarkus REST»: «Exception mapping». https://quarkus.io/guides/rest
- Quarkus, «Simplified Hibernate ORM with Panache»: «Solution 1: using the active record pattern» and «Solution 2: using the repository pattern». https://quarkus.io/guides/hibernate-orm-panache
- Quarkus, «Using the REST Client». https://quarkus.io/guides/rest-client
- Quarkus, «SmallRye Fault Tolerance». https://quarkus.io/guides/smallrye-fault-tolerance
- Quarkus, «SmallRye Health». https://quarkus.io/guides/smallrye-health
- Quarkus, «Management interface reference». https://quarkus.io/guides/management-interface-reference
- Quarkus, «Contexts and Dependency Injection» (ArC reference). https://quarkus.io/guides/cdi-reference
- Quarkus, «YAML configuration». https://quarkus.io/guides/config-yaml
- M. Rydahl Andersen, «Long-Term Support (LTS) for Quarkus», Quarkus blog, July 6, 2023. https://quarkus.io/blog/lts-releases/
- G. Smet, «Quarkus 3.40 LTS - new LTS version», Quarkus blog, September 30, 2026. https://quarkus.io/blog/quarkus-3-40-released/
- Eclipse Foundation, «Jakarta RESTful Web Services 3.1», parameter conversion. https://jakarta.ee/specifications/restful-ws/3.1/jakarta-restful-ws-spec-3.1
- Quarkiverse, «quarkus-http-problem», GitHub. https://github.com/quarkiverse/quarkus-http-problem
- M. Nottingham, E. Wilde and S. Dalal, «RFC 9457: Problem Details for HTTP APIs», IETF, July 2023. https://www.rfc-editor.org/rfc/rfc9457.html
- ArchUnit, «ArchUnit User Guide»: «Layer Checks». https://www.archunit.org/userguide/html/000_Index.html
- Quarkus, «Virtual thread support reference». https://quarkus.io/guides/virtual-threads
- Quarkus, «Quarkus extension for Spring DI API». https://quarkus.io/guides/spring-di
- Quarkus, «Micrometer Metrics». https://quarkus.io/guides/telemetry-micrometer
- SDKMAN, Java candidates for macOS arm64 (
25.5.5.0+3-graalce). https://api.sdkman.io/2/candidates/java/darwinarm64/versions/list?installed= - Git, «git-restore». https://git-scm.com/docs/git-restore
- Quarkus, «Testing your application». https://quarkus.io/guides/getting-started-testing
Does your operation face these challenges?
Prefer email? Write to us at hola@habil.mx