flow_chat 0.9.0 → 0.10.0

data/docs/configuration.md

@@ -1,690 +1,183 @@
-# FlowChat Configuration
+# Configuration
 
-This guide covers all configuration options for FlowChat, from basic setup to advanced customization for production deployments.
+FlowChat has two layers of configuration: global settings on `FlowChat::Config`, set once during boot, and per-processor settings passed to the `FlowChat::Processor.new` block for each webhook.
 
-## Global Configuration
+## Global configuration
 
-Configure FlowChat globally in `config/initializers/flow_chat.rb`:
+Set these once, for example in `config/initializers/flow_chat.rb`.
 
-```ruby
-# Basic configuration
-FlowChat::Config.logger = Rails.logger
-FlowChat::Config.cache = Rails.cache
-
-# Validation behavior
-FlowChat::Config.combine_validation_error_with_message = true
-
-# Simulator settings (for development/testing)
-FlowChat::Config.simulator_secret = "your_simulator_secret"
-```
-
-## Platform-Specific Configuration
-
-### USSD Configuration
+| Option | Default | What it controls |
+|---|---|---|
+| `FlowChat::Config.logger` | `Logger.new($stdout)` | The logger FlowChat writes to. Set it to `Rails.logger` to fold FlowChat logs into your app's. |
+| `FlowChat::Config.cache` | `nil` | The cache backend the session store reads and writes. Required: `CacheSessionStore` raises without it. Set it to `Rails.cache` or any store with the same interface. |
+| `FlowChat::Config.simulator_secret` | `nil` | Secret that enables the local web simulator. The simulator stays off until this is set. See [testing.md](testing.md). |
+| `FlowChat::Config.combine_validation_error_with_message` | `true` | When `true`, a rejected input re-prompts with the validation error followed by the original prompt. When `false`, only the error is shown. |
+| `FlowChat::Config.inject_middleware_logger` | `true` in Rails development, else `false` | Whether a logging middleware is inserted into the stack automatically. |
 
 ```ruby
-# USSD pagination settings
-FlowChat::Config.ussd.pagination_page_size = 160       # Characters per page
-FlowChat::Config.ussd.pagination_next_option = "#"     # Next page option
-FlowChat::Config.ussd.pagination_back_option = "0"     # Previous page option
-FlowChat::Config.ussd.pagination_next_text = "More"    # Next page text
-FlowChat::Config.ussd.pagination_back_text = "Back"    # Previous page text
-```
-
-### WhatsApp Configuration
-
-```ruby
-# WhatsApp API configuration
-FlowChat::Config.whatsapp.api_base_url = "https://graph.facebook.com/v23.0"
-```
-
-### HTTP Configuration
-
-```ruby
-# HTTP gateway settings
-FlowChat::Config.http.default_gateway = :simple
-FlowChat::Config.http.request_timeout = 30
-FlowChat::Config.http.response_format = :json
-```
-
-## Processor Configuration
-
-Configure processors for each request:
-
-```ruby
-processor = FlowChat::Processor.new(self) do |config|
-  # Gateway configuration
-  config.use_gateway FlowChat::Ussd::Gateway::Nalo
-  
-  # Session configuration
-  config.use_session_store FlowChat::Session::CacheSessionStore
-  config.use_session_config(
-    boundaries: [:flow, :platform, :gateway],
-    identifier: :msisdn,
-    hash_identifiers: true
-  )
-  
-  # Middleware configuration
-  config.use_middleware LoggingMiddleware
-  config.use_middleware AuthenticationMiddleware
-  
-  # Convenience methods
-  config.use_durable_sessions
-  config.use_cross_platform_sessions
-  config.use_url_isolation
-end
-```
-
-## Session Configuration
-
-### Session Boundaries
-
-Control how session IDs are generated:
-
-```ruby
-# Available boundaries
-boundaries: [
-  :flow,      # Separate sessions per flow class
-  :platform,  # Separate sessions per platform (ussd, whatsapp, http)
-  :gateway,   # Separate sessions per gateway (nalo, cloud_api, etc.)
-  :url        # Separate sessions per URL (multi-tenancy)
-]
-
-# Examples
-config.use_session_config(boundaries: [:flow])                    # "survey_flow:user123"
-config.use_session_config(boundaries: [:flow, :platform])         # "survey_flow:ussd:user123"
-config.use_session_config(boundaries: [:flow, :url])              # "survey_flow:tenant1.app.com:user123"
-```
-
-### Custom Session ID Generation
-
-For complete control over session ID format, use a block:
-
-```ruby
-# Custom session ID with proc/block
-config.use_session_config do |context|
-  # Access full context for custom logic
-  user_phone = context["request.msisdn"]
-  flow_name = context["flow.name"]
-  gateway = context["request.gateway"]
-  timestamp = Time.current.strftime("%Y%m%d")
-  
-  # Return your custom session ID
-  "#{flow_name}_#{gateway}_#{timestamp}_#{hash_phone(user_phone)}"
-end
-
-# Multi-tenant example
-config.use_session_config do |context|
-  tenant_id = extract_tenant(context)
-  user_id = context["request.user_id"] || context["request.msisdn"]
-  "tenant_#{tenant_id}_user_#{user_id.hash.abs}"
-end
-
-# API-based session IDs
-config.use_session_config do |context|
-  api_key = context.controller.request.headers["X-API-Key"]
-  "api_#{Digest::SHA256.hexdigest(api_key)[0,8]}_#{context['request.id']}"
-end
-```
-
-**Note**: When using a custom proc, it takes precedence over all boundary and identifier settings. The proc receives the full FlowChat context and should return a string session ID.
-
-### Session Identifiers
-
-Choose what identifies a user session:
-
-```ruby
-# Identifier types
-:request_id  # Ephemeral (new session each request)
-:user_id     # Durable using user_id field
-:msisdn      # Durable using phone number
-
-# Examples
-config.use_session_config(identifier: :request_id)  # Default for HTTP
-config.use_session_config(identifier: :msisdn)      # Default for WhatsApp/USSD
-config.use_session_config(identifier: :user_id)     # For authenticated users
+# config/initializers/flow_chat.rb
+FlowChat::Config.cache = Rails.cache
+FlowChat::Config.logger = Rails.logger
+FlowChat::Config.simulator_secret = Rails.application.credentials.flow_chat_simulator_secret
 ```
 
