Real-World to Code - Learning Module

Loading content...

0/246

Validating Design Against Requirements

The Design Verification Gap

You've spent days carefully designing a domain model. Classes are well-named, relationships are clear, behavior is properly encapsulated. The code is elegant. You're proud of it.

Then the product manager asks: "Can a premium customer split an order across multiple shipping addresses?" You realize there's no way to model that in your design. The elegant Order entity assumes one shipping address.

This is the design validation gap—the disconnect between what we think the design covers and what it actually covers. Closing this gap before implementation saves enormous rework costs. A design flaw discovered during coding costs 10x more to fix than one found during design review.

What You Will Learn

By the end of this page, you will have systematic techniques for validating that your domain model satisfies all requirements, methods for walking through scenarios with your design before writing code, and approaches for catching gaps in functionality, edge cases, and invariant enforcement early in the development process.

Why Formal Validation Matters

Developers often skip design validation because:

"I understand the requirements, the design is obviously right."
"We can fix it during implementation if something's missing."
"The deadline is too tight for extra validation steps."

All three are costly illusions. Requirements are frequently misunderstood, implementation "fixes" create technical debt, and rushing past validation creates more deadline pressure downstream.

The economics:

Cost to fix a design flaw during design review: ~1 hour
Cost to fix it during implementation: ~1 day
Cost to fix it after deployment: ~1 week (or more with data migration)

What Validation Catches
Gap Type	Example	Consequence if Missed
Missing entity	No `Shipment` entity when fulfillment workflow needs tracking	Major redesign mid-implementation
Missing relationship	No way to represent 'Order placed by Employee on behalf of Customer'	Workarounds that corrupt the model
Missing behavior	Order can't be split after being placed	Feature request becomes architecture change
Missing state	No 'Partially Shipped' status	Data hacks to represent state system doesn't model
Missing constraint	Nothing prevents negative inventory	Data corruption in production
Edge case gap	What if a customer has two active carts?	Undefined behavior, potential bugs

Validation is Investment, Not Overhead

The time spent validating design is typically 5-10% of total development time. The time spent fixing design flaws discovered later is typically 20-40% of total development time. Validation has one of the highest returns on investment of any software practice.

Requirements Traceability

The most straightforward validation technique is traceability—mapping each requirement to the design elements that fulfill it. If any requirement lacks a corresponding design element, the design is incomplete.

Creating a traceability matrix:

List all requirements (user stories, functional specs, business rules)
For each, identify which classes, methods, or relationships address it
Flag any requirement with no design coverage
Flag any design element with no requirement justification (potential over-engineering)

traceability_matrix.md
Markdown
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
# Requirements Traceability Matrix
 
## E-Commerce Order Management
 
| Req ID | Requirement | Design Elements | Status |
|--------|------------|-----------------|--------|
| REQ-01 | Customer can add items to cart | `Cart.add_item()`, `CartItem` | ✅ Covered |
| REQ-02 | Customer can checkout cart | `Cart.checkout()` → creates `Order` | ✅ Covered |
| REQ-03 | Order must have shipping address | `Order._shipping_address: Address` | ✅ Covered |
| REQ-04 | Premium customers can split shipments | **??? NO COVERAGE** | ❌ GAP |
| REQ-05 | System tracks inventory levels | `Product._inventory_count` | ✅ Covered |
| REQ-06 | Cannot sell more than available | `Order.confirm()` checks inventory | ✅ Covered |
| REQ-07 | Order can be cancelled before shipping | `Order.cancel()` | ✅ Covered |
| REQ-08 | Refunds require manager approval | **??? NO COVERAGE** | ❌ GAP |
| REQ-09 | Customer sees order history | `CustomerRepository.find_orders()` | ✅ Covered |
| REQ-10 | Express shipping available | `ShippingMethod` enum includes EXPRESS | ✅ Covered |
 
## Identified Gaps
 
### REQ-04: Split Shipments
**Problem**: Current `Order` has single `shipping_address`. Premium customers need 
multiple addresses for partial shipments.
 
