🔄 Complete documentation and examples update for production readiness

README.md

@@ -82,6 +82,45 @@ $result = Flowpipe::make()
 // Result: "HELLO-WORLD!"
 ```
 
+### <span style="color: #88C600;">🎯 Factory Methods</span>
+
+**<span style="color: #D2D200;">Laravel Flowpipe</span>** provides convenient factory methods for creating instances with specific tracers:
+
+```php
+use Grazulex\LaravelFlowpipe\Flowpipe;
+
+// Create with debug tracing (logs to file or console)
+$debugFlow = Flowpipe::debug(true, 'flowpipe'); // logToFile=true, channel='flowpipe'
+$result = $debugFlow
+    ->send($data)
+    ->through($steps)
+    ->thenReturn();
+
+// Create with performance tracing
+$perfFlow = Flowpipe::performance();
+$result = $perfFlow
+    ->send($data)
+    ->through($steps)
+    ->thenReturn();
+
+// Create with database tracing
+$dbFlow = Flowpipe::database('custom_traces_table');
+$result = $dbFlow
+    ->send($data)
+    ->through($steps)
+    ->thenReturn();
+
+// Create with test tracing (for unit tests)
+$testFlow = Flowpipe::test();
+$result = $testFlow
+    ->send($data)
+    ->through($steps)
+    ->thenReturn();
+
+// Standard make method (no tracing by default)
+$flow = Flowpipe::make(); // or Flowpipe::make($customTracer)
+```
+
 ### <span style="color: #D2D200;">🛡️ Error Handling with Retry</span>
 
 ```php
@@ -508,6 +547,82 @@ $result = Flowpipe::make()
     ->thenReturn();
 ```
 
+### <span style="color: #88C600;">🔧 Built-in Step Types</span>
+
+**<span style="color: #00B470;">Laravel Flowpipe</span>** includes various specialized step types for common operations:
+
+```php
+use Grazulex\LaravelFlowpipe\Flowpipe;
+
+// Cache step - cache expensive operations
+$result = Flowpipe::make()
+    ->send($userData)
+    ->cache('user_profile_' . $userData['id'], 3600) // Cache for 1 hour
+    ->through([
+        fn($data, $next) => $next(fetchUserProfile($data)),
+    ])
+    ->thenReturn();
+
+// Transform step - transform data structure
+$result = Flowpipe::make()
+    ->send($rawData)
+    ->transform(function ($data) {
+        return [
+            'name' => strtoupper($data['name']),
+            'email' => strtolower($data['email']),
+            'created_at' => now(),
+        ];
+    })
+    ->through([
+        fn($data, $next) => $next(saveUser($data)),
+    ])
+    ->thenReturn();
+
+// Validation step - validate data using Laravel validation
+$result = Flowpipe::make()
+    ->send($inputData)
+    ->validate([
+        'name' => 'required|string|max:255',
+        'email' => 'required|email|unique:users',
+        'age' => 'required|integer|min:18',
+    ])
+    ->through([
+        fn($data, $next) => $next(processValidData($data)),
+    ])
+    ->thenReturn();
+
+// Batch step - process data in batches
+$result = Flowpipe::make()
+    ->send($largeDataset)
+    ->batch(100) // Process 100 items at a time
+    ->through([
+        fn($batch, $next) => $next(processBatch($batch)),
+    ])
+    ->thenReturn();
+
+// Rate limiting step - prevent API abuse
+$result = Flowpipe::make()
+    ->send($apiRequest)
+    ->rateLimit('api_calls', 60, 1) // 60 calls per minute
+    ->through([
+        fn($data, $next) => $next(callExternalAPI($data)),
+    ])
+    ->thenReturn();
+
+// Combine multiple step types
+$result = Flowpipe::make()
+    ->send($complexData)
+    ->validate(['data' => 'required|array'])
+    ->transform(fn($data) => ['processed' => $data['data']])
+    ->cache('complex_operation', 1800)
+    ->batch(50)
+    ->rateLimit('processing', 30, 1)
+    ->through([
+        fn($data, $next) => $next(performComplexOperation($data)),
+    ])
+    ->thenReturn();
+```
+
 ### <span style="color: #00B470;">Error Handling in Production Workflows</span>
 
 ```php
