Physical World and System-Independent Process Modeling

This guide explains how to model physical objects, paper-based processes, and system-independent workflow steps in Korgraph.

📋 Overview

Real-world business processes often involve:

• Physical objects (trucks, documents, packages)
• Paper-based documents (invoices, delivery notes, waybills)
• System-independent steps (loading, driving, physical handovers)
• Non-IT actors (vehicles, stations, physical locations)

Korgraph supports modeling these elements to create complete end-to-end process visualizations that bridge physical and digital worlds.

🌍 Physical World System

Concept

The "Physical World" is modeled as a special System that represents non-IT processes and objects:

• System Type: Physical (not Cloud or OnPrem)
• Purpose: Contains modules for physical objects and paper documents
• Benefits:
  • Complete process visibility (physical + digital)
  • Clear handoffs between physical and digital steps
  • Documentation of paper-based workflows

Example: Paper Module

system:
  - id: "system-physical-world"
    name: "Physische Welt"
    description: "Non-IT objects and paper-based processes"
    systemType: "Physical"
    
systemmodule:
  - id: "module-paper"
    name: "Papier"
    description: "Paper-based documents"
    systemId: "system-physical-world"

📄 Paper-Based Data Objects

Modeling Documents

Paper documents are represented as Data Objects that can flow through processes:

dataobject:
  - id: "dataobject-frachtbrief"
    name: "Frachtbrief"
    description: "Physical waybill for shipment tracking"
    
  - id: "dataobject-rechnung"
    name: "Rechnung"
    description: "Physical or digital invoice"
    
  - id: "dataobject-routerlabel"
    name: "Routerlabel"
    description: "Address label for routing"

Common Paper Documents

Logistics:

• Frachtbrief (Waybill)
• Lieferschein (Delivery Note)
• Rechnung (Invoice)
• Entladebericht (Unloading Report)
• Routerlabel (Routing Label)

Manufacturing:

• Produktionsauftrag (Production Order)
• Qualitätsprüfbericht (Quality Report)
• Materialschein (Material Slip)

Healthcare:

• Patientenakte (Patient Record)
• Laborbericht (Lab Report)
• Überweisungsschein (Referral Form)

🚛 Physical Actors

Vehicles as Actors

Vehicles (trucks, ships, trains) can be modeled as Actors:

actor:
  - id: "actor-lkw"
    name: "LKW"
    description: "Truck as transport vehicle. Can send GPS positions."
    actorType: "internal"
    parentType: "company"

Use Cases:

• GPS position reporting
• Loading/unloading events
• Maintenance triggers
• Route tracking

Stations and Locations

Physical locations are modeled as Actors:

actor:
  - id: "actor-empfangsstation"
    name: "Empfangsstation"
    description: "Receiving station for goods"
    actorType: "internal"
    parentType: "company"

Common Location Actors:

• Warehouse stations
• Loading docks
• Transfer hubs
• Customer locations
• Service centers

Human Operators

People operating physical processes:

actor:
  - id: "actor-fahrer"
    name: "Fahrer"
    description: "Truck driver responsible for delivery"
    actorType: "internal"
    
  - id: "actor-disponent"
    name: "Disponent"
    description: "Dispatcher coordinating logistics"
    actorType: "internal"

🔄 System-Independent Process Steps

What Are System-Independent Steps?

These are process steps that occur outside of IT systems:

• Physical movements (driving, walking)
• Manual handovers (document exchange)
• Physical actions (loading, unloading)
• Analog communications (verbal instructions)

Modeling Physical Steps

Use Stories to model these steps by connecting actors and objects:

story:
  # Physical handover
  - sourceElementId: "actor-fahrer"
    targetElementId: "dataobject-frachtbrief"
    label: "übergibt"
    
  # Physical action (self-referencing)
  - sourceElementId: "actor-lkw"
    targetElementId: "actor-lkw"
    label: "verlässt Beladung"
    condition: "physische Aktion"
    
  # Physical movement
  - sourceElementId: "actor-lkw"
    targetElementId: "actor-empfangsstation"
    label: "fährt zu"