**Proposed Solution**: 
- Introduce `Shipment` entity (not just a status)
- `Order` has many `Shipment`s
- Each `Shipment` has its own address and `OrderItem`s
- Add `Order.split_to_shipments()` method
 
### REQ-08: Refund Approval
**Problem**: No approval workflow exists. `Order.refund()` currently executes immediately.
 
**Proposed Solution**:
- Introduce `RefundRequest` entity with PENDING/APPROVED/DENIED states
- `Order.request_refund()` creates RefundRequest
- `RefundRequest.approve(manager)` required before funds movement

The discipline:

For every requirement in your spec, you should be able to point to specific code that implements it. If you can't, either:

The design is incomplete and needs extension
The requirement should be deferred (consciously, not by accident)
The requirement is actually covered by composition of existing elements (document how)

This process often reveals requirements that seem covered but actually aren't. "Order history" seems covered by storing orders, but does your design support querying by date range? By status? Pagination for customers with thousands of orders?

Non-Functional Requirements Too

Traceability applies to non-functional requirements as well. If the system needs to 'handle 1000 concurrent users,' which design choices support that? If 'data must be encrypted at rest,' where is that addressed? These often get missed because they don't map to obvious entities.

Scenario Walkthroughs

Beyond static traceability, scenario walkthroughs validate that the design behaves correctly. You mentally (or collaboratively) execute user scenarios against your design, verifying that each step is possible and produces the right outcome.

The process:

Select key user scenarios (happy paths + important error cases)
For each scenario, walk step-by-step through the design
At each step, ask: What method is called? What state changes? What invariants are checked?
Document any step where the answer is unclear or impossible

This is essentially "running" your design before writing code.

scenario_walkthrough.md
Markdown
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
# Scenario Walkthrough: Customer Purchases with Promotion
 
## Actors
- **Customer**: Sarah (premium member)
- **System**: E-commerce platform
 
## Preconditions  
- Sarah is logged in (Session exists with customer_id)
- Cart contains 3 items totaling $150
- Active promotion: "20% off orders over $100"
 
## Scenario Steps
 
### Step 1: Sarah views cart
| Action | cart = CartRepository.find_by_customer(sarah.id) |
|--------|--------------------------------------------------|
| Response | Cart with 3 CartItems, subtotal=$150 |
| Validation | ✅ Cart.subtotal() sums item prices correctly |
 
### Step 2: System applies promotions
| Action | promotions = PromotionService.find_applicable(cart) |
|--------|-----------------------------------------------------|
| Response | List containing "20% off over $100" promotion |
| Question | ❓ How does PromotionService access cart details? |
| Answer | Via Cart.subtotal() and Cart.items - both public |
| Validation | ✅ Promotion eligibility can be checked |
 
### Step 3: Sarah proceeds to checkout
| Action | order = cart.checkout(shipping_address, promotions) |
|--------|------------------------------------------------------|
| Response | New Order in PENDING state |
| Transformation | Cart → Order with OrderItems, promotions applied |
| Question | ❓ Does Order store promotions applied? |
| Answer | ⚠️ NO - Order only has final_total. Audit trail lost! |
| **GAP FOUND** | Need OrderPromotion join or promotion_code on Order |
 
### Step 4: Sarah enters payment
| Action | order.add_payment_method(card_details) |
|--------|----------------------------------------|
| Response | PaymentMethod attached to Order |
| Question | ❓ Is this the right design? |
| Answer | ⚠️ CONCERN - Storing card in Order violates PCI |
| **GAP FOUND** | Should reference payment_token, not card details |
 
### Step 5: Sarah confirms order
| Action | order.confirm() |
|--------|-----------------|
| Business Rules | Checks: inventory available, payment valid, address valid |
| State Change | Order.status → CONFIRMED |
| Side Effects | Inventory decremented, confirmation email triggered |
| Question | ❓ Who triggers the email? |
| Answer | ⚠️ UNCLEAR - Not in Order behavior |
| **GAP FOUND** | Need event/callback mechanism for side effects |
 