@@ -624,6 +739,19 @@ public function test_user_processing_flow()
     $this->assertEquals('JOHN', $result);
     $this->assertCount(1, $tracer->count());
 }
+
+// Or use the factory method for cleaner tests:
+public function test_user_processing_flow_with_factory()
+{
+    $result = Flowpipe::test()
+        ->send(['name' => 'John'])
+        ->through([
+            fn($data, $next) => $next(strtoupper($data['name'])),
+        ])
+        ->thenReturn();
+
+    $this->assertEquals('JOHN', $result);
+}
 ```
 
 ## <span style="color: #88C600;">⚡ Performance</span>
@@ -668,10 +796,15 @@ public function test_user_processing_flow()
 
 ### <span style="color: #88C600;">Static Methods</span>
 
-- **<span style="color: #FF9900;">`group(string $name, array $steps)`</span>** - Define a reusable step group
-- **<span style="color: #D2D200;">`hasGroup(string $name)`</span>** - Check if a group exists
-- **<span style="color: #88C600;">`getGroups()`</span>** - Get all registered groups
-- **<span style="color: #00B470;">`clearGroups()`</span>** - Clear all registered groups (useful for testing)
+- **<span style="color: #FF9900;">`make(?Tracer $tracer = null)`</span>** - Create a new flowpipe instance
+- **<span style="color: #D2D200;">`debug(bool $logToFile = false, string $logChannel = 'default')`</span>** - Create instance with debug tracer
+- **<span style="color: #88C600;">`performance()`</span>** - Create instance with performance tracer
+- **<span style="color: #00B470;">`database(string $tableName = 'flowpipe_traces')`</span>** - Create instance with database tracer
+- **<span style="color: #FF9900;">`test()`</span>** - Create instance with test tracer (for testing)
+- **<span style="color: #D2D200;">`group(string $name, array $steps)`</span>** - Define a reusable step group
+- **<span style="color: #88C600;">`hasGroup(string $name)`</span>** - Check if a group exists
+- **<span style="color: #00B470;">`getGroups()`</span>** - Get all registered groups
+- **<span style="color: #FF9900;">`clearGroups()`</span>** - Clear all registered groups (useful for testing)
 
 ### <span style="color: #00B470;">Conditional Steps</span>
 

examples/README.md

@@ -222,23 +222,64 @@ php artisan flowpipe:export user-registration --format=md --output=docs/user-reg
 
 ## Step Groups
 
-The examples demonstrate three types of reusable step groups:
+The examples demonstrate multiple types of reusable step groups organized by functionality:
 
-### User Validation Group (`groups/user-validation.yaml`)
+### User-Related Groups
+
+#### User Validation Group (`groups/user-validation.yaml`)
 - Email format validation
 - Password strength checking
 - Required field validation
 - User existence checking
 - Terms acceptance validation
 
-### Order Processing Group (`groups/order-processing.yaml`)
+#### User Setup Group (`groups/user-setup.yaml`)
+- User ID generation
+- Password hashing
+- Profile creation
+- Default preferences setup
+- API key generation
+
+#### User Notifications Group (`groups/user-notifications.yaml`)
+- Welcome email sending
+- Email verification dispatch
+- Admin notifications
+- Registration event logging
+- User statistics updates
+
+### E-commerce Groups
+
+#### Order Validation Group (`groups/order-validation.yaml`)
+- Order structure validation
+- Customer information validation
+- Item and quantity validation
+- Order total verification
+- Business rules checking
+
+#### Inventory Management Group (`groups/inventory-management.yaml`)
+- Item availability checking
+- Inventory reservation
+- Shipping cost calculation
+- Inventory level updates
+- Inventory reporting
+
+#### Order Notifications Group (`groups/order-notifications.yaml`)
+- Order confirmation emails
+- SMS notifications
+- Customer account updates
+- Warehouse notifications
+- Notification event logging
+
+### General Processing Groups
+
+#### Order Processing Group (`groups/order-processing.yaml`)
 - Order data validation
 - Inventory checking and reservation
 - Payment processing
 - Order record creation
 - Confirmation generation
 
-### Notifications Group (`groups/notifications.yaml`)
+#### Notifications Group (`groups/notifications.yaml`)
 - Welcome email sending
 - Verification email dispatch
 - SMS notifications

examples/groups/inventory-management.yaml

@@ -0,0 +1,31 @@
+# Example: Inventory Management Group
+# File: groups/inventory-management.yaml
+
+group: inventory-management
+description: Manage inventory for e-commerce orders
+
+steps:
+  # Check item availability
+  - type: closure
+    action: check_item_availability
+    description: Check if all items are available in requested quantities
+
+  # Reserve inventory items
+  - type: closure
+    action: reserve_items
+    description: Reserve items for this order
+
+  # Calculate shipping costs
+  - type: closure
+    action: calculate_shipping
+    description: Calculate shipping costs based on items and location
+
+  # Update inventory levels
+  - type: closure
+    action: update_inventory_levels
+    description: Update inventory levels after reservation
+
+  # Generate inventory report
+  - type: closure
+    action: generate_inventory_report
+    description: Generate inventory status report for this order

examples/groups/order-notifications.yaml

@@ -0,0 +1,31 @@
+# Example: Order Notifications Group  
+# File: groups/order-notifications.yaml
+
+group: order-notifications
+description: Send notifications for e-commerce orders
+
+steps:
+  # Send order confirmation email
+  - type: closure
+    action: send_order_confirmation
+    description: Send order confirmation email to customer
+
+  # Send SMS notification
+  - type: closure
+    action: send_sms_notification
+    description: Send SMS notification if customer opted in
+
+  # Update customer account
+  - type: closure
+    action: update_customer_account
+    description: Update customer's order history
+
+  # Notify warehouse
+  - type: closure
+    action: notify_warehouse
+    description: Notify warehouse team about new order
+
+  # Log notification events
+  - type: closure
+    action: log_notifications
+    description: Log all notification events for auditing

examples/groups/order-validation.yaml

@@ -0,0 +1,31 @@
+# Example: Order Validation Group
+# File: groups/order-validation.yaml
+
+group: order-validation
+description: Validate e-commerce order data and requirements
+
+steps:
+  # Validate order structure
+  - type: closure
+    action: validate_order_structure
+    description: Ensure order contains required fields
+
+  # Validate customer information
+  - type: closure
+    action: validate_customer_info
+    description: Validate customer name, email, and address
+
+  # Validate items and quantities
+  - type: closure
+    action: validate_items
+    description: Validate item names, prices, and quantities
+
+  # Calculate and verify total
+  - type: closure
+    action: verify_order_total
+    description: Calculate total and verify against provided total
+
+  # Check business rules
+  - type: closure
+    action: check_business_rules
+    description: Apply business rules (minimum order, restrictions, etc.)

examples/groups/user-notifications.yaml

@@ -0,0 +1,31 @@
+# Example: User Notifications Group
+# File: groups/user-notifications.yaml
+
+group: user-notifications
+description: Send notifications for new user registration
+
+steps:
+  # Send welcome email
+  - type: closure
+    action: send_welcome_email
+    description: Send welcome email with account details
+
+  # Send verification email  
+  - type: closure
+    action: send_verification_email
+    description: Send email verification link
+
+  # Send admin notification
+  - type: closure
+    action: notify_admin
+    description: Notify administrators about new user registration
+
+  # Log registration event
+  - type: closure
+    action: log_registration
+    description: Log user registration event for analytics
+
+  # Update user stats
+  - type: closure
+    action: update_user_stats
+    description: Update application user statistics