apidays Paris 2024 - Modularizing your API with Domain Storytelling Henning Schwentner, Workplace Solutions

Starring With Directed by as Written by

@hschwentner

Foto: Rameessos/Wikipedia

@hschwentner Spark a fire ! Tell a story " Paint
a picture #

Painting a picture "

!"# Kolleg:in gesucht (Deutschlandweit)

Story Time

@hschwentner Do I get a car for this?

Monolease

@hschwentner To split the Monolith we first have to put
it aside

thinking about business => thinking about technology to

customer tells wish for 1 salesperson signs to gives for
contract 3 risk manager contract passes on to 4 contract votes checks calculates 5 6 7 calculates to 8 2 car credit rating installment car resale value contract

@hschwentner Explained

Collaborative Modeling

Domain Expert Developer

Knowledge crunching

Collaborative Modeling User Story Mapping

@hschwentner Domain Storytelling = Pictographic Language + Workshop Format

@hschwentner The Workshop Format

@hschwentner Bring together the right people and let them tell
a story

" " Storyteller Listeners

@hschwentner HANDS OVER RISK MANAGER SALESPERSON TO CONTRACT PASSES ON
“The salesperson passes on the contract to the risk manager”

Active Listening

CONCRETE STORIES VS. ABSTRACT PROCESSES

@hschwentner The Pictographic Language

@hschwentner actor work object activity 5 sequence number

@hschwentner risk manager contract votes

@hschwentner CALCULATES GIVES INSTALLMENT CAR

@hschwentner CONTRACT CONTRACT PASSES ON SIGNS

@hschwentner person group IT system

ACTORS ONCE/ WORK OBJECTS SEVERAL TIMES SIGNS 4 FILLS OUT
5 CUSTOMER CONTRACT CONTRACT

@hschwentner ßDraw here Leave some empty space there à Annotations,
variations, and purpose Precondi?ons, assump?ons, and triggers Name of the Domain Story

PICTOGRAPHIC LANGUAGE – NO IF/SWITCH/OR actor work object activity 5
sequence number

Scenario-based modeling

Scenarios Car Leasing – The Happy Path Car Leasing –
Contract is too risky Car Leasing – Customer can’t afford installment

@hschwentner Scope

Scope Factors

@hschwentner Granularity Point in time Domain Purity

@hschwentner Granularity fine- grained coarse- grained x x x x
x x x x x x x x x x x x x x

@hschwentner A Day at the Beach ! Sea Level "
Kite Level ☁ Cloud Level $ Fish Level % Clam Level Foto: Dennis Hamilton/flickr/CC BY 2.0 Alistair Cockburn

@hschwentner Point in Time as-is to-be t

@hschwentner Point in Time now optimized t with new system

@hschwentner Domain Purity pure digitalized

@hschwentner Excercise

@hschwentner Tell domain story: - “Travel by train” - Coarse-grained
- All together Exercise

@hschwentner Tools

PowerPoint Whiteboard Kit (www.domainstorytelling.org)

@hschwentner https://egon.io

PowerPoint Whiteboard Kit (www.domainstorytelling.org)

Whiteboard Kit (www.domainstorytelling.org)

@hschwentner

@hschwentner Modes

Moderated

@hschwentner Tell domain story: - “Going to the movies” -
Coarse-grained - In groups Exercise

@hschwentner Purposes

@hschwentner draw boundaries learn language work on requirements implement domain
model find shadow IT …

@hschwentner Learning Domain Language

CUSTOMER TELLS WISH FOR 1 SALESPERSON SIGNS TO GIVES FOR
CONTRACT 3 RISK MANAGER CONTRACT PASSES ON TO 4 CONTRACT VOTES CHECKS CALCULATES 5 6 7 CALCU- LATES TO 8 2 CAR CREDIT RATING INSTALLMENT CAR RESALE VALUE CONTRACT INSTALLMENT: THE MONTHLY PAYMENT OF THE CUSTOMER

@hschwentner Drawing Boundaries

Bundesarchiv, Bild 173-1282 / Helmut J. Wolf / CC-BY-SA 3.0

@hschwentner Scope: coarse-grained to-be (i.e. optimized) pure

Which activities belong together (from an actor’s perspective)?

CONTRACT 3 RISK MANAGER CONTRACT PASSES ON TO 4 CONTRACT VO TES CHECKS CALCU LATES 5 6 7 CALCU- LATES TO 8 2 CAR CREDIT RATING INSTALLMENT CAR RESALE VALUE CONTRACT SALES RISK ASSESSMENT