### Step 6: Order is fulfilled (later)
| Action | order.ship(tracking_number) |
|--------|----------------------------|
| Precondition | status == CONFIRMED |
| State Change | status → SHIPPED, tracking stored |
| Validation | ✅ Covered in current design |
 
## Gap Summary
1. **Order doesn't track which promotions were applied** - Need for audit trail
2. **Payment storage violates PCI** - Need tokenization pattern
3. **Side effects unclear** - Need domain events or hooks

Key questions at each step:

Can we do this? Is there a method/attribute that enables this action?
Is the state transition valid? Does the design prevent invalid transitions?
Are invariants maintained? After this step, is the system still consistent?
Who is responsible? Which object/service handles this step?
What could go wrong? How does the design handle failures?

Walk Through With Others

Scenario walkthroughs are more effective with 2-3 people. Different perspectives catch different gaps. The person who designed the system often has blind spots; they unconsciously fill in missing pieces. Fresh eyes spot what's actually missing.

Invariant Verification

Invariants are conditions that must always be true for domain objects. Validating that your design enforces all required invariants prevents data corruption and undefined behavior.

Types of invariants:

Entity invariants: Rules about a single object's state
Aggregate invariants: Rules about related objects in an aggregate
System invariants: Rules across the entire system
Temporal invariants: Rules about state over time

invariant_checklist.py
Python
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
# Invariant Documentation and Verification
 
class Order:
    """
    INVARIANTS (must always be true):
    
    1. Order must have at least one OrderItem
       - Enforced by: __init__ raises if items empty
       - Risk: Can items be removed after creation? Need remove_item guard.
    
    2. Order.total == sum of OrderItem.subtotal (minus discounts)
       - Enforced by: total is calculated property, not stored
       - Risk: None if truly calculated. Verify no stored total field.
    
    3. status transitions follow: PENDING → CONFIRMED → SHIPPED → DELIVERED
       - Enforced by: Each state change method checks current state
       - Risk: Is there a way to set status directly? Audit for set_status().
    
    4. Cancelled orders cannot transition to any other state
       - Enforced by: All transition methods check status != CANCELLED
       - Risk: Need to verify ALL methods include this check.
    
    5. Shipped orders must have tracking_number
       - Enforced by: ship() requires tracking_number parameter
       - Risk: What if ship() is called with empty string?
    """
    
    def __init__(self, order_id: str, items: list["OrderItem"]):
        # INVARIANT 1: Enforced at creation
        if not items:
            raise OrderException("Order must have at least one item")
        
        self._items = list(items)
        self._status = OrderStatus.PENDING
        self._tracking_number: str | None = None
    
    def remove_item(self, item_id: str) -> None:
        """Remove an item from the order."""
        # INVARIANT 1: Must maintain at least one item
        if len(self._items) <= 1:
            raise OrderException("Cannot remove last item; cancel order instead")
        
        self._items = [i for i in self._items if i.item_id != item_id]
    
    @property
    def total(self) -> Money:
        # INVARIANT 2: Total is calculated, not stored (always consistent)
        return sum((item.subtotal for item in self._items), Money.zero())
    
    def confirm(self) -> None:
        # INVARIANTS 3, 4: Transition guards
        self._require_status(OrderStatus.PENDING)
        self._status = OrderStatus.CONFIRMED
    
    def ship(self, tracking_number: str) -> None:
        # INVARIANT 3: Transition guard
        self._require_status(OrderStatus.CONFIRMED)
        
        # INVARIANT 5: Tracking required
        if not tracking_number or not tracking_number.strip():
            raise OrderException("Tracking number required for shipment")
        
        self._tracking_number = tracking_number
        self._status = OrderStatus.SHIPPED
    
    def cancel(self, reason: str) -> None:
        # INVARIANT 3 (modified for cancel): Can cancel from PENDING or CONFIRMED
        if self._status not in (OrderStatus.PENDING, OrderStatus.CONFIRMED):
            raise OrderException(f"Cannot cancel order in {self._status} state")
        
        self._status = OrderStatus.CANCELLED
        self._cancellation_reason = reason
    
    def _require_status(self, required: OrderStatus) -> None:
        """Guard method for state transitions."""
        if self._status == OrderStatus.CANCELLED:
            # INVARIANT 4: Cancelled is terminal
            raise OrderException("Cancelled orders cannot be modified")
        if self._status != required:
            raise OrderException(
                f"Expected {required.value}, but order is {self._status.value}"
            )
 
 