-### Session Stores
-
-Choose where session data is stored:
-
-```ruby
-# Built-in session stores
-config.use_session_store FlowChat::Session::CacheSessionStore    # Rails sessions
-config.use_session_store FlowChat::Session::CacheSessionStore   # Rails cache
+## USSD configuration
 
-# Custom session store
-config.use_session_store MyCompany::CustomSessionStore
-```
+`FlowChat::Config.ussd` controls how USSD responses are paginated. USSD messages are length-limited, so FlowChat splits long output into pages and adds navigation options.
 
-### Convenience Methods
+| Option | Default | What it controls |
+|---|---|---|
+| `pagination_page_size` | `140` | Maximum characters per USSD page before FlowChat splits the response. |
+| `pagination_next_option` | `"#"` | The input a user sends to see the next page. |
+| `pagination_next_text` | `"More"` | The label shown next to the next-page option. |
+| `pagination_back_option` | `"0"` | The input a user sends to go to the previous page. |
+| `pagination_back_text` | `"Back"` | The label shown next to the previous-page option. |
 
 ```ruby
-# Durable sessions (use phone number, survive timeouts)
-config.use_durable_sessions
-
-# Cross-platform sessions (same user across USSD/WhatsApp)
-config.use_cross_platform_sessions
-
-# URL-based isolation (multi-tenancy)
-config.use_url_isolation
+FlowChat::Config.ussd.pagination_page_size = 160
 ```
 
-## Gateway Configuration
+## WhatsApp configuration
 
-### Built-in Gateways
+`FlowChat::Config.whatsapp` holds the WhatsApp Cloud API base URL. Per-tenant credentials (access token, phone number id, app secret, verify token) are passed to the gateway, not set here. See [platforms/whatsapp.md](platforms/whatsapp.md).
 
-#### USSD - Nalo Gateway
+| Option | Default | What it controls |
+|---|---|---|
+| `api_base_url` | `"https://graph.facebook.com/v23.0"` | The Cloud API version and host the WhatsApp client calls. |
 
-```ruby
-config.use_gateway FlowChat::Ussd::Gateway::Nalo
+## HTTP configuration
 
-# No additional configuration required for Nalo
-```
+`FlowChat::Config.http` holds defaults for the HTTP gateway used in testing and custom integrations. See the platform guides for the full request and response shapes.
 