Connecting Physical and Digital

Show transitions between physical and digital worlds:

story:
  # Physical document → Digital entry
  - sourceElementId: "actor-disponent"
    targetElementId: "dataobject-frachtbrief"
    label: "empfängt"
    
  - sourceElementId: "actor-disponent"
    targetElementId: "feature-tms-order-entry"
    label: "erfasst in"
    
  # Physical action → Digital tracking
  - sourceElementId: "actor-lkw"
    targetElementId: "dataobject-gps-position"
    label: "meldet"
    
  - sourceElementId: "dataobject-gps-position"
    targetElementId: "feature-tms-tracking"
    label: "an"

📖 Complete Example: Road Logistics

Scenario

Complete shipment process from physical handover to digital confirmation:

1. Driver hands waybill to dispatcher
2. Dispatcher enters data into TMS
3. Truck reports GPS position
4. Truck leaves loading area (physical)
5. Truck drives to destination (physical)
6. Driver unloads (physical)
7. Driver confirms unloading report
8. Report sent to receiving station

YAML Model

process:
  - id: "process-road-logistics-shipment"
    name: "Sendungsübergabe Road Logistik"
    description: "Complete physical and digital shipment workflow"
    processLandscapeId: "processlandscape-default"
    
story:
  # Step 1-2: Physical handover
  - sourceElementId: "actor-fahrer"
    targetElementId: "dataobject-frachtbrief"
    label: "übergibt"
    order: 1
    
  - sourceElementId: "dataobject-frachtbrief"
    targetElementId: "actor-disponent"
    label: "an"
    order: 2
    
  # Step 3: Digital data entry
  - sourceElementId: "actor-disponent"
    targetElementId: "feature-tms-order-entry"
    label: "erfasst Daten in"
    order: 3
    
  # Step 4-5: GPS tracking (physical → digital)
  - sourceElementId: "actor-lkw"
    targetElementId: "dataobject-gps-position"
    label: "meldet"
    order: 4
    
  - sourceElementId: "dataobject-gps-position"
    targetElementId: "feature-tms-tracking"
    label: "an"
    order: 5
    
  # Step 6: Physical action
  - sourceElementId: "actor-lkw"
    targetElementId: "actor-lkw"
    label: "verlässt Beladung"
    condition: "physische Aktion"
    order: 6
    
  # Step 7: Physical movement
  - sourceElementId: "actor-lkw"
    targetElementId: "actor-empfangsstation"
    label: "fährt zu"
    condition: "Umschlaglager"
    order: 7
    
  # Step 8: Physical unloading
  - sourceElementId: "actor-fahrer"
    targetElementId: "actor-lkw"
    label: "entlädt"
    order: 8
    
  # Step 9-10: Confirmation and reporting
  - sourceElementId: "actor-fahrer"
    targetElementId: "dataobject-entladebericht"
    label: "bestätigt"
    order: 9
    
  - sourceElementId: "dataobject-entladebericht"
    targetElementId: "actor-empfangsstation"
    label: "wird geschickt an"
    order: 10

💡 Best Practices

Naming Conventions

Physical World System:

• Name: "Physische Welt" or "Physical World"
• Type: Physical (not Cloud/OnPrem)
• Module: "Papier" for documents, "Transport" for vehicles

Actors:

• Use role names, not individual names
• Be specific: "LKW Fahrer" not just "Mitarbeiter"
• Include responsibilities in description

Data Objects:

• Use actual document names
• Specify if physical or digital in description
• Include purpose and handling instructions

Process Design

Clear Transitions:

• Show explicit handoffs between physical and digital
• Use condition field to annotate physical actions
• Label connections clearly (übergibt, fährt zu, meldet)

Completeness:

• Don't skip physical steps
• Include all actors (people, vehicles, locations)
• Model both directions (send and receive)

Visualization:

• Physical steps should flow logically
• Group related physical actions
• Show parallel physical and digital activities

Common Patterns

Document Digitization:

Paper Doc → Actor → Digital System Feature

