Let's imagine ...

We are a startup company that wants to create a web application for doctor offices.

The following scenario is fictional, simplified on purpose.

Building the right thing, the right way

Before jumping into code, let's explore some ways to go from a business idea to a well-designed API.

We'll cover:

• Understanding user needs
• Modeling the business domain
• Designing user stories
• Collaborative refinement
• API design

Part 1: Context & Discovery

Value Proposition

How does a doctor office work today?

What value can our application bring to a doctor office?

Value Proposition Canvas

A strategic tool to ensure your product creates value for your customers.

Two parts:

1. Customer Profile: Understanding the customer
2. Value Map: How your product creates value

Goal: Achieve Fit between what customers need and what you offer.

Customer Profile: Dr. Thomas

Customer Jobs - What is Dr. Thomas trying to accomplish?

• Provide quality care to patients
• Keep accurate medical records
• Manage patient appointments efficiently
• Access patient history quickly during consultations

Customer Profile: Dr. Thomas (cont.)

Pains - What frustrates Dr. Thomas today?

• Time wasted searching for physical patient folders
• Limited storage space for growing number of files
• Risk of losing documents (damage, misplacement)
• Difficulty finding specific information within thick folders
• No backup if fire or water damage occurs

Customer Profile: Dr. Thomas (cont.)

Gains - What would make Dr. Thomas's life easier?

• Quick access to any patient record
• Easy search by patient name, SSN, or date of birth
• More time for patients, less for administration
• Secure backup of all medical data
• Ability to update records instantly
• Free up physical office space

Value Map: Practice Manager

Value Proposition Fit

The Fit:

Doctors need to spend less time on paperwork and more time with patients.

Practice Manager digitizes patient records, making them instantly searchable and always accessible.

Result:

• Less time searching for folders
• More time for patients
• Better quality of care

Discovery & User Research

Why do Discovery?

Before building anything, we need to deeply understand our users.

Goals:

• Understand real user needs (not assumed needs)
• Identify pain points in current workflows
• Avoid building the wrong thing
• Validate our assumptions

Principle: Build what users need, not what we think they need.

Discovery Techniques

User Interviews

• Direct conversations with potential users
• Open-ended questions about their workflow
• Understand their goals, frustrations, and context

Observation / Shadowing

• Watch users in their natural environment
• See how they actually work (vs. how they say they work)
• Identify inefficiencies they may not mention

Analyzing Existing Systems

• Review current tools and processes
• Identify what works and what doesn't
• Look for workarounds users have created

A Day with Dr. Thomas

We shadowed Dr. Thomas for a full day. Here's what we observed:

Key Pain Points Identified (1/2)

From our discovery work, we identified critical issues:

Time Inefficiency

• 15-20 minutes per day searching for folders
• 30 minutes per day on manual filing and organization
• Must write notes after each patient before seeing the next one
• Patients wait longer between consultations
• Cumulative time loss: 1-2 appointment slots per day

Storage & Space

• Archive room takes up valuable office space
• Boxes of old records stacked in hallways (fire hazard)

Key Pain Points Identified (2/2)

Risk & Security

• No backup if documents are lost or damaged
• Folders sometimes taken home (GDPR concern)
• Confidential info left on desks

Information Retrieval

• Hard to find specific test results in thick folders
• No way to search across patients (e.g., "all patients with condition X")

As-Is vs To-Be Analysis

As-Is: Current Workflow

Patient Consultation Process (Current State)

Patient arrives
    ↓
Search for physical folder (5-10 min) 
    ↓
Retrieve folder from archive room
    ↓
Consultation (review folder during visit)
    ↓
Write notes by hand (3-5 min) 
    ↓
Patient waits for next appointment slot
    ↓
File folder back in archive (2-3 min) 

Pain Points:

• Multiple time-consuming manual steps
• Patient waiting time between steps
• Physical movement required (archive room)
• Risk of misplacement at each step

To-Be: Target Workflow

Patient Consultation Process (Future State)

Patient arrives
    ↓
Open digital patient record (10 seconds) 
    ↓
Consultation (all info on screen, add notes in real-time)
    ↓
Auto-save 
    ↓
Next patient immediately

Benefits:

• Instant access to patient data
• No waiting time for note-taking
• Real-time updates during consultation
• Automatic backup and storage
• Can access from anywhere

Gap Analysis: What We Need to Build

Time Savings: ~15-20 minutes per patient = 1-2 extra appointments/day
Revenue Impact: +10-15% capacity increase

Part 2: Domain Modeling

Domain-Driven Design (DDD)

An approach to software development that focuses on:

• Understanding the business domain deeply
• Creating a shared language between technical and business teams
• Modeling software to match business reality

We'll introduce DDD concepts progressively as we need them.

The Power of Ubiquitous Language

Why a Common Language Matters

The Problem:

• Developers speak in technical terms (User, Record, Entity, CRUD)
• Business experts speak in domain terms (Patient, Medical Folder, Consultation)
• Misunderstandings lead to wrong features being built

The Solution: Ubiquitous Language

• Everyone uses the same vocabulary
• The language comes from the business domain
• The code uses the same terms as the business
• No translation needed between business and code

Golden Rule: If a business expert wouldn't say it, don't use it in your code.

Building Our Ubiquitous Language