CONTRACT 3 RISK MANAGER CONTRACT PASSES ON TO 4 CONTRACT VO TES CHECKS CALCU LATES 5 6 7 CALCU- LATES TO 8 2 CAR CREDIT RATING INSTALLMENT CAR RESALE VALUE CONTRACT SALES Group the sentences • Boundary around activites and work objects • Keep actors outside boundaries Give a name to the group RISK ASSESSMENT

SALES RISK ASSESSMENT

@hschwentner Naming Subdomains Express what is done Verbs turned into
nouns Often: -ing-form Anti-pattern: name of work object as name for subdomain

@hschwentner Naming Subdomains— Examples Price calculation Risk assessment Maneuver
planning Customer Car Price Payment Car inspection

Indicators: 1) Actor produces result on their own 2) One-way
informa<on flow 3) Different triggers (<me vs. on demand) 4) Ac<vi<es suppor<ng something that is not in the picture 5) Difference in language 6) Different use of the same thing Ask your domain experts!

@hschwentner Draw Boundaries: - “Traveling by train” - All together
Exercise

@hschwentner Draw Boundaries: - “Going to the movies” - In
groups Exercise

@hschwentner From Coarse-Grained to Fine-Grained

CONTRACT 3 CALCU- LATES TO 8 2 CAR INSTALLMENT CAR CONTRACT SALES salesperson fills out 1 contract car model w ith price and

salesperson fills out 1 2 interest from contract price car
model calculates 3 offers installment signs w ith and contract for price and customer contract 3

@hschwentner Tell domain story: - “Validate train ticket” - Fine-grained
- All together Exercise

@hschwentner Tell domain story: - “Selling movie tickets” - Fine-grained,
pure, as-is - In groups Exercise

@hschwentner Working with Requirements

@hschwentner From Domain Story to User Story

SALESPERSON CUSTOMER TELLS WISH FOR 1 SIGNS TO GIVES FOR
CONTRACT 3 RISK MANAGER CONTRACT PASSES ON TO 4 CONTRACT VOTES CHECKS CALCULATES 5 6 7 CALCU- LATES TO 8 2 CAR CREDIT RATING INSTALLMENT CAR RESALE VALUE CONTRACT TELL WISH FOR CAR CALCULATE INSTALLMENT

SALESPERSON CUSTOMER TELLS WISH FOR 1 SIGNS TO GIVES FOR
CONTRACT 3 RISK MANAGER CONTRACT PASSES ON TO 4 CONTRACT VOTES CHECKS CALCULATES 5 6 7 CALCU- LATES TO 8 2 CAR CREDIT RATING INSTALLMENT CAR RESALE VALUE CONTRACT AS CUSTOMER I WANT TO TELL WHAT KIND OF CAR I NEED SO THAT THE CAR IS NOT TOO EXPENSIVE AS SALESPERSON I WANT TO CALCULATE THE CONTRACT SO THAT I CAN FULFILL MY CLIENT‘S WISH

@hschwentner From Domain Story to User Story Map

@hschwentner Coarse-Grained Domain Story as Backbone for User Story Map

@hschwentner TELL WISH FOR CAR CALCULATE INSTALLMENT SIGN CONTRACT PASS
ON CONTRACT

@hschwentner WISH CAR CALCULATE INSTALLMENT SIGN CONTRACT PASS O CONTRA
CALCULATE INSTALLMENT FOR NEW CUSTOMER CALCULATE INSTALLMENT FOR EXISTING CUSTOMER

@hschwentner Write user stories: - “Selling movie tickets” - In
groups Exercise

@hschwentner Modeling in Code

salesperson ﬁlls out 1 2 interest from contract price car
model calculates 3 offers installment signs w ith and contract for price and customer contract 3

@hschwentner How do we design a program for that?

@hschwentner #dddesign

-DRIVEN DESIGN

Software Domain

@hschwentner From Domain Story to Code

«Entity» Contract fillOut(:CarModel, :Price) calculateInstallment(:Interest) salesperson ﬁlls out 1 2
interest from contract price car model calculates 3 offers installment signs w ith and contract for price and customer contract 3 sign()

«En>ty» Contract ﬁllOut(:CarModel, :Price) calculateInstallment(:Interest) sign() «Value Object» CarModel «Value
Object» Price «Value Object» Interest