# Invariant verification checklist
 
INVARIANT_CHECKLIST = """
For each invariant, verify:
 
☐ Where is it enforced? (constructor, method guard, property)
☐ Are there any bypass paths? (direct field access, reflection, setters)
☐ What happens if enforcement fails? (exception, silent corruption)
☐ Is enforcement tested? (unit tests specifically for invariants)
☐ Is the invariant documented? (docstring, comments)
 
For aggregate invariants across multiple objects:
 
☐ Which object is responsible for enforcement? (aggregate root)
☐ Can related objects be modified outside the aggregate? (encapsulation leak)
☐ Are database constraints a backup enforcement? (belt AND suspenders)
"""

The invariant validation process:

List all business rules that must never be violated
Classify each as entity, aggregate, or system invariant
For each invariant, trace enforcement to specific code
Challenge each enforcement — What if someone bypasses it?
Document as tests — Invariant tests become regression guards

Beware Framework Bypass

ORMs can violate invariants by hydrating objects without calling constructors. Serialization libraries can set private fields. Reflection bypasses all guards. Defense in depth: have database constraints as backup, and test invariants with integration tests that include real persistence.

Edge Case Exploration

Edge cases are where designs most often fail. Systematic exploration of boundary conditions and unusual scenarios reveals gaps that happy-path thinking misses.

Edge case categories:

Boundary values: Empty collections, zero quantities, maximum lengths
Timing: Concurrent operations, stale data, clock skew
Unusual actors: Admin vs user, system processes, integrations
State combinations: Objects in unexpected states or state pairs
Failure scenarios: Network errors, partial failures, retries

Edge Case Exploration Questions

•What if the collection is empty? Cart with no items? Order with no shipments? Team with no members?
•What if quantities are zero or negative? Order for 0 items? Refund of $0? Inventory count of -5?
•What if it happens twice? Order confirmed twice? Payment processed twice? Email sent twice?
•What if timing is unusual? Checkout starts before promotion expires, finishes after? Order placed at midnight boundary?
•What if permissions vary? Can regular user do this? Admin? System process? What if role changes mid-operation?
•What if related entities change? Customer deleted while order in progress? Product discontinued mid-cart?
•What if there's a failure partway? Payment succeeds but inventory decrement fails? Email fails but order persists?
•What if there are concurrent operations? Two people checkout the last item? Same cart edited simultaneously?

edge_case_documentation.md
Markdown
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
# Edge Case Analysis: Inventory Management
 
## Entity: Product (with inventory_count)
 
### Boundary Values
 
| Case | Question | Design Answer |
|------|----------|---------------|
| inventory_count = 0 | Can product be viewed? Listed? Added to cart? | Viewable + listed, cannot add to cart |
| inventory_count < 0 | Can this state exist? | NO - decrement check in Order.confirm() |
| Very large count | Any max limit? Integer overflow? | Use int64, no practical limit |
 
### Timing Scenarios
 
| Case | Question | Design Answer |
|------|----------|---------------|
| Two orders for last item | Who wins? Loser's experience? | First to confirm() wins, second gets InventoryException |
| Restock during order | If restocked after "out of stock" error? | Customer must retry. Consider: queue backorders? |
| Inventory update during checkout | Cart shows "3 available" but only 1 when confirm | confirm() re-checks; customer gets partial fill or error |
 
### Failure Scenarios
 