-#### WhatsApp - Cloud API Gateway
+| Option | Default | What it controls |
+|---|---|---|
+| `default_gateway` | `:simple` | The HTTP gateway used when none is named. |
+| `request_timeout` | `30` | Request timeout in seconds. |
+| `response_format` | `:json` | The response serialization format. |
 
-```ruby
-# Basic configuration (uses Rails credentials)
-config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
-
-# Custom configuration
-whatsapp_config = FlowChat::Whatsapp::Configuration.new
-whatsapp_config.access_token = ENV["WHATSAPP_ACCESS_TOKEN"]
-whatsapp_config.phone_number_id = ENV["WHATSAPP_PHONE_NUMBER_ID"]
-whatsapp_config.verify_token = ENV["WHATSAPP_VERIFY_TOKEN"]
-whatsapp_config.app_secret = ENV["WHATSAPP_APP_SECRET"]
-whatsapp_config.skip_signature_validation = Rails.env.development?
-
-config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi, whatsapp_config
-```
+## Sessions
 
-#### HTTP - Simple Gateway
+A session holds the answers a flow has collected so far. FlowChat looks the session up by an id it builds on every request from two things: a set of boundaries and an identifier.
 
-```ruby
-# HTTP gateway requires user_params hash
-config.use_gateway FlowChat::Http::Gateway::Simple, {
-  session_id: "unique_session_id",  # required
-  user_id: "user_identifier",       # required
-  name: "John Doe",                 # optional
-  msisdn: "+256700123456",          # optional
-  email: "user@example.com"         # optional
-}
-```
+`FlowChat::Config.session` sets the defaults.
 
-**Required Parameters:**
-- `session_id` - Unique identifier for the session
-- `user_id` - User identifier
+| Option | Default | What it controls |
+|---|---|---|
+| `boundaries` | `[:flow, :gateway, :platform]` | Which dimensions separate one session from another (see below). |
+| `hash_identifiers` | `true` | Whether the identifier (often a phone number) is hashed into the session id rather than stored in the clear. |
+| `identifier` | `nil` | Which request value identifies the user. `nil` lets the platform choose: WhatsApp uses `:msisdn`, the others use `:request_id`. |
+| `session_id_proc` | `nil` | A callable that builds the session id from the context directly, bypassing boundaries and identifier. |
 
-**Optional Parameters:**
-- `name` - User's display name (sets `request.user_name`)
-- `msisdn` - E.164 formatted phone number (sets `request.msisdn`)
-- `email` - User email address (sets `request.email`)
+### How the session id is built
 
-**Note:** User input comes from `params["input"]` in the request. The `message_id` is auto-generated as a UUID.
+FlowChat sets the session id one of three ways, in order of precedence:
 
-### Custom Gateway Configuration
+1. If `context["session.id"]` is already set, that value is used verbatim (a manual override).
+2. If you passed a block to `use_session_config`, its return value is used verbatim. Boundaries and identifier are skipped entirely.
+3. Otherwise the id is built from the boundaries and the identifier, described below.
 
-```ruby
-# Custom gateway with configuration
-my_config = MyCompany::CustomGatewayConfig.new
-my_config.api_key = ENV["CUSTOM_API_KEY"]
-my_config.endpoint = ENV["CUSTOM_ENDPOINT"]
+Think of the built id as `boundaries` followed by `identifier`: the boundaries describe the context a session lives in (the walls that separate it), and the identifier is who the session belongs to. The parts are joined with `:` in this fixed order, and a part is included only when its boundary is enabled and its value is present:
 
-config.use_gateway MyCompany::CustomGateway, my_config
 ```
-
-## Environment-Specific Configuration
-
-### Development Configuration
-
-```ruby
-# config/environments/development.rb
-Rails.application.configure do
-  # Enable detailed logging
-  config.log_level = :debug
-  
-  # FlowChat development settings
-  config.after_initialize do
-    FlowChat::Config.logger = Rails.logger
-    FlowChat::Config.logger.level = Logger::DEBUG
-    
-    # USSD settings for development
-    FlowChat::Config.ussd.pagination_page_size = 200  # Larger for easier testing
-    
-    # WhatsApp settings for development
-    FlowChat::Config.whatsapp.message_handling_mode = :inline
-    
-    # Enable simulator
-    FlowChat::Config.simulator_secret = "dev_secret_123"
-  end
-end
+flow_name : platform : gateway : url : identifier
 ```
 