For Practice Manager, let's identify our domain vocabulary:

Important: These terms must appear in:

• Conversations between team members
• Code (class names, variables, functions)
• API endpoints and documentation, User interface

Exercise: Find the Domain Terms (1/2)

Look at this requirement:

"When a new person comes to the office, Dr. Thomas needs to register them in the system with their personal information."

Bad (Technical Language):

POST /users
createUser(data)
class User { userId, name }

Exercise: Find the Domain Terms (2/2)

Good (Ubiquitous Language):

POST /patients
registerPatient(patientData)
class Patient {
  patientId,              // System-generated unique ID
  socialSecurityNumber,   // Business data (not unique!)
  name,
  birthDate
}

Key Insight: Code that speaks the business language is easier to understand and maintain.
Note: PatientId is the unique identifier; SSN is important business data but not unique.

Event Storming

What is Event Storming?

A collaborative workshop technique to explore complex business domains

Key Characteristics:

• Brings together developers, domain experts, and stakeholders
• Uses colored sticky notes on a large timeline
• Focuses on business events (things that happen in the domain)
• Visual and interactive
• Fast way to build shared understanding

Created by: Alberto Brandolini

Goal: Rapidly explore and model a business domain by discovering the events that occur.

Event Storming Building Blocks

We'll use three main building blocks:

Pattern: Actor → performs Command → triggers Event(s)

Note: There are more building blocks in full Event Storming, but we'll keep it simple.

Let's practice Event Storming

Working in groups, model the Practice Manager application using the Event Storming technique.

Consider these key user flows:

• A new patient comes to the office for the first time
• An existing patient returns for a follow-up visit
• Doctor needs to add a new document (lab result, x-ray, etc.)
• Doctor needs to retrieve a specific document
• Doctor searches for a patient

Remember the pattern:
[Actor] → performs Command → triggers Event(s)

Output: Timeline of events on sticky notes (miro, excalidraw, ...)

Benefits of Event Storming

Why is this valuable?

Shared Understanding

• Everyone sees the same business process
• Developers understand the domain deeply
• Domain experts learn about technical constraints

Discover Complexity Early

• Identify areas where things get complicated
• Surface conflicting understandings
• Find missing processes or edge cases

Foundation for Next Steps

• Events reveal natural boundaries (future Bounded Contexts)
• Commands become potential API operations
• Timeline shows user journeys (future User Stories)

Speed: Can model a complex domain in hours, not weeks.

From Events to Domain Structure

From Event Storming to Bounded Contexts

Our Event Storming revealed natural groupings of related events.

Observation: Events tend to cluster around specific concepts:

• All patient-related events (Patient Registered, Patient Info Updated)
• All document-related events (Document Added, Document Retrieved)
• All consultation-related events (Consultation Started, Notes Recorded)

DDD Concept: Bounded Context

• A boundary within which a particular domain model is defined
• Has its own Ubiquitous Language
• Clear responsibility and cohesion

Analogy: Like departments in a company - each has its own focus and vocabulary.

Bounded Contexts for Practice Manager

Based on our Event Storming, we identify three Bounded Contexts:

For our MVP: We'll focus on Patient Management, Document Management and Consultation Management.

Future: Appointment scheduling, billing, prescriptions (separate contexts).

DDD Building Blocks: Aggregates & Entities

Now let's structure the data within each context.

Entity

• An object with a unique identity
• Identity persists over time
• Example: A Patient is the same person even if their address changes

Value Object

• An object defined by its attributes, not identity
• Immutable and interchangeable
• Example: An Address (two addresses with same values are equivalent)

Aggregate

• A cluster of entities and value objects treated as a single unit
• Has one Aggregate Root (the main entity)
• Maintains consistency and invariants
• Golden Rule: External objects can only reference the Aggregate Root

Aggregate Example: Patient (Patient Management Context)

Patient Aggregate
├─ Patient (Aggregate Root - Entity)
│  ├─ patientId (Identity)
│  ├─ socialSecurityNumber (Value Object)
│  ├─ name (Value Object)
│  │  ├─ firstName
│  │  └─ lastName
│  ├─ birthDate (Value Object)
│  ├─ contactInfo (Value Object)
│  │  ├─ address (Value Object)
│  │  ├─ phoneNumber (Value Object)
│  │  └─ email (Value Object)
│  └─ medicalRecordId (Reference to Medical Record Aggregate)

Why this structure?

• Patient is the entry point (Aggregate Root)
• Name, Address are Value Objects (no identity, just values)
• Medical Record is a separate Aggregate (too complex to be inside Patient)
• Changes to Patient info don't affect Medical Record consistency

From Domain Model to Implementation

How DDD guides our technical decisions:

Bounded Contexts → Modules/Packages

/patient-management
/document-management
/consultation

Each module encapsulates its own logic and data (we'll see the internal structure during implementation).

Aggregates → API Resources

• Patient Aggregate → /patients API resource
• Document Aggregate → /documents API resource

Entities → Database Tables

• Patient Entity → patients table
• Value Objects → Embedded in entity table or separate tables

Domain Events → Event-driven architecture

• (Patient Registered) → Triggers creation of Medical Record
• (Document Added) → Triggers indexing for search

Exercise: Implement the Patient Management and Document Management Bounded Contexts based on our domain model.