ComputerConnection/logic

Business Logic Workshop: $ARGUMENTS

Turn messy real-world rules into clean, implementable logic.

---

Philosophy

• Extract before coding - Understand the rules before writing if statements
• Make implicit explicit - Business rules hide in conversations and assumptions
• Edge cases are features - The weird cases reveal the real complexity
• State is everything - Most business logic is state management
• Test with examples - Concrete scenarios validate abstract rules

---

Mode Selection

Choose your path:

A) Extract Mode (Existing Code)

You have code with business logic buried in it. Goal: document what exists.

B) Design Mode (Greenfield)

You're designing new business logic. Goal: spec before code.

C) Quick Mode (Single Rule)

You need to document one specific rule or decision.

---

Extract Mode: Documenting Existing Logic

When business logic already exists in code but isn't documented:

Step 1: Find the Logic

# Find conditionals and business decisions
grep -rn "if.*status\|if.*state\|switch" --include="*.ts" src/
grep -rn "validate\|isValid\|canDo\|allowed" --include="*.ts" src/

# Find state transitions
grep -rn "status.*=\|state.*=\|setState" --include="*.ts" src/

# Find business calculations
grep -rn "calculate\|compute\|total\|price\|amount" --include="*.ts" src/

# Find rule comments
grep -rn "business rule\|requirement\|must be\|should be\|cannot" --include="*.ts" src/

Step 2: Trace the Logic

For each piece of business logic found:

┌─────────────────────────────────────────────────────────────┐
│  EXTRACTED RULE: [Name]                                     │
├─────────────────────────────────────────────────────────────┤
│  Location: [file:line]                                      │
│  Code:                                                      │
│  ```                                                        │
│  [the actual code]                                          │
│  ```                                                        │
├─────────────────────────────────────────────────────────────┤
│  Plain English:                                             │
│  [What this rule actually means in business terms]          │
├─────────────────────────────────────────────────────────────┤
│  Inputs: [what data does it need]                           │
│  Output: [what does it produce/decide]                      │
│  Side Effects: [what else happens]                          │
├─────────────────────────────────────────────────────────────┤
│  Questions:                                                 │
│  • Is this rule documented anywhere else?                   │
│  • Is this the only place this rule is enforced?            │
│  • Are there edge cases not covered?                        │
└─────────────────────────────────────────────────────────────┘

Step 3: Verify Understanding

• [ ] Run the code with test inputs
• [ ] Check for duplicate enforcement (same rule in multiple places)
• [ ] Look for edge cases in tests
• [ ] Ask: "Why is it this way?" (git blame, ask Zach)

Step 4: Document in Canonical Location

Move the extracted understanding into proper documentation (see Phase 3: Business Rules Extraction).

---

Quick Mode: Single Rule Documentation

For documenting one rule quickly:

┌─────────────────────────────────────────────────────────────┐
│  RULE: [Name]                                               │
├─────────────────────────────────────────────────────────────┤
│  When: [condition]                                          │
│  Then: [behavior]                                           │
│  Because: [business reason]                                 │
├─────────────────────────────────────────────────────────────┤
│  Example:                                                   │
│  ✅ [valid case] → [result]                                 │
│  ❌ [invalid case] → [error/rejection]                      │
├─────────────────────────────────────────────────────────────┤
│  Enforced at: [API / UI / DB / code location]               │
│  Source: [who/what defined this rule]                       │
└─────────────────────────────────────────────────────────────┘

---

Design Mode: Full Process

Use the phases below for designing new business logic from scratch.

---

Phase 1: Domain Discovery

What Are We Modeling?

┌─────────────────────────────────────────────────────────────┐
│  DOMAIN: [Name]                                             │
├─────────────────────────────────────────────────────────────┤
│  Core Entities:                                             │
│  • [Entity 1] - [what it represents]                        │
│  • [Entity 2] - [what it represents]                        │
│  • [Entity 3] - [what it represents]                        │
├─────────────────────────────────────────────────────────────┤
│  Key Relationships:                                         │
│  • [Entity A] ──[relationship]──► [Entity B]                │
│  • [Entity C] ──[relationship]──► [Entity D]                │
├─────────────────────────────────────────────────────────────┤
│  Business Events:                                           │
│  • [Event 1] - [what triggers it]                           │
│  • [Event 2] - [what triggers it]                           │
└─────────────────────────────────────────────────────────────┘

Entity Definition Template

## Entity: [Name]

### Identity
- What uniquely identifies this entity?
- Can two entities be "the same"?

### Attributes
| Attribute | Type | Required | Rules |
|-----------|------|----------|-------|
| id | UUID | Yes | System-generated |
| name | string | Yes | 1-100 chars |
| status | enum | Yes | One of: [values] |

### Lifecycle
[Created] → [Active] → [Completed/Archived]

### Invariants (always true)
- [Rule that must never be violated]
- [Another invariant]

### Relationships
- Has many: [related entities]
- Belongs to: [parent entity]
- References: [lookup entities]