-### Production Configuration
+The order of the parts is fixed regardless of the order you list boundaries in. With the default boundaries `[:flow, :gateway, :platform]`, a WhatsApp user in `RegistrationFlow` gets:
 
-```ruby
-# config/environments/production.rb
-Rails.application.configure do
-  # Production logging
-  config.log_level = :info
-  
-  # FlowChat production settings
-  config.after_initialize do
-    FlowChat::Config.logger = Rails.logger
-    
-    # USSD production settings
-    FlowChat::Config.ussd.pagination_page_size = 140  # Conservative for compatibility
-    
-    # WhatsApp uses inline by default
-    
-    # Disable simulator in production
-    FlowChat::Config.simulator_secret = nil
-  end
-end
 ```
-
-### Staging Configuration
-
-```ruby
-# config/environments/staging.rb
-Rails.application.configure do
-  # Staging-specific settings
-  config.after_initialize do
-    FlowChat::Config.logger = Rails.logger
-    FlowChat::Config.logger.level = Logger::DEBUG  # More verbose for staging
-    
-    # Use background processing but with shorter delays
-    FlowChat::Config.whatsapp.message_handling_mode = :background
-    
-    # Enable simulator with staging secret
-    FlowChat::Config.simulator_secret = ENV["STAGING_SIMULATOR_SECRET"]
-  end
-end
+registration_flow:whatsapp:whatsapp_cloud_api:9f86d0818...
+     (flow)          (platform)     (gateway)   (hashed msisdn)
 ```
 
-## Multi-Tenant Configuration
+The hashed identifier is shown truncated here for readability; the real key carries the 32-character (128-bit) SHA256 prefix.
 
-### URL-Based Tenancy
+### What each boundary isolates
 
-```ruby
-class MultiTenantController < ApplicationController
-  def process_request
-    processor = FlowChat::Processor.new(self) do |config|
-      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi, tenant_whatsapp_config
-      config.use_session_store FlowChat::Session::CacheSessionStore
-      
-      # Enable URL-based session isolation
-      config.use_url_isolation
-      
-      # Optional: Additional tenant isolation
-      config.use_session_config(
-        boundaries: [:flow, :platform, :url],
-        identifier: :user_id
-      )
-    end
-
-    processor.run tenant_flow_class, :main_action
-  end
-
-  private
-
-  def tenant_whatsapp_config
-    tenant = extract_tenant_from_request
-    tenant.whatsapp_configuration
-  end
-
-  def tenant_flow_class
-    tenant = extract_tenant_from_request
-    tenant.flow_class
-  end
-
-  def extract_tenant_from_request
-    # Extract tenant from subdomain, domain, or path
-    subdomain = request.subdomain
-    Tenant.find_by(subdomain: subdomain)
-  end
-end
-```
+A boundary is a wall. Include it and two requests that differ on that dimension get separate sessions; drop it and they share one session, provided the identifier matches.
 
-### Database-Based Tenancy
+| Boundary | Segment | Adding it separates sessions by | Drop it when |
+|---|---|---|---|
+| `:flow` | `context["flow.name"]` | flow class, so `RegistrationFlow` and `SurveyFlow` never share state | you want one session shared across all flows (rare) |
+| `:platform` | `:ussd`, `:whatsapp`, and so on | platform, so the same person on USSD and on WhatsApp gets two sessions | you want one conversation to span platforms |
+| `:gateway` | `:nalo`, `:whatsapp_cloud_api`, and so on | gateway, so two gateways on the same platform (for example two USSD aggregators) do not collide | you are consolidating gateways and want them to share |
+| `:url` | normalized `host + path` | host and path, for per-tenant or per-endpoint isolation (`tenant1.app.com` vs `tenant2.app.com`) | single tenant, single endpoint |
 
