A report on the construction of a software system with artificial intelligence — from the first prompt to the first functional prototype.
🔗 Source code of the prototype: github.com/dmissud/biblioCQRS — tag First_IT
The project, in two sentences
I've been training computer scientists for years—business analysis, Babok, IREB, software architecture. I've always used the same example to illustrate my courses: a library. Simple to understand, yet rich enough to demonstrate complex principles. This time, I wanted to go further: to actually build the system, live, with AI as a development partner. And to document every step.
BiblioCQRS was born from this. A library catalog management system, built on a hexagonal architecture, with CQRS, Event-Driven Architecture, and Apache Kafka. The domain is intentionally well-known. What interests me is the methodology.
The setting comes first
Before writing a single line of code, I laid out the framework for Gemini. Not by asking it to "create a library application." By dictating the architectural constraints one by one:
«"We will begin by laying the groundwork for the objective and the rules. Everything we do must follow strict TDD with a BDD approach. We will implement a black-box approach for the domain/use case and follow the principles of hexagonal architecture."»
Gemini responded positively, summarized the four principles — TDD, BDD, black box, hexagonal — and asked which use case to start with. Good start.
I then added the CQRS layer and the infrastructure selection:
«Another architectural principle I want you to note. I want to create a CQRS architecture. […] I’m in a mindset of demonstrating best practices, and a foundation like Postgres suits me.»
And then, Gemini did what all AIs do: it immediately offered three options for event handling—in-memory, message broker, event sourcing—along with sub-questions about the language, the ecosystem, and the desired level of complexity. Useful, but already a slight drift towards exhaustiveness.
I made a clean decision: Java Spring Boot, multi-module Maven, Kafka, Docker Compose. And we move on to the next step.
The first pitfall: AI that wants to do everything
This is where it gets interesting. I had outlined the business domain: a work defined by its ISBN, its title, its author. Physical copies. Each copy with a location—room, shelf, position. I had specified that we were in a library, that copies counted as much as books.
Gemini has produced its first BDD scenario:
Given that the book with the ISBN "978-2-07-036822-8" ("1984", George Orwell) does not exist in our catalog
When the librarian references this work with 1 copy located in "Room A", "Shelf 2", "Position 15"«
Then the work is added to the catalog
And one copy is created and assigned to this storage location
A clean script. Well-written. And yet, I held back.
«"I find this first scenario quite good, but very complex for a baby-step approach. Perhaps shorter steps would be better for a gradual implementation."»
That's the trainer's reflex. A scenario that combines creating a book AND adding a copy AND its location is too much for a first TDD iteration. If something doesn't work, we don't know where to look. The baby step is the golden rule: One thing at a time, one reason to fail.
Gemini immediately understood and broke it down into three steps:
- Baby Step 1 To reference an abstract work — ISBN, title, author. Nothing else.
- Baby Step 2 : Reject a duplicate ISBN — the uniqueness business rule.
- Baby Step 3 : Add a copy with its storage location to an existing work.
Three scenarios. Three distinct TDD loops. Three different reasons to fail — and therefore to understand.
What this reveals about AI
AI can't resist the urge to deliver a complete system. It confuses "showing its value" with "doing everything all at once." Left unconstrained, it produces rich code, seemingly functional, but monolithic—difficult to read, impossible to properly test, and, above all, in direct contradiction with the principles it just accepted. You ask it for TDD, it writes code. You ask it for baby steps, it offers you an entire feature.
This is not a flaw in AI. It is its nature: it optimizes for completeness, not for discipline. It is up to the developer to stop it.
And to stop it, you have to know where you want to go.
Documentation as a safeguard
Alongside the code, I imposed a rule: each iteration must enrich the functional and architectural documentation. Not after the fact — continuously.
I had asked Gemini to produce structured documentation based on Babok principles: product vision, stakeholders, breakdown of objectives, use cases. But not all at once. Step by step, staying strictly within the scope of what is implemented.
«"Let's make it a project rule to always update the functional documentation."»
The documentation is not optional. It is not a project deliverable. It is a mirror of the code — it must reflect exactly what exists, nothing more and nothing less.
Result: at the end of the first prototype, we had structured functional documentation (vision, stakeholders, objectives tree, business glossary, use cases) and architectural documentation (hexagonal, CQRS, Maven modules, infrastructure). Both were perfectly aligned with what was actually running.
What was actually built
In just a few hours of guided dialogue, here's what the prototype contains:
Command side (writing):
A pure domain in Java — the aggregate Work, its entities Copy, its value object Storage Location. Three green database scenarios. A PostgreSQL adapter via Spring Data JPA. Event publishing to Kafka (Reference Book Event, Copy Add Event) encapsulated in the repository implementation — the domain does not know that Kafka exists.
Query side (read):
A Kafkaesque consumer who projects events into a denormalized view catalogue_view — ISBN, title, author, number of copies. A REST GET endpoint for the frontend.
The frontend:
An Angular 17 application with Material Design, three facets: live catalog consultation, manual book referencing, and a test dashboard that triggers an automated injection of fifteen queries in bursts to observe the propagation of events in Kafka.
The infrastructure:
A docker-compose.yml which orchestrates PostgreSQL, Zookeeper and Kafka. Two independent Spring Boot applications — command on port 8082, query on port 8083.
The emerging thesis
We often hear that AI will replace developers. This experiment suggests the opposite: it restores control to managers. more indispensable than ever.
A developer without a business analysis background, without an iterative approach, without knowledge of architectural principles—this developer will drown in what the AI offers. They will accept the first overly complex scenario. They will let the AI wire the Kafkaesque domain. They will end up with a working prototype that they don't understand.
AI is a powerful accelerator for long and repetitive tasks: writing BDD scenarios, generating the Maven skeleton, producing JPA entities, configuring Spring Kafka. These tasks, which used to take hours, are now done in minutes.
But the accelerator doesn't know where to go. You're the one in control.
Episode 2: Architecture rises from the ground — how to guide AI to respect the borders of the hexagon.
Leave a Reply