Physical Tracking:

Vehicle → GPS Data → Tracking System

Handover Chain:

Actor A → Physical Object → Actor B → Digital Entry

Physical Action:

Actor → Actor (self-reference with condition)

🎯 Use Cases

Logistics & Transportation

• Shipment tracking (physical + digital)
• Route planning and execution
• Loading/unloading workflows
• Cross-docking operations
• Last-mile delivery

Manufacturing

• Production order flow (paper → digital)
• Quality inspection reports
• Material movements
• Maintenance procedures
• Shift handovers

Healthcare

• Patient admission (paper forms → EMR)
• Lab sample tracking
• Prescription flow
• Medical record transfer
• Equipment tracking

Retail

• Inventory receiving
• Return processing
• Cash handling procedures
• Store-to-warehouse transfers
• Customer pickup flow

🔗 Integration with Digital Systems

GPS and IoT Data

Model IoT device data as Data Objects:

dataobject:
  - name: "GPS Position"
    description: "Real-time vehicle location"
    
  - name: "Temperature Sensor"
    description: "Cold chain monitoring"
    
  - name: "Weight Sensor"
    description: "Loading verification"

Digital Twins

Create parallel digital representations:

# Physical truck
actor:
  - id: "actor-lkw-physical"
    name: "LKW 12345"
    actorType: "internal"
    
# Digital twin in TMS
feature:
  - id: "feature-truck-digital-twin"
    name: "LKW 12345 Digital Twin"
    description: "Digital representation with telemetry"

Hybrid Workflows

Combine physical and digital approvals:

story:
  # Physical signature
  - sourceElementId: "actor-manager"
    targetElementId: "dataobject-approval-form"
    label: "unterschreibt"
    
  # Scan and upload
  - sourceElementId: "actor-assistant"
    targetElementId: "dataobject-approval-form"
    label: "scannt"
    
  # Digital processing
  - sourceElementId: "dataobject-approval-form"
    targetElementId: "feature-document-management"
    label: "wird hochgeladen in"

📊 Visualization Tips

Graph Layout

• Physical actors often appear on the left
• Digital systems on the right
• Paper documents in the middle
• Use vertical flow for sequential steps

Element Styling

• Physical actors: Use vehicle/person icons
• Paper documents: Use document icon
• Digital features: Use application icons
• Physical actions: Use condition labels

Process Annotations

Use the condition field for context:

• "physische Aktion"
• "Papierbasiert"
• "manuelle Übergabe"
• "vor Ort"

🚀 Getting Started

Initial Setup

Korgraph includes example physical world data by default. When you start the server, it automatically creates:

• Physical World system
• Paper module
• Common paper documents (Frachtbrief, Rechnung, etc.)
• Example actors (LKW, Fahrer, Disponent)
• Road logistics example process

Creating Your Own

1. Define your physical system (if not using default)
2. Model your actors (vehicles, people, locations)
3. Create data objects (documents, signals, materials)
4. Build processes with mixed physical/digital steps
5. Document transitions between physical and digital

YAML Import

Import your physical world model:

npm start -- --import ./my-physical-model.yaml

Or place YAML in config/db-setup/ for automatic loading on startup.

📚 Related Documentation

• Actor Element Help
• Data Object Element Help
• Process Modeling
• Story Editor
• YAML Import/Export

🆘 FAQ

Q: Can I model IoT sensors as actors?
A: Yes! Sensors can be actors that produce data objects (sensor readings).

Q: How do I show a physical handoff?
A: Use two stories: Actor A → Document, Document → Actor B.

Q: Can processes mix physical and digital steps?
A: Absolutely! That's the goal - complete end-to-end visibility.

Q: Should physical locations be actors or contexts?
A: Actors are better for locations that participate in processes (stations, docks).

Q: How do I model a vehicle fleet?
A: Create one actor type "LKW" and use descriptions/IDs for specific vehicles.

Q: Can paper documents become digital?
A: Yes! Show the transformation: Paper Doc → Scan Feature → Digital Doc.