-```ruby
-class TenantSpecificController < ApplicationController
-  before_action :set_tenant
-
-  def process_request
-    processor = FlowChat::Processor.new(self) do |config|
-      config.use_gateway gateway_for_tenant
-      config.use_session_store FlowChat::Session::CacheSessionStore
-      
-      # Custom session boundaries for tenant isolation
-      config.use_session_config(
-        boundaries: [:flow, :platform],
-        identifier: :user_id
-      )
-    end
-
-    processor.run @tenant.flow_class.constantize, :main_action
-  end
-
-  private
-
-  def set_tenant
-    @tenant = Tenant.find(params[:tenant_id])
-  end
-
-  def gateway_for_tenant
-    case @tenant.platform
-    when 'whatsapp'
-      FlowChat::Whatsapp::Gateway::CloudApi
-    when 'ussd'
-      FlowChat::Ussd::Gateway::Nalo
-    else
-      FlowChat::Http::Gateway::Simple
-    end
-  end
-end
-```
+The `:url` segment is `host + path` with the leading slash removed and any character outside `[a-zA-Z0-9._-]` replaced by `_`. If that exceeds 50 characters it becomes the first 41 characters plus an 8-character SHA256 suffix, so it stays bounded but still recognizable.
 
-## Security Configuration
+### The identifier
 
-### WhatsApp Signature Validation
+The identifier is chosen independently of the boundaries and always comes last. Its type is the `identifier` option, or a platform default when unset: WhatsApp uses `:msisdn`, every other platform uses `:request_id`.
 
-```ruby
-# Always validate signatures in production
-whatsapp_config = FlowChat::Whatsapp::Configuration.new
-whatsapp_config.app_secret = ENV["WHATSAPP_APP_SECRET"]
-whatsapp_config.skip_signature_validation = false  # Never skip in production
+| Type | Value | Hashed |
+|---|---|---|
+| `:request_id` | `context["request.id"]` | Never. It is already opaque. On USSD it is the telco session id, which rotates on timeout, so the session is ephemeral. |
+| `:msisdn` | `context["request.msisdn"]` | Yes, when `hash_identifiers` is true (the default): the first 32 hex characters of SHA256 (128 bits). |
+| `:user_id` | `context["request.user_id"]` | Yes, when `hash_identifiers` is true. |
 
-# Only skip validation in development if needed
-whatsapp_config.skip_signature_validation = Rails.env.development?
-```
+So with the default `hash_identifiers: true`, a phone number never appears in the session key in the clear, while a `request_id` passes through untouched.
 
-### Session Security
+### Worked examples
 
-```ruby
-# Hash sensitive identifiers
-config.use_session_config(
-  identifier: :msisdn,
-  hash_identifiers: true  # Phone numbers are hashed for privacy
-)
-
-# Implement custom session store with encryption
-class EncryptedSessionStore < FlowChat::Session::CacheSessionStore
-  def set(key, value)
-    encrypted_value = encrypt(value.to_json)
-    super(key, encrypted_value)
-  end
-
-  def get(key)
-    encrypted_value = super(key)
-    return nil unless encrypted_value
-    
-    decrypted = decrypt(encrypted_value)
-    JSON.parse(decrypted)
-  rescue
-    nil  # Return nil if decryption fails
-  end
-
-  private
-
-  def encrypt(data)
-    # Use Rails credentials or environment variable
-    secret = Rails.application.credentials.session_encryption_key
-    crypt = ActiveSupport::MessageEncryptor.new(secret)
-    crypt.encrypt_and_sign(data)
-  end
-
-  def decrypt(encrypted_data)
-    secret = Rails.application.credentials.session_encryption_key
-    crypt = ActiveSupport::MessageEncryptor.new(secret)
-    crypt.decrypt_and_verify(encrypted_data)
-  end
-end
+Default config, USSD, `RegistrationFlow`, no durable sessions. The identifier is `:request_id`, the telco session id, so the session lasts only as long as that telco session:
 
-# Use encrypted session store
-config.use_session_store EncryptedSessionStore
 ```
-
-## Performance Configuration
-
-### Redis Cache Configuration
-
-```ruby
-# config/initializers/redis.rb
-redis_config = {
-  url: ENV["REDIS_URL"],
-  pool_size: ENV.fetch("REDIS_POOL_SIZE", 5).to_i,
-  pool_timeout: ENV.fetch("REDIS_POOL_TIMEOUT", 5).to_i
-}
-
-# Use Redis for session storage
-Rails.application.configure do
-  config.cache_store = :redis_cache_store, redis_config
-end
-
-# FlowChat will automatically use Rails.cache
-FlowChat::Config.cache = Rails.cache
+registration_flow:ussd:nalo:1699_telco_session_42
 ```
 
