Bottom-Up Architecture – Bridging the Achitecture Code Gap

Hard to change code bases often suffer from two primary problems: a lack of alignment with domain boundaries and failure to effectively express architectural ideas in code. To address that critical issue, developers have turned to Separation of Concerns Architectures, such as Onion-, Clean and Hexagonal Architecture. However, these approaches typically yield mixed results, as they primarily focus on separating technical and business code, without addressing the structural aspects of the domain.

This presentation explores strategies for transferring architectural ideas and design pattern languages into code at various levels of abstraction. We will discuss how different frameworks and libraries in the Java ecosystem can aid in this process, leveraging the presence of meta-information within the code to support critical aspects such as structural verification, testability, and documentation. By employing these approaches and tools, developers can write more maintainable code that is less susceptible to degradation over time.

Version:
- Software Architecture Alliance (Keynote, current) - https://static.odrotbohm.de/slides/2024/10/bottom-up-architecture-saa.pdf
- Java Forum Nord – https://static.odrotbohm.de/slides/2024/09/bottom-up-architecture-jfn.pdf
- GOTO Amsterdam 2024 – https://static.odrotbohm.de/slides/2024/06/bottom-up-architecture-goto-ams.pdf

Transcript

1. BOTTOM-UP ARCHITECTURE BRIDGING THE ARCHITECTURE CODE GAP Oliver Drotbohm  oliver.drotbohm@broadcom.com    odrotbohm
3. Architectural Goal Architectural Concept Supporting Technology Development Practice supports drives selection drives selection enables supports supported by
4.  
5. "Architecture is a property of a system, not a description of its intended design." — Stefan Tilkov in "Good Enough Architecture"
7. Vocabulary Domain Terms Abstraction Pattern Languages Level of Detail Encapsulation Concepts & Rules Extensional Intensional Enumerated Specified
8. Architecturally- Evident Code? !
9. Deployables / Build modules / Packages Classes, methods, fields    Extensional Intensional Naming conventions What else? " Invoicing, Shipment Components / Modules EmailAddress, ZipCode Domain language Concepts ValueObject, Entity, Aggregate Layers, Rings Concepts & Rules
10. Chunking Hierarchization Pattern languages
12. A simple Aggregate arrangement Orders Customers «Aggregate» Order id: OrderId lineItems: List<LineItem> customer: Customer «Entity» LineItem amount: int price: MonetaryAmount «Aggregate» Customer id: CustomerId contains 1 1..* belongs to * 1 This and that imply that this is wrong! #  
13.  Tools  Frameworks  User Code  Concepts  Rules Code Architecture Technology
14.       Means of definition
16. MATCH (repo:Java:Type) -[:IMPLEMENTS_GENERIC]-# (superType) -[:OF_RAW_TYPE]-# (:Java:Type { fqn: "o.s.d.r.Repository"}), (superType) -[:HAS_ACTUAL_TYPE_ARGUMENT { index: 0 }]-# () -[:OF_RAW_TYPE]-# (aggregateType) SET aggregateType:Aggregate RETURN repo, aggregateType Establishing an Aggregate… in jQAssistant MATCH (aggregate:Aggregate) -[:DECLARES]-# (f:Field) -[:OF_TYPE]-# (fieldType:Aggregate) WHERE aggregate <& fieldType RETURN aggregate, fieldType Establishes the concept Establishes the rule Reference to tech stack $
17. @AnalyzeClasses(packagesOf = Application.class) public class ArchitectureTest { @ArchTest void verifyAggregates(JavaClasses types) { var aggregates = new AggregatesExtractor(); var aggregateTypes = aggregates.doTransform(types); all(aggregates) .should(notReferToOtherAggregates(aggregateTypes)) .check(types); } } Establishing an Aggregate… in ArchUnit Establishes the concept Establishes the rule
18.       Responsibility of definition Means of definition
19.     🕵 Responsibility of definition  
20.   
21. xMolecules
22. jMolecules
23. Architectural Goal Architectural Concept Supporting Technology Development Practice supports drives selection drives selection enables supports supported by Understandability DDD Building Blocks jMolecules
24.  Explicit concepts
25. @Entity @NoArgsConstructor(force = true) @EqualsAndHashCode(of = "id") @Table(name = "SAMPLE_ORDER") @Getter public class Order { private final @EmbeddedId OrderId id; @OneToMany(cascade = CascadeType.ALL) private List<LineItem> lineItems; private CustomerId customerId; public Order(CustomerId customerId) { this.id = OrderId.of(UUID.randomUUID()); this.customerId = customerId; } @Value @RequiredArgsConstructor(staticName = "of") @NoArgsConstructor(force = true) public static class OrderId implements Serializable { private static final long serialVersionUID = …; private final UUID orderId; } } What is the role of this class in the overall arrangement?
26. Conceptual Density 1 N N = Number of source code elements needed to determine the architectural role of a piece of code
27. @Entity @NoArgsConstructor(force = true) @EqualsAndHashCode(of = "id") @Table(name = "SAMPLE_ORDER") @Getter public class Order implements o.j.d.t.AggregateRoot<Order, OrderId> { private final @EmbeddedId OrderId id; @OneToMany(cascade = CascadeType.ALL) private List<LineItem> lineItems; private CustomerId customerId; public Order(CustomerId customerId) { this.id = OrderId.of(UUID.randomUUID()); this.customerId = customerId; } @Value @RequiredArgsConstructor(staticName = "of") @NoArgsConstructor(force = true) public static class OrderId implements o.j.d.t.Identifier { private static final long serialVersionUID = …; private final UUID orderId; } }
28. Verification
29. Invalid aggregate root reference! Use identifier or Association instead! ☝
30. Eliminate Boilerplate
31. @Entity @NoArgsConstructor(force = true) @EqualsAndHashCode(of = "id") @Table(name = "SAMPLE_ORDER") @Getter public class Order { private final @EmbeddedId OrderId id; @OneToMany(cascade = CascadeType.ALL) private List<LineItem> lineItems; private CustomerId customerId; public Order(CustomerId customerId) { this.id = OrderId.of(UUID.randomUUID()); this.customerId = customerId; } @Value @RequiredArgsConstructor(staticName = "of") @NoArgsConstructor(force = true) public static class OrderId implements Serializable { private static final long serialVersionUID = …; private final UUID orderId; } } JPA-induced boilerplate Model characteristics expressed implicitly or through technical means
32. @Entity @NoArgsConstructor(force = true) @EqualsAndHashCode(of = "id") @Table(name = "SAMPLE_ORDER") @Getter public class Order implements AggregateRoot<Order, OrderId> { private final @EmbeddedId OrderId id; @OneToMany(cascade = CascadeType.ALL) private List<LineItem> lineItems; private Association<Customer, CustomerId> customer; public Order(CustomerId customerId) { this.id = OrderId.of(UUID.randomUUID()); this.customer = Association.forId(customerId); } @Value @RequiredArgsConstructor(staticName = "of") @NoArgsConstructor(force = true) public static class OrderId implements Identifier { private static final long serialVersionUID = …; private final UUID orderId; } }
33. @Entity @NoArgsConstructor(force = true) @EqualsAndHashCode(of = "id") @Table(name = "SAMPLE_ORDER") @Getter public class Order implements AggregateRoot<Order, OrderId> { private final @EmbeddedId OrderId id; @OneToMany(cascade = CascadeType.ALL) private List<LineItem> lineItems; private Association<Customer, CustomerId> customer; public Order(CustomerId customerId) { this.id = OrderId.of(UUID.randomUUID()); this.customer = Association.forId(customerId); } @Value @RequiredArgsConstructor(staticName = "of") @NoArgsConstructor(force = true) public static class OrderId implements Identifier { private static final long serialVersionUID = …; private final UUID orderId; } }
34. [INFO] □─ example.order.Order [INFO] ├─ JPA - Adding @j.p.Entity. [INFO] ├─ JPA - Adding default constructor. [INFO] ├─ JPA - Adding nullability verification using new callback methods. [INFO] ├─ JPA - Defaulting id mapping to @j.p.EmbeddedId(). [INFO] ├─ JPA - Defaulting lineItems mapping to @j.p.JoinColumn(…). [INFO] ├─ JPA - Defaulting lineItems mapping to @j.p.OneToMany(…). [INFO] ├─ Spring Data JPA - Implementing o.s.d.d.Persistable<e.o.Order$OrderIdentifier>. [INFO] └─ Spring JPA - customer - Adding @j.p.Convert(converter=…). Meanwhile in your IDE…
35. @Entity @NoArgsConstructor(force = true) @EqualsAndHashcode(of = "id") @Table(name = "SAMPLE_ORDER") @Getter public class Order { private final @EmbeddedId OrderId id; @OneToMany(cascade = CascadeType.ALL) private List<LineItem> lineItems; private CustomerId customerId; public Order(Customer customer) { this.id = OrderId.of(UUID.randomUUID()); this.customerId = customer.getId(); } @Value @RequiredArgsConstructor(staticName = "of") @NoArgsConstructor(force = true) public static class OrderId implements Serializable { private static final long serialVersionUID = …; private final UUID orderId; } } @Table(name = "SAMPLE_ORDER") @Getter public class Order implements AggregateRoot<Order, OrderId> { private final OrderId id; private List<LineItem> lineItems; private Association<Customer, CustomerId> customer; public Order(CustomerId customerId) { this.id = OrderId.of(UUID.randomUUID()); this.customer = Association.forId(customerId); } record OrderId(UUID orderId) implements Identifier {} }
36.  Decomposition
37. A B
38. A B & Risk of Change Scope of Change?
39. Infrastructure Application Domain
40.   ✉  Application Domain Infrastructure
41.   ✉  Application Domain Infrastructure
42.   ✉  Domain Application   ✉  Infrastructure Domain Application   ✉  Infrastructure Domain Application Infrastructure
43.       ✉  ✉  ✉  Infrastructure Infrastructure Domain Domain Domain Application Application Application Infrastructure
44.         ✉  ✉  ✉    Infrastructure Infrastructure Domain Domain Domain Application Application Application Infrastructure
45. Module Module Module         ✉  ✉  ✉   
46. Architectural Goal Architectural Concept Supporting Technology Development Practice supports drives selection drives selection enables supports supported by Evolvability Modules Spring Modulith
47. Spring Modulith
48. package com.acme.modulith @SpringBootApplication class MyApplication { … } Standard Spring Boot Application
49. Package Conventions  ….modulith  ….modulith.moduleA  ….modulith.moduleA.internal  ….modulith.moduleB  ….modulith.moduleB.internal Access to components residing in internal packages forbidden and checked during tests. API packages
50. Verification
51. package com.acme.modulith @SpringBootApplication class MyApplication { … } var modules = ApplicationModules.of(MyApplication.class); modules.verify(…); Standard Spring Boot Application Verifies rules for MyApplication
52. Web Business logic Data access Module A Module B Module C
53. Web Business logic Data access Module A Module B Module C
54. A B C D E Unit of… - Understanding - Consistency - Testing - Documentation - Observation
55. 🧪 Testing
56. Web Business logic Data access Module A Module B Module C @Data…Test @WebMvcTest
57. Web Business logic Data access Module A Module B Module C @Data…Test @WebMvcTest @ApplicationModuleTest
58. Subcutaneous Tests
59. Module   ✉  Module    ✉   Module    ✉  
60. Stimulate the module by… …invoking a business operation …publishing an event listened to Module    ✉  
61. @ApplicationModuleTest @RequiredArgsConstructor class OrderIntegrationTests { private final OrderManagement orders; @Test void completionCausesEventPublished(Scenario scenario) { var order = new Order(new CustomerIdentifier(UUID.randomUUID())); scenario.stimulate(() -# orders.complete(order)) .andWaitForEventOfType(OrderCompleted.class) .matchingMappedValue(OrderCompleted:%id, order.getId()) .toArrive(); } } Test scoped to the module Public API primary interaction target Stimulate module Given When Then
62. Scope of Individual Tests
63. A B C D E Unit of… - Understanding - Consistency - Testing - Documentation - Observation
64. A B C D E Unit of… - Understanding - Consistency - Testing - Documentation - Observation
65. A B C D E Unit of… - Understanding - Consistency - Testing - Documentation - Observation
66. Scope of Test Execution
67. A B C D E Change detected here. We only need to test A!
68. A B C D E Change detected in C. We need to test C and A!
70. Documentation
71. A B C D E Unit of… - Understanding - Consistency - Testing - Documentation - Observation
72. Salespoint «Component: Module» Salespoint :: Accountancy «Component: Module» Salespoint :: Catalog «Component: Module» Salespoint :: Inventory «Component: Module» Salespoint :: Order «Component: Module» Salespoint :: Payment «Component: Module» Salespoint :: Quantity «Component: Module» Salespoint :: Storage «Component: Module» Salespoint :: Time «Component: Module» Salespoint :: User Account listens t o depends on uses depends on depends on depends on listens t o depends on depends on depends on depends on uses depends on depends on
73. Salespoint «Component: Module» Salespoint :: Accountancy «Component: Module» Salespoint :: Catalog «Component: Module» Salespoint :: Inventory «Component: Module» Salespoint :: Order «Component: Module» Salespoint :: Payment «Component: Module» Salespoint :: Quantity «Component: Module» Salespoint :: Storage «Component: Module» Salespoint :: Time «Component: Module» Salespoint :: User Account listens t o depends on uses depends on depends on depends on listens t o depends on depends on depends on depends on uses depends on depends on Salespoint :: Inventory «Component: Module» Salespoint :: Catalog «Component: Module» Salespoint :: Inventory «Component: Module» Salespoint :: Order «Component: Module» Salespoint :: Quantity depends on depends on listens t o depends on depends on depends on
74. Salespoint «Component: Module» Salespoint :: Accountancy «Component: Module» Salespoint :: Catalog «Component: Module» Salespoint :: Inventory «Component: Module» Salespoint :: Order «Component: Module» Salespoint :: Payment «Component: Module» Salespoint :: Quantity «Component: Module» Salespoint :: Storage «Component: Module» Salespoint :: Time «Component: Module» Salespoint :: User Account listens t o depends on uses depends on depends on depends on listens t o depends on depends on depends on depends on uses depends on depends on Salespoint :: Inventory «Component: Module» Salespoint :: Catalog «Component: Module» Salespoint :: Inventory «Component: Module» Salespoint :: Order «Component: Module» Salespoint :: Quantity depends on depends on listens t o depends on depends on depends on Stereotypes present in the code base (via jMolecules)
75. Summary
76. Summary  To strengthen the relationship between architecture and code, find means to represent architectural and design concepts in your codebase.  Align software engineering practices with architectural abstractions.  Understand how technology choices affect the overall architecture of the system.  The scope of change drives decomposition.
77. Thank you! Questions? Oliver Drotbohm  oliver.drotbohm@broadcom.com    odrotbohm
78. Resources  Just Enough Software Architecture George Fairbanks – Book  Architecture, Design, Implementation Ammon H. Eden, Rick Kazman – Paper  Sustainable Software Architecture Carola Lilienthal – Book  Software Architecture for Developers Simon Brown – Books
79. Links  xMolecules Project website  jMolecules Project website  jMolecules Examples Example project @ GitHub  Spring Modulith Project website  Archictecturally Evident Spring Example project @ GitHub