---

Phase 2: State Machine Design

Identify States

Every entity with a "status" field is a state machine.

## State Machine: [Entity]

### States
┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐
│  Draft  │──►│ Pending │──►│ Active  │──►│ Closed  │
└─────────┘   └─────────┘   └─────────┘   └─────────┘
                  │              │
                  ▼              ▼
             ┌─────────┐   ┌─────────┐
             │Rejected │   │Cancelled│
             └─────────┘   └─────────┘

State Transition Table

| From | To | Trigger | Guard | Action | |------|----|---------|-------|--------| | Draft | Pending | submit() | isValid() | notifyReviewer() | | Pending | Active | approve() | hasApprover() | sendConfirmation() | | Pending | Rejected | reject(reason) | - | notifyOwner(reason) | | Active | Closed | complete() | allTasksDone() | archive() | | Active | Cancelled | cancel(reason) | - | refund() |

Guards (Conditions for Transitions)

// Guard: Can transition from Pending → Active?
function canApprove(entity: Entity): boolean {
  return (
    entity.status === 'pending' &&
    entity.reviewer !== null &&
    entity.reviewer !== entity.owner &&
    !entity.hasBlockers()
  );
}

Actions (Side Effects on Transition)

// Action: When transitioning to Active
function onActivate(entity: Entity): void {
  entity.activatedAt = new Date();
  entity.version += 1;
  emit('entity.activated', entity);
  notifyStakeholders(entity);
}

---

Phase 3: Business Rules Extraction

Rule Catalog

Extract every business rule into explicit statements:

## Rule: [Rule Name]

### Statement
When [condition], the system shall [behavior].

### Category
[ ] Validation (data correctness)
[ ] Authorization (who can do what)
[ ] Calculation (derived values)
[ ] Workflow (process flow)
[ ] Constraint (limits/boundaries)

### Examples
✅ Valid: [example that follows the rule]
❌ Invalid: [example that violates the rule]

### Implementation
- Check in: [where in code]
- Enforced at: [API / UI / DB / all]
- Error: "[user-facing message]"

### Edge Cases
- What if [edge case]? → [handling]

### Source
- Where did this rule come from?
- Who owns it?
- When was it last verified?

Rule Matrix

For complex conditional logic:

| Condition A | Condition B | Condition C | Result | |-------------|-------------|-------------|--------| | Yes | Yes | Yes | Action 1 | | Yes | Yes | No | Action 2 | | Yes | No | Yes | Action 3 | | Yes | No | No | Error | | No | Yes | Yes | Action 4 | | No | Yes | No | Action 2 | | No | No | Yes | Error | | No | No | No | Default |

---

Phase 4: Validation Logic

Validation Layers

┌─────────────────────────────────────────────────────────────┐
│  Layer 1: Format Validation (syntactic)                     │
│  - Is it the right type?                                    │
│  - Is it within length limits?                              │
│  - Does it match the pattern?                               │
├─────────────────────────────────────────────────────────────┤
│  Layer 2: Business Validation (semantic)                    │
│  - Does it make business sense?                             │
│  - Are related values consistent?                           │
│  - Does it violate any business rules?                      │
├─────────────────────────────────────────────────────────────┤
│  Layer 3: Contextual Validation (stateful)                  │
│  - Is it valid given current state?                         │
│  - Does the user have permission?                           │
│  - Are external dependencies available?                     │
└─────────────────────────────────────────────────────────────┘

Validation Rule Template

interface ValidationRule<T> {
  name: string;
  layer: 'format' | 'business' | 'contextual';
  validate: (value: T, context?: Context) => ValidationResult;
  errorCode: string;
  errorMessage: string;
}

// Example
const orderQuantityRule: ValidationRule<Order> = {
  name: 'order-quantity-positive',
  layer: 'format',
  validate: (order) => ({
    valid: order.quantity > 0,
    field: 'quantity',
  }),
  errorCode: 'INVALID_QUANTITY',
  errorMessage: 'Order quantity must be greater than 0',
};

Validation Error Design

## Validation Error: [Code]

Field: [which field]
Message: [user-friendly message]
Hint: [how to fix it]

Triggers:
- [condition that causes this error]

Test Cases:
- Input: [invalid input] → Error
- Input: [valid input] → OK

---

Phase 5: Calculation Logic

Derived Values

Document every calculated/computed field:

## Calculation: [Field Name]

### Formula
result = [formula or algorithm]

### Inputs
| Input | Source | Type | Required |
|-------|--------|------|----------|
| [input1] | [where from] | number | Yes |
| [input2] | [where from] | number | No (default: 0) |

### Rules
- Round to: [precision]
- Null handling: [behavior]
- Edge cases: [special handling]

### Examples
| input1 | input2 | Result | Notes |
|--------|--------|--------|-------|
| 100 | 0.1 | 110 | Standard case |
| 0 | 0.1 | 0 | Zero base |
| 100 | 0 | 100 | No modifier |