class Contract { public Contract(CarModel carModel, Amount price) //... public
void calculateInstallment(Interest interest) //... public void sign(SignDate date) //... }

import org.jmolecules.annotations.ddd.Entity; @Entity class Contract { public Contract(CarModel carModel, Amount
price) //... public void calculateInstallment(Interest interest) //... public void sign(SignDate date) //... }

import org.jmolecules.annotations.ddd.Entity; @Entity class Contract { public Contract(CarModel carModel, Amount
price) //... public void calculateInstallment(Interest interest) //... public void sign(SignDate date) //... } record CarModel(String name){}

import org.jmolecules.annotations.ddd.*; @Entity class Contract { public Contract(CarModel carModel, Amount
price) //... public void calculateInstallment(Interest interest) //... public void sign(SignDate date) //... } @ValueObject record CarModel(String name){}

@Entity class Contract { public Contract(CarModel carModel, Amount price) //...
public void calculateInstallment(Interest interest) //... public void sign(SignDate date) //... } @ValueObject record CarModel(String name){} @ValueObject record Amount(int cents, Currency currency){} @ValueObject enum Currency{ EUR, GBP, USD }

public void sign(SignDate date) //... } @ValueObject record CarModel(String name){}
@ValueObject record Amount(int cents, Currency currency){} @ValueObject enum Currency{ EUR, GBP, USD } // ...

Object orientation

LeasingNinja https://leasingninja.io

@hschwentner LeasingNinja.io

@hschwentner Derive Domain Model: - “Traveling by train” - From
fine-grained stories - All together Exercise

@hschwentner Derive Domain Model: - “Going to the movies” -
From ﬁne-grained stories - In groups Exercise

@hschwentner Cutting the Monolith

@hschwentner Brownfield

@hschwentner How to split the monolith

1) How should it be? 2) How is it? 3)
How to move the “is” to the “ideal”? RISK MANAGE- MENT SALES

1) How should it be? 1) Domain Re-Discovery 2) “ideal”
context map 2) How is it? 1) Architecture Analysis 2) As-is context map 3) How to move the “is” to the “ideal”? 1) Compare 2) Create List of Refactorings 4) Do the move 1) Extract a suppor<ng domain to learn 2) Then extract core(s)

old old old old new new new new “just flip
the lever” 1 2 3 4 5 a.k.a. big bang replacement

old old old new new new new 2 3 4
5 old 1

Strangler Fig Application

Lesson: is better than Strangler Fig Application Big Bang Replacement

<<Entity>> Contract sign() SALES RISK ASSESSMENT <<En$ty>> Contract sign() vote()
… BIG BALL OF MUD <<Entity>> Contract vote()

Domain-Driven Refactorings • Strategic • Socio-Technical • Tactical (Against Model
Anemia) • Tactical (Against Big Ball of Mud)

Domain-Driven Refactorings • Strategic • Carve Out Bounded Context •
Socio-Technical • Form Cross-Functional Team • Tactical (Against Model Anemia) • Tactical (Against Big Ball of Mud) • Extract Specialized Entity • Extract Specialized Data Model

Read on at: https://hschwentner.io/domain-driven-refactorings

@hschwentner Consulting

@hschwentner Conclusion

@hschwentner Further Reading

@hschwentner https://domainstorytelling.org

Get it at: https://hschwentner.io

@hschwentner LeasingNinja.io

May 6th-8th 2024 Vienna, Austria The Collaborative Modeling Unconference comocamp.org
Event Storming User Story Mapping Event Modeling Impact Mapping Domain Storytelling Storystorming Context Mapping Example Mapping etc.

@hschwentner

Bibliography Baas-Schwegler, Kenny and João Rosa (eds.). Visual Collaboration Tools.
Self-published, Leanpub, last updated August 7, 2020. Beck, Kent et al. Manifesto for Agile Software Development. 2001. Brandolini, Alberto. Introducing EventStorming. Self-published, Leanpub, last updated February 12, 2021. Conway, Melvin E. “How Do Committees Invent?” Datamation 14, no. 5 (April 1968): 28–31. Evans, Eric. Domain-Driven Design: Tackling Complexity in the Heart of Software. Boston: Addison-Wesley, 2004. Foote, Brian and Joseph Yoder. “Big Ball of Mud.” PLoP ’97, Monticello, IL, September 1997. Fowler, Martin. “Strangler Fig Application.” Bliki, June 29, 2004. Hofer, Stefan and Henning Schwentner. Domain Storytelling: a Collaborative, Visual, and Agile Way to Develop Domain- Driven Software. Boston: Addison-Wesley, 2022. Patton, Jeff. User Story Mapping: Discover the Whole Story, Build the Right Product. Sebastopol, CA: O’Reilly, 2014.

Henning Schwentner ⌂ https://hschwentner.io @hschwentner [email protected] Kolleg:in gesucht (Deutschlandweit)

@hschwentner Appendix

@hschwentner What about Event Storming?

apidays Paris 2024 - Modularizing your API with...

apidays Paris 2024 - Modularizing your API with Domain Storytelling Henning Schwentner, Workplace Solutions

More Decks by apidays

Other Decks in Programming

Featured

Transcript