| Case | Question | Design Answer |
|------|----------|---------------|
| Decrement succeeds, order persist fails | Inventory forever decremented? | ⚠️ GAP - need transaction or compensation |
| Partial order fulfillment | 3 items ordered, only 2 available after race | Options: (1) reject all, (2) partial fill. Need decision. |
| Duplicate decrement (retry) | If confirm() called twice due to network timeout | Idempotency: check order already confirmed? ⚠️ GAP |
 
### Decisions Required
 
1. **Partial fulfillment policy**: Reject entire order or allow partial?
   - Recommendation: Offer customer choice, need UI design
   
2. **Backorder support**: Queue orders when OOS and fulfill later?
   - Recommendation: V2 feature, design BackorderQueue entity
   
3. **Idempotency for retries**: How to make confirm() safe to retry?
   - Recommendation: Add confirmation_token, check before processing

Edge Cases Become Tests

Every edge case you document should become a test case. This serves two purposes: (1) ensures the design actually handles the case, and (2) prevents regression if someone changes the code later. The edge case documentation becomes your test plan.

Design Review Checklist

A comprehensive design review checklist synthesizes all validation techniques into a systematic process you can apply to any domain model.

Domain Model Validation Checklist

•Entity Completeness: Every major domain noun has a corresponding class
•Value Object Usage: Compound attributes are modeled as immutable Value Objects
•Relationship Accuracy: All domain relationships captured with correct cardinality
•Behavior Placement: Business operations are methods on domain objects, not external services
•Invariant Enforcement: All business rules are enforced at construction and mutation
•State Machine Clarity: Entity lifecycles are explicit with clear valid transitions
•Aggregate Boundaries: Clusters of related objects have a clear root and boundary

Requirement Coverage Checklist

•Traceability Complete: Every requirement maps to design elements
•Scenarios Walkable: Key user journeys execute successfully against the model
•Error Paths Defined: The design handles failures explicitly, not by omission
•Edge Cases Considered: Boundary values, timing, and unusual inputs are addressed
•Non-Functional Requirements: Performance, security, and scalability concerns have design support
•Integration Points: External systems have adapter/gateway abstractions

Quality Attributes Checklist

•Testability: Domain objects can be unit tested without infrastructure
•Extensibility: Adding new behaviors doesn't require modifying existing classes
•Understandability: Class names use Ubiquitous Language readable by domain experts
•Encapsulation: Internal state is protected; mutations go through domain methods
•Consistency: Similar patterns used throughout (naming, structure, error handling)
•Documentation: Each class has docstrings explaining invariants and behavior

Review is Collaborative

The most effective design reviews involve developers, domain experts, and product stakeholders. Developers catch technical issues; domain experts catch model inaccuracies; product managers catch missing requirements. Multiple perspectives together find far more issues than any single reviewer.

Summary: Design Validation Completes the Loop

Validation is not about proving your design is perfect—it's about finding imperfections cheaply, before they become expensive to fix. The techniques in this page form a safety net that catches gaps before coding begins.

Key Takeaways

•Traceability proves coverage — Map every requirement to design elements. Gaps become visible.
•Scenario walkthroughs test behavior — "Run" the design manually before writing code.
•Invariant verification ensures correctness — Document and trace enforcement of every business rule.
•Edge case exploration prevents surprises — Systematically question boundary conditions and failures.
•Checklists create consistency — Apply the same validation rigor to every design.
•Validation pays for itself — Time invested in design validation saves 10x in implementation rework.

Module Complete:

You've now learned the complete journey from real-world concepts to validated code structures:

Identifying domain concepts and translating them to classes
Using Ubiquitous Language to ensure code speaks the domain's vocabulary
Avoiding implementation-driven design that corrupts the domain model
Validating against requirements to catch gaps before implementation

With these skills, you can create domain models that accurately represent business reality, remain maintainable as requirements evolve, and form a solid foundation for the system you build.

Module Complete

You've completed the module on Real-World to Code Translation. You now have systematic techniques for the critical skill of translating business domains into clean, correct code structures. This foundation will serve you throughout your career in software design and architecture.