### When to Calculate
- On create: [yes/no]
- On update: [which fields trigger recalc]
- On read: [calculated on-demand or stored]

Calculation Dependencies

┌──────────┐     ┌──────────┐     ┌──────────┐
│ subtotal │────►│   tax    │────►│  total   │
└──────────┘     └──────────┘     └──────────┘
     │                                  ▲
     │           ┌──────────┐          │
     └──────────►│ discount │──────────┘
                 └──────────┘

Recalculation order: subtotal → tax, discount → total

---

Phase 6: Decision Trees

For complex branching logic:

## Decision: [What decision]

                    ┌─────────────────┐
                    │ Is user premium? │
                    └────────┬────────┘
                             │
              ┌──────────────┼──────────────┐
              │ Yes          │              │ No
              ▼              │              ▼
    ┌─────────────────┐      │    ┌─────────────────┐
    │ Free shipping   │      │    │ Order > $50?    │
    └─────────────────┘      │    └────────┬────────┘
                             │             │
                             │   ┌─────────┼─────────┐
                             │   │ Yes     │         │ No
                             │   ▼         │         ▼
                             │ ┌───────────┴──┐  ┌──────────────┐
                             │ │Free shipping │  │ $5.99 shipping│
                             │ └──────────────┘  └──────────────┘

Decision Table Format

function calculateShipping(order: Order, user: User): Money {
  // Decision table implementation
  if (user.isPremium) return Money.zero();
  if (order.subtotal.gte(50)) return Money.zero();
  return Money.of(5.99);
}

---

Phase 7: Process Flows

Business Process Mapping

## Process: [Name]

### Actors
- [Actor 1]: [role]
- [Actor 2]: [role]
- System: automated steps

### Flow
┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐
│ Actor 1 │    │ System  │    │ Actor 2 │    │ System  │
│ Submit  │───►│ Validate│───►│ Approve │───►│ Execute │
└─────────┘    └─────────┘    └─────────┘    └─────────┘
                    │              │
                    ▼              ▼
               [Reject]       [Reject]
                    │              │
                    └──────┬───────┘
                           ▼
                    ┌─────────┐
                    │ Notify  │
                    │ Actor 1 │
                    └─────────┘

### Steps

| Step | Actor | Action | Input | Output | Next |
|------|-------|--------|-------|--------|------|
| 1 | User | Submit request | Form data | Request ID | 2 |
| 2 | System | Validate | Request | Valid/Invalid | 3 or END |
| 3 | Approver | Review | Request | Approved/Rejected | 4 or END |
| 4 | System | Execute | Approved request | Result | END |

### Timeouts
- Step 3: Auto-reject after 48 hours

### Exceptions
- [What could go wrong] → [How to handle]

---

Phase 8: Test Scenarios

Scenario Template

## Scenario: [Name]

### Given (Setup)
- [Entity] exists with [state]
- [Actor] has [permissions]
- [Context] is [condition]

### When (Action)
- [Actor] does [action] with [input]

### Then (Expected)
- [Entity] state is [new state]
- [Side effect] occurs
- [Response] is returned

### Edge Cases
- What if [variation]? → [expected behavior]

Test Matrix

| Scenario | Input | Pre-condition | Expected | Actual | |----------|-------|---------------|----------|--------| | Happy path | valid data | normal state | success | | | Invalid input | bad data | normal state | validation error | | | Wrong state | valid data | wrong status | state error | | | No permission | valid data | unauthorized | auth error | | | Edge case | boundary value | normal state | ? | |

---

Phase 9: Logic Documentation Output

Business Logic Spec

┌─────────────────────────────────────────────────────────────┐
│  BUSINESS LOGIC SPEC: [Domain/Process]                      │
├─────────────────────────────────────────────────────────────┤
│  Entities: [count]                                          │
│  State Machines: [count]                                    │
│  Business Rules: [count]                                    │
│  Validations: [count]                                       │
│  Calculations: [count]                                      │
├─────────────────────────────────────────────────────────────┤
│  Complexity: [Low/Medium/High]                              │
│  Coverage: [% of cases documented]                          │
└─────────────────────────────────────────────────────────────┘

Files to Generate

• domain/entities/[entity].ts - Entity definitions
• domain/rules/[domain].rules.ts - Business rules
• domain/validation/[entity].validation.ts - Validation logic
• domain/workflows/[process].workflow.ts - Process flows
• docs/business-logic/[domain].md - Human-readable spec

---

Anti-Patterns

• "It's just an if statement" (hidden complexity)
• Scattered business rules (rules in 5 different files)
• Magic numbers (what does status === 3 mean?)
• Implicit state machines (status changes without transitions)
• "The code is the documentation" (it's not)
• No test scenarios (untestable rules)

---

Output

1. Domain model with entities and relationships
2. State machines with transitions
3. Business rules catalog
4. Validation rules by layer
5. Calculation specifications
6. Decision trees for complex logic
7. Process flows
8. Test scenarios
9. Complexity assessment