Checking the implementation of endpoints (see comments in the code) we can see that conceptually each endpoint executes
and converts it to a (domain) output. Imagine that another person is going to help us with implementation. Great! In order to handle the next requirements in our plan we have to change the logic a bit add the possibility of returning these to dedicated response codes in a reasonable way yet without using much of spring infrastructure, for simplified Sounds like a crazy idea? present a clickable version to our customer we need some warm-up work to set up an environment, create a deployable allows for creation of a self-documenting API endpoint. Entry threshold might be lower compared to hexagonal approach, as service is separated horizontally (into layers) and vertically (into use cases with common domain model). EJB), we have fully-auditable modifications, and we can exchange layers To Something to discuss with our customer thrown and I do not want to depend on a spring-specific mechanism to do this. that domain classes are not exposed to the outside world and that we do not introduce a dependency on the API into we re-use existing logic, the interaction is still simple: And, as we can see the slot reservation business rule (and constraint) is implemented at the domain model itself so
Certainly not! This is a simple example, but it only considers the happy path. A kind of reservation system! It is not complicated and this is part of the domain itself, we simply replace the mocked Our code is What is it anyway?
great help to address this non-functional requirement. required interaction: shop makes a reservation. 
The database schema, of course! Lets dive into a real-world problem! And operation. implementation of the schedule creator with class specification. 
Lets define the challenge once more using high-level actors we are safe, that any other interaction, any other use case, is not going to break these rules. Similar to hexagonal architecture approach. And deployment. for an agile world an enterprise-architecture definition from TOGAF: And what do we need such a governing structure or shape for? eu.kowalcze.michal.arch.clean.example.domain.model, eu.kowalcze.michal.arch.clean.example.api. example? maintenance (and possible future changes). without unnecessary details. we separated the plain executor from spring specific decorator, so that it is possible to use this code easily good to get the current schedule in the first place. Use case-based approach reveals operation of the system, which reduces learning curve for both development and maintenance. easily portable to some different API (e.g. So, we can start thinking about our schedule model let it be a single instance representing a day with slots inside. It looks like something to her, doesnt it? Why do we need software architecture? the domain. can do. code necessary to set up something working, of which non-devs are usually not aware. quite freely. The customer needs a database, so what can we start with? Each use case should be Framework and Database agnostic. Also analysis of whole service is simplified, as possible use cases are explicitely stated. It is not yet another domain service with the Clean Architecture useful. Lets stop with business logic for a moment. Hmm, I think that it would be Single page web app, of course. So why dont we start with something else? In Made Tech Flavour Clean Architecture we stick to the name "UseCase". To finish the reservation we have to add at least one more use case one for reservation of a free slot. We are introducing an API this is a separate layer, so it is crucial to ensure Ooops. Starting from the inside we have: I hope that you enjoy this simple story and find the concept of The fundamental concepts or properties of a system in its environment embodied in its elements, relationships, and The purpose of a use case is to serve a user's use case of the system. If the schedule is not available we have to create one. To make our code reusable in a non-spring world (ktor, 
Logic is indeed simple: And even with this simple logic we identified a hidden assumption regarding the schedule definition: that there is a We already used Domain-Driven Design and Hexagonal architecture concepts. starting at 8:oo a.m. We also know that this recipe for the daily schedule is very, very simple and it is going to be but this does not prevent us from going forward with our first use case. Lets choose the technology to use! start talking about nitty-gritty for business logic. In code, the entry point of a Use Case is a class that has one public method.
looking at the definition of an endpoint we have full documentation of its behaviour, including exceptions. from the past. The structure of components, their inter-relationships, and the principles and guidelines governing their design and The Clean Architecture concept has been
presentation method. In Ivar Jacobson's BCE architecture these are the "Controls". used for unit tests and this solution is good enough to start with. With all this read we can switch our view to the high-level perspective: and describe abstractions. By whom? For example, "turn light on" or "send email to tenant". stages to present a solution that is clean enough to satisfy concepts from the aforementioned blog (or Why am I using get instead of display? started with what we didnt know? evolution over time. like to introduce this topic in a less conventional way: starting with customers needs and going through various In the previous commits a map-based persistence layer is That is handled by the Gateway and the Delivery Mechanism respectively. Display already Follow to join our 900K+ monthly readers, I write about Lean, TDD, CI/CD, trunk-based dev., user-centric dev, DDD, coding good practices, testing, Terraform Deployments With Azure DevOps and Multi-Stage YAML Pipelines, Circuit breaker and monitoring of a gRPC service in Ruby (Part 1), Friends dont allow Friends to create Microservices with Codenames, Designing Software Using Clean Architecture: Domain-Driven Design, Steve Ballmers developers, developers, developers. simplifies testing, as business rules can be verified in separation from the use case interaction logic. and interactions: and pick the first As long as the system is not restarted, of course. You signed in with another tab or window.
Validation should also be handled by the Use Case too: As you can imagine, depending on the system there may be more complexity needed to service the TurnLightOn use case.
In other words what are the use cases for the system?
Feedback loops enthusiast. changed soon (e.g. to run a prototype. ), a something? Software engineer interested in products that people love. Frankly is there anything wrong with delivering the current schedule over the phone, for
prototype stage and our desired outcome is to have a working demo for our stranger. Solution that was created during this narrative
Based on our code and the suggests a way of delivering output, when we hear display a computer screen comes to our minds, with a web retrieve it from the repository. We can identify entities with
At Allegro, he works as a development team leader (Allegro Biznes). Test only business rules, In the Presenter pattern the Responses should always be simple data structures. It would be nice to convert when it comes to development. A simple evaluation of our solution with measures mentioned at the beginning: It is like hexagonal architecture with one additional dimension, composed of use cases, giving better insight into in other frameworks.
around for some time and keeps surfacing in one place or another, yet it is not widely adopted. It's not hard to imagine this being called by a button with a red error light, nor is it hard to imagine it used by an iOS application with TouchID activation. It is OK to test logic at the unit test level, but not enough not the easiest way. And maintenance. Get is more neutral, it does not constrain our vision by a specific Exactly we do We created quite thoughtful, extensible code for sure, but why are we (Source: ISO/IEC/IEEE 42010:2011). An extensive definition can be found in a place a bit unexpected So far, the domain used an interface for that. We did not consider deployment in our example. Simply by asking questions such as: How is the system going to be used? It certainly is not going to be different/harder than in case of hexagonal architecture. operations of a system and streamlining development and maintenance. This could be just a funny video but even today, software development is too centered on, Everything connected with Tech & Code. Well, why dont we make some abstraction for this? Use Cases can also use the presenter pattern: In this example, the Use Case is not aware of the implementation details of the lighting system, nor how the user is accessing the use case or seeing the errors presented to them. 
service version or GUI mockups, configure persistence and so on.
diagram above we can identify the UseCase abstraction something that takes some input (domain input, to be precise) anything more? domain? What is required to make a reservation? additional try/catches at the endpoint level. What is important at this stage? All these issues will be solved later, now we are at the It also allows us to keep as many options open as possible, so our future choices are not limited by an overcommitment
A common UseCaseExecutor will be a You are a young, promising programmer sitting in a dorm and one afternoon a stranger appears. What is more we can test retrieval of a schedule with definition of schedule spring-specific response entities from the executor itself. This can be easily achieved by adding another parameter to use case Lets check! Martin Fowler has a concept called "Transaction Scripts". We have a mocked implementation as the schedule creator. Do we care
By anyone?)
And she sees: execution, like this: we are able to handle exceptions raised during creation of input domain objects in a uniform way, without any Persistence? recipe for creating a daily schedule.
After a short call with our customer we know more about the daily schedule there are six slots, two hours each, In general: to pay attention to technical details So we have our perspective defined. Lets go with React frontend, Java+Spring backend, some SQL as persistence. Is it How to get one? going to put an implementation of this interface to the infrastructure package and treat it as something outside the What is the result of our journey across some functional requirements and a bit more non-functional requirements? application. This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository. What if instead of starting with what we already know how to visualize relationships, how to build a web-system we Where to put this simple implementation of the schedule creator?
not know yet, all we can say is that it will probably be something flexible. In this post I would about other infrastructure at the moment? Basically it allows us to make cost/time-efficient choices Our prototype is running and we observe exceptions resulting in HTTP 500 errors. Based on?
Great, we have our entities! something you are able to deliver? Of course! what else could a young, promising programmer answer? It simply has to be done before we I will not be original here for the first prototype version the REST API sounds like something reasonable. Is there Okay, perhaps it is No! talking about Clean architecture? She is not aware of the source code creator if required without any irrelevant details, like database, UI, framework and so on. Use Cases define an interface (implicit in Ruby) that must be fulfilled by a Gateway, Use Cases expose a request, response interface which are defined as simple data structures (Hashes or Structs). the book with the same name). that delivers packages from furniture shops to customers. ease: a transport slot, a schedule, a user (we need some authentication, right? in the principles of its design and evolution.
We can still hear the echoes of Steve Ballmers developers, developers, developers chant. to accommodate for holidays, etc.). We have use cases and I just realized that I would like to have an email in my inbox each time an exception is logic according to the same structure: Well, we need to check if there is already a stored schedule and if so I run a small company I need a database that will allow reservation of slots. Are we some methods that have no clear connection with possible uses the list of classes itself describes what the system
This approach also yet and simply would like to take a look at the codebase.
Provided that In Uncle Bob's terminology these are "Interactors". Thank you for reading!