-### Background Job Configuration
-
-```ruby
-# config/initializers/sidekiq.rb (if using Sidekiq)
-Sidekiq.configure_server do |config|
-  config.redis = { url: ENV["REDIS_URL"] }
-end
+The same, but with `use_durable_sessions` (identifier `:user_id`, which Nalo sets equal to the msisdn) and hashing on. Now the user can time out and dial back into the same session:
 
-Sidekiq.configure_client do |config|
-  config.redis = { url: ENV["REDIS_URL"] }
-end
-
-# WhatsApp uses inline responses by defaul
 ```
-
-### Database Connection Configuration
-
-```ruby
-# config/database.yml
-production:
-  adapter: postgresql
-  pool: <%= ENV.fetch("RAILS_MAX_THREADS", 5) %>
-  timeout: 5000
-  # ... other database settings
-  
-  # For high-volume USSD applications
-  checkout_timeout: 2
-  reaping_frequency: 10
+registration_flow:ussd:nalo:9f86d0818...
 ```
 
-## Monitoring Configuration
+### Configuring sessions per processor
 
-### Instrumentation Setup
+Set boundaries, identifier, and hashing directly:
 
 ```ruby
-# config/initializers/flow_chat.rb
-FlowChat.setup_instrumentation!
-
-# Subscribe to FlowChat events
-ActiveSupport::Notifications.subscribe("flow_chat.message_received") do |event|
-  # Log message received
-  Rails.logger.info "Message received: #{event.payload}"
-end
-
-ActiveSupport::Notifications.subscribe("flow_chat.message_sent") do |event|
-  # Log message sent
-  Rails.logger.info "Message sent: #{event.payload}"
-end
-
-ActiveSupport::Notifications.subscribe("flow_chat.flow_execution_error") do |event|
-  # Alert on flow errors
-  ErrorNotificationService.notify(event.payload)
+processor = FlowChat::Processor.new(self) do |config|
+  config.use_gateway FlowChat::Ussd::Gateway::Nalo
+  config.use_session_store FlowChat::Session::CacheSessionStore
+  config.use_session_config(boundaries: [:flow, :platform], identifier: :msisdn, hash_identifiers: true)
 end
 ```
 
-### Custom Metrics
+Or take full control of the id with a block:
 
 ```ruby
-# Custom metrics collector
-class CustomMetricsCollector
-  def self.collect_metrics
-    {
-      active_sessions: count_active_sessions,
-      messages_per_minute: calculate_message_rate,
-      error_rate: calculate_error_rate
-    }
-  end
-
-  private
-
-  def self.count_active_sessions
-    # Implementation depends on your session store
-    Rails.cache.redis.keys("flow_chat:session:*").count
-  end
-
-  def self.calculate_message_rate
-    # Implementation depends on your metrics storage
-    # Return messages processed in the last minute
-  end
-
-  def self.calculate_error_rate
-    # Calculate error percentage
-  end
+config.use_session_config do |context|
+  "tenant:#{context["request.tenant_id"]}:#{context["request.msisdn"]}"
 end
-
-# Setup metrics collection
-FlowChat::Config.metrics_collector = CustomMetricsCollector
 ```
 
-## Testing Configuration
+Three convenience methods wrap common changes:
 
-### Test Environment
+| Method | Effect |
+|---|---|
+| `use_durable_sessions` | Sets the identifier to `:user_id`, a stable per-user id. It changes only the identifier, not the boundaries. It matters most on USSD, where `:request_id` rotates on timeout but `:user_id` (which Nalo sets equal to the msisdn) is stable, so the conversation survives a rotation. |
+| `use_cross_platform_sessions` | Narrows boundaries to `[:flow]`, dropping platform and gateway, so one user shares a single session across platforms. |
+| `use_url_isolation` | Appends `:url` to the current boundaries for per-tenant or per-host isolation. |
 
 ```ruby
-# config/environments/test.rb
-Rails.application.configure do
-  config.after_initialize do
-    FlowChat::Config.logger = Rails.logger
-    FlowChat::Config.logger.level = Logger::ERROR  # Reduce noise in tests
-    
-    # Use memory cache for tests
-    FlowChat::Config.cache = ActiveSupport::Cache::MemoryStore.new
-    
-    # Disable background processing in tests
-    FlowChat::Config.whatsapp.message_handling_mode = :inline
-    
-    # Enable simulator for testing
-    FlowChat::Config.simulator_secret = "test_secret"
-  end
-end
-```
-
-### Test Helper Configuration
-
-```ruby
-# test/test_helper.rb
-class ActiveSupport::TestCase
-  def setup_flow_chat_test_environment
-    # Reset FlowChat state between tests
-    FlowChat::Config.cache.clear
-    
-    # Mock external API calls
-    stub_whatsapp_api_calls
-    stub_ussd_gateway_calls
-  end
-
-  def create_test_processor(platform: :ussd, **options)
-    gateway_class = case platform
-    when :ussd then FlowChat::Ussd::Gateway::Nalo
-    when :whatsapp then FlowChat::Whatsapp::Gateway::CloudApi
-    when :http then FlowChat::Http::Gateway::Simple
-    end
-
-    FlowChat::Processor.new(MockController.new) do |config|
-      config.use_gateway gateway_class
-      config.use_session_store FlowChat::Session::MemorySessionStore
-      options.each { |key, value| config.send(key, value) }
-    end
-  end
+processor = FlowChat::Processor.new(self) do |config|
+  config.use_gateway FlowChat::Ussd::Gateway::Nalo
+  config.use_session_store FlowChat::Session::CacheSessionStore
+  config.use_durable_sessions
 end
 ```
 
-## Troubleshooting Configuration
-
-### Debug Mode
-
-```ruby
-# Enable comprehensive debugging
-FlowChat::Config.logger.level = Logger::DEBUG
-
-# Add custom debug middleware
-class DebugMiddleware
-  def initialize(app)
-    @app = app
-  end
-
-  def call(context)
-    Rails.logger.debug "=== FlowChat Debug ==="
-    Rails.logger.debug "Context: #{context.to_h}"
-    Rails.logger.debug "Input: #{context.input.inspect}"
-    Rails.logger.debug "Session ID: #{context['session.id']}"
-    
-    result = @app.call(context)
-    
-    Rails.logger.debug "Result: #{result.inspect}"
-    Rails.logger.debug "======================"
-    
-    result
-  end
-end
+One subtlety with `use_cross_platform_sessions`: dropping the `:platform` boundary only shares a session if the identifier resolves to the same value on both platforms. The platform default identifier differs (WhatsApp uses `:msisdn`, USSD uses `:request_id`), so for real cross-platform sharing pair it with a stable identifier, either `use_durable_sessions` (`:user_id`) or `identifier: :msisdn`.
 
-# Use debug middleware
-config.use_middleware DebugMiddleware
-```
+## Async processing
 
-### Configuration Validation
+Enable background processing with `use_async`. It has two forms:
 
 ```ruby
-# Add configuration validation
-class ConfigurationValidator
-  def self.validate!
-    validate_environment_variables!
-    validate_gateway_configuration!
-    validate_session_configuration!
-  end
-
-  private
-
-  def self.validate_environment_variables!
-    required_vars = %w[
-      WHATSAPP_ACCESS_TOKEN
-      WHATSAPP_PHONE_NUMBER_ID
-      WHATSAPP_VERIFY_TOKEN
-    ]
-
-    missing = required_vars.select { |var| ENV[var].blank? }
-    raise "Missing environment variables: #{missing.join(', ')}" if missing.any?
-  end
-
-  def self.validate_gateway_configuration!
-    # Validate gateway-specific configuration
-  end
-
-  def self.validate_session_configuration!
-    # Validate session store connectivity
-    FlowChat::Config.cache.write("test_key", "test_value")
-    FlowChat::Config.cache.delete("test_key")
-  rescue => e
-    raise "Session store configuration invalid: #{e.message}"
-  end
-end
+# Use a factory (no custom job class needed). The factory: keyword is required.
+config.use_async(factory: :whatsapp)
 
-# Run validation on startup
-Rails.application.config.after_initialize do
-  ConfigurationValidator.validate! if Rails.env.production?
-end
+# Or use your own ActiveJob subclass, with optional job params.
+config.use_async(MyFlowJob, deployment_id: 123)
 ```
 
-This configuration guide covers all aspects of FlowChat setup. For platform-specific configuration details, see the individual platform guides. 
+The webhook enqueues the job and returns immediately; the job re-runs the flow in the background. USSD does not support async, since its protocol needs a synchronous response. See [factory-pattern.md](factory-pattern.md) and [async-background-processing.md](async-background-processing.md).