flow_chat 0.9.0 → 0.10.0

data/docs/gateway-development.md

@@ -1,315 +1,53 @@
-# Gateway Development Guide
+# Building a gateway
 
-This guide shows how to build custom gateways to extend FlowChat to new platforms and services. FlowChat's pluggable architecture makes it easy to add support for SMS, Telegram, Slack, voice calls, or any other conversational platform.
+A gateway adapts one messaging platform to FlowChat. It is the first and last layer of the middleware stack: it parses the platform's inbound webhook into normalized context values on the way in, and renders the flow's output back to the platform on the way out. FlowChat ships gateways for USSD (Nalo), WhatsApp, Telegram, HTTP, and Intercom; write your own to support anything else.
 
-## Gateway Interface
+## The contract
 
-Every gateway must implement the basic interface:
-
-> **Note:** The examples in this guide are illustrative implementations to demonstrate the concepts. They are not part of the FlowChat codebase and would need additional work to be production-ready.
-
-```ruby
-class YourCustomGateway
-  # Required: Initialize with app and optional configuration
-  def initialize(app, *config_args)
-    @app = app
-    @config = config_args.first
-  end
-
-  # Required: Process requests through the middleware stack
-  def call(context)
-    # 1. Parse platform-specific request
-    parse_request(context)
-    
-    # 2. Process through FlowChat middleware stack
-    type, prompt, choices, media = @app.call(context)
-    
-    # 3. Render platform-specific response
-    render_response(type, prompt, choices, media, context)
-  end
-
-  # Optional: Configure platform-specific middleware
-  def self.configure_middleware_stack(builder, custom_middleware)
-    builder.use YourPlatform::SpecialMiddleware
-    builder.use custom_middleware
-    builder.use YourPlatform::ResponseMiddleware
-  end
-end
-```
-
-## Example: Telegram Gateway (Hypothetical)
-
-Here's how you would build a complete Telegram Bot API gateway:
-
-```ruby
-module MyCompany
-  module Telegram
-    module Gateway
-      class BotAPI
-        include FlowChat::Instrumentation
-
-        def initialize(app, bot_token)
-          @app = app
-          @bot_token = bot_token
-          @api_base = "https://api.telegram.org/bot#{@bot_token}"
-        end
-
-        def call(context)
-          # 1. Parse Telegram webhook payload
-          payload = parse_telegram_webhook(context)
-          
-          # 2. Set FlowChat context
-          set_flowchat_context(context, payload)
-          
-          # 3. Process through middleware stack
-          type, prompt, choices, media = @app.call(context)
-          
-          # 4. Send response via Telegram API
-          send_telegram_response(type, prompt, choices, media, context)
-        end
-
-        # Optional: Configure Telegram-specific middleware
-        def self.configure_middleware_stack(builder, custom_middleware)
-          builder.use MyCompany::Telegram::Middleware::MessageProcessor
-          builder.use custom_middleware
-          builder.use MyCompany::Telegram::Middleware::ResponseFormatter
-        end
-
-        private
-
-        def parse_telegram_webhook(context)
-          body = context.controller.request.body.read
-          JSON.parse(body)
-        rescue JSON::ParserError => e
-          Rails.logger.error "Telegram: Invalid JSON: #{e.message}"
-          raise "Invalid webhook payload"
-        end
-
-        def set_flowchat_context(context, payload)
-          message = payload.dig("message")
-          callback_query = payload.dig("callback_query")
-          
-          if message
-            # Regular message
-            context["request.user_id"] = message.dig("from", "id").to_s
-            context["request.message_id"] = message["message_id"].to_s
-            context["request.platform"] = :telegram
-            context["request.gateway"] = :telegram_bot_api
-            context["request.timestamp"] = Time.at(message["date"]).iso8601
-            context.input = message["text"]
-            
-            # Telegram-specific data
-            context["telegram.chat_id"] = message.dig("chat", "id")
-            context["telegram.username"] = message.dig("from", "username")
-            
-          elsif callback_query
-            # Button press
-            context["request.user_id"] = callback_query.dig("from", "id").to_s
-            context["request.platform"] = :telegram
-            context.input = callback_query["data"]  # Button callback data
-            
-            context["telegram.chat_id"] = callback_query.dig("message", "chat", "id")
-            context["telegram.callback_query_id"] = callback_query["id"]
-          end
-        end
-
-        def send_telegram_response(type, prompt, choices, media, context)
-          chat_id = context["telegram.chat_id"]
-          
-          response_data = {
-            chat_id: chat_id,
-            text: prompt
-          }
-
-          # Add inline keyboard for choices
-          if choices.present?
-            keyboard = build_inline_keyboard(choices)
-            response_data[:reply_markup] = { inline_keyboard: keyboard }
-          end
-
-          # Send message via Telegram API
-          send_telegram_api_request("sendMessage", response_data)
-        end
-
-        def build_inline_keyboard(choices)
-          # Convert FlowChat choices to Telegram inline keyboard
-          buttons = choices.map do |value, text|
-            [{ text: text, callback_data: value }]
-          end
-          buttons
-        end
-
-        def send_telegram_api_request(method, data)
-          uri = URI("#{@api_base}/#{method}")
-          
-          http = Net::HTTP.new(uri.host, uri.port)
-          http.use_ssl = true
-          
-          request = Net::HTTP::Post.new(uri)
-          request['Content-Type'] = 'application/json'
-          request.body = data.to_json
-          
-          response = http.request(request)
-          
-          unless response.code.to_i.between?(200, 299)
-            Rails.logger.error "Telegram API error: #{response.code} #{response.body}"
-          end
-          
-          response
-        end
-      end
-    end
-  end
-end
-```
-
-## Example: SMS Gateway (Hypothetical)
-
-Here's how you would build an SMS gateway using Twilio:
+A gateway is a middleware object. It takes the next app in its constructor and implements `call(context)`:
 
 ```ruby
 module MyCompany
   module Sms
     module Gateway
       class Twilio
-        include FlowChat::Instrumentation
-
-        def initialize(app, config)
+        def initialize(app, config = nil)
           @app = app
-          @account_sid = config.account_sid
-          @auth_token = config.auth_token
-          @from_number = config.from_number
+          @config = config
         end
 
         def call(context)
-          # Parse Twilio webhook
-          params = context.controller.params
-          
-          # Set FlowChat context
-          context["request.user_id"] = params["From"]
-          context["request.msisdn"] = params["From"]
-          context["request.message_id"] = params["MessageSid"]
-          context["request.platform"] = :sms
-          context["request.gateway"] = :twilio
+          @context = context
+          controller = context.controller
+          params = controller.request.params
+
+          # 1. Parse the inbound webhook into normalized context values.
+          context["request.id"] = params["MessageSid"]
+          context["request.msisdn"] = FlowChat::PhoneNumberUtil.to_e164(params["From"])
+          context["request.user_id"] = context["request.msisdn"]
+          context["request.message_id"] = SecureRandom.uuid
           context["request.timestamp"] = Time.current.iso8601
-          context.input = params["Body"]
-
-          # Process through middleware
-          type, prompt, choices, media = @app.call(context)
-
-          # Send SMS response
-          send_sms(prompt, to: params["From"], context: context)
-        end
-
-        def self.configure_middleware_stack(builder, custom_middleware)
-          # SMS-specific processing
-          builder.use MyCompany::Sms::Middleware::CharacterLimitMiddleware
-          builder.use custom_middleware
-          builder.use MyCompany::Sms::Middleware::ChoiceFormatter
-        end
-
-        private
-
-        def send_sms(message, to:, context:)
-          # Format choices for SMS
-          if context["choices"].present?
-            choice_text = format_choices_for_sms(context["choices"])
-            message = "#{message}\n\n#{choice_text}"
-          end
-
-          # Send via Twilio API
-          twilio_client.messages.create(
-            from: @from_number,
-            to: to,
-            body: message
-          )
-
-          # Instrument message sent
-          instrument(FlowChat::Events::MESSAGE_SENT, {
-            to: to,
-            message: message,
-            platform: :sms,
-            gateway: :twilio,
-            content_length: message.length,
-            timestamp: context["request.timestamp"]
-          })
-        end
-
-        def format_choices_for_sms(choices)
-          choices.map.with_index(1) { |(value, text), i| "#{i}. #{text}" }.join("\n")
-        end
-
-        def twilio_client
-          @twilio_client ||= ::Twilio::REST::Client.new(@account_sid, @auth_token)
-        end
-      end
-    end
-  end
-end
-```
-
-## Custom Middleware
+          context["request.gateway"] = :twilio
+          context["request.platform"] = :sms
+          context["request.body"] = params.to_h.transform_keys(&:to_s)
+          context.input = params["Body"].presence || ""
 
-Gateways can define their own middleware for platform-specific processing:
+          # 2. Run the rest of the stack. It returns [type, prompt, choices, media].
+          type, prompt, choices, _media = @app.call(context)
 
-```ruby
-module MyCompany
-  module Telegram
-    module Middleware
-      class MessageProcessor
-        def initialize(app)
-          @app = app
-        end
-
-        def call(context)
-          # Pre-process Telegram-specific features
-          handle_telegram_commands(context)
-          handle_telegram_media(context)
-          
-          result = @app.call(context)
-          
-          # Post-process response
-          format_telegram_response(context, result)
-          
-          result
+          # 3. Render the result back to the platform.
+          message = render(prompt, choices)
+          send_sms(message, to: context["request.msisdn"])
         end
 
         private
 
-        def handle_telegram_commands(context)
-          input = context.input
-          return unless input&.start_with?('/')
-
-          # Handle Telegram bot commands
-          command = input.split.first
-          context["telegram.command"] = command
-          
-          case command
-          when "/start"
-            context.input = nil  # Start fresh conversation
-          when "/help"
-            context.input = "help"
-          when "/cancel"
-            context.input = "cancel"
-          end
+        def render(prompt, choices)
+          # Turn prompt + choices into whatever the platform expects.
         end
 
-        def handle_telegram_media(context)
-          # Handle photos, documents, etc.
-          # Implementation depends on your needs
-        end
-
-        def format_telegram_response(context, result)
-          # Format response for Telegram's markdown
-          type, prompt, choices, media = result
-          
-          if prompt.is_a?(String)
-            # Escape special Telegram markdown characters
-            prompt = prompt.gsub(/[_*\[\]()~`>#+=|{}.!-]/, '\\\\\&')
-            result[1] = prompt
-          end
-          
-          result
+        def send_sms(message, to:)
+          # Call the platform API.
         end
       end
     end
@@ -317,407 +55,105 @@ module MyCompany
 end
 ```
 
-## Using Your Custom Gateway
+`@app.call(context)` returns a four-element array: `[type, prompt, choices, media]`. `type` is `:prompt` while the conversation continues and `:terminal` when it has ended. `prompt` is the message text, `choices` is a hash of choice keys to labels (or `nil`), and `media` is an outbound media hash (or `nil`).
 
-Once built, use your gateway like any other:
+Use the gateway with `use_gateway`, passing any constructor arguments after the class:
 
 ```ruby
-class TelegramController < ApplicationController
-  def webhook
-    processor = FlowChat::Processor.new(self) do |config|
-      config.use_gateway MyCompany::Telegram::Gateway::BotAPI, telegram_bot_token
-      config.use_session_store FlowChat::Session::CacheSessionStore
-      config.use_durable_sessions  # Use user_id for persistent sessions
-    end
-
-    processor.run WelcomeFlow, :start
-  end
-
-  private
-
-  def telegram_bot_token
-    ENV["TELEGRAM_BOT_TOKEN"]
-  end
-end
-```
-
-## Gateway Configuration
-
-### Configuration Objects
-
-Create configuration classes for complex gateways:
-
-```ruby
-module MyCompany
-  module Slack
-    class Configuration
-      attr_accessor :bot_token, :signing_secret, :app_token
-      attr_accessor :default_channel, :enable_threads
-
-      def initialize
-        @enable_threads = true
-        @default_channel = "#general"
-      end
-
-      def validate!
-        raise "bot_token required" if bot_token.blank?
-        raise "signing_secret required" if signing_secret.blank?
-      end
-    end
-  end
-end
-
-# Usage
-slack_config = MyCompany::Slack::Configuration.new
-slack_config.bot_token = ENV["SLACK_BOT_TOKEN"]
-slack_config.signing_secret = ENV["SLACK_SIGNING_SECRET"]
-
 processor = FlowChat::Processor.new(self) do |config|
-  config.use_gateway MyCompany::Slack::Gateway::BoltJS, slack_config
+  config.use_gateway MyCompany::Sms::Gateway::Twilio, sms_config
+  config.use_session_store FlowChat::Session::CacheSessionStore
 end
 ```
 
-### Environment-Based Configuration
+## Context values to set
 
-```ruby
-class MyCompany::Sms::Gateway::Twilio
-  def initialize(app, config = nil)
-    @app = app
-    
-    # Use config object or fall back to environment
-    if config
-      @account_sid = config.account_sid
-      @auth_token = config.auth_token
-      @from_number = config.from_number
-    else
-      @account_sid = ENV["TWILIO_ACCOUNT_SID"]
-      @auth_token = ENV["TWILIO_AUTH_TOKEN"]
-      @from_number = ENV["TWILIO_FROM_NUMBER"]
-    end
-    
-    validate_configuration!
-  end
+The session middleware and `FlowChat::App` read normalized keys off the context. Set the ones your platform can provide:
 
-  private
+| Key | Purpose |
+|---|---|
+| `request.id` | The platform's session or conversation id. |
+| `request.user_id` | A stable per-user id (used by `use_durable_sessions`). |
+| `request.msisdn` | The user's phone number in E.164, when available. |
+| `request.message_id` | A unique id for this message. |
+| `request.timestamp` | ISO8601 time of the message. |
+| `request.gateway` | Your gateway's symbol, for example `:twilio`. |
+| `request.platform` | The platform symbol, for example `:sms`. |
+| `request.body` | The raw request payload, with string keys. |
+| `context.input` | The turn's text (a caption or `""` when the turn carries only an attachment). |
+| `request.media` / `request.location` / `request.contact` | Structured attachments, when present. |
 
-  def validate_configuration!
-    required = [@account_sid, @auth_token, @from_number]
-    raise "Twilio configuration incomplete" if required.any?(&:blank?)
-  end
-end
-```
+The full list and how each existing gateway populates it is in [gateway-context-variables.md](gateway-context-variables.md).
 
-## Testing Custom Gateways
+## Adding platform middleware
 
-### Unit Testing
+If your platform needs its own middleware (USSD adds pagination and choice-number mapping), define `self.configure_middleware_stack(builder, custom_middleware)`. The processor calls it in place of the default custom-middleware step, so you decide where your middleware and the user's sit:
 
 ```ruby
-# test/unit/telegram_gateway_test.rb
-class TelegramGatewayTest < Minitest::Test
-  def setup
-    @mock_app = proc { |context| [:text, "Test response", {}, nil] }
-    @gateway = MyCompany::Telegram::Gateway::BotAPI.new(@mock_app, "test_token")
-  end
-
-  def test_parses_telegram_message
-    context = create_mock_context(telegram_payload: {
-      "message" => {
-        "from" => { "id" => 12345, "username" => "testuser" },
-        "text" => "Hello",
-        "message_id" => 123
-      }
-    })
-
-    @gateway.call(context)
-
-    assert_equal "12345", context["request.user_id"]
-    assert_equal :telegram, context["request.platform"]
-    assert_equal "Hello", context.input
-  end
-
-  def test_handles_callback_queries
-    context = create_mock_context(telegram_payload: {
-      "callback_query" => {
-        "from" => { "id" => 12345 },
-        "data" => "button_value",
-        "id" => "callback123"
-      }
-    })
-
-    @gateway.call(context)
-
-    assert_equal "button_value", context.input
-    assert_equal "callback123", context["telegram.callback_query_id"]
-  end
-
-  private
-
-  def create_mock_context(telegram_payload:)
-    controller = Minitest::Mock.new
-    request = Minitest::Mock.new
-    
-    request.expect :body, StringIO.new(telegram_payload.to_json)
-    controller.expect :request, request
-    
-    context = FlowChat::Context.new
-    context["controller"] = controller
-    context
-  end
+def self.configure_middleware_stack(builder, custom_middleware)
+  builder.use MyCompany::Sms::Middleware::Segmentation
+  builder.use custom_middleware
 end
 ```
 
-### Integration Testing
+`custom_middleware` is the app's own custom-middleware builder. Include it, or the middleware a user added with `use_middleware` will not run.
 
-```ruby
-# test/integration/telegram_flow_test.rb
-class TelegramFlowTest < ActionDispatch::IntegrationTest
-  def test_complete_telegram_conversation
-    # Simulate Telegram webhook for /start command
-    post telegram_webhook_path, 
-      params: telegram_message_payload(text: "/start"),
-      headers: telegram_headers
-
-    assert_response :success
-
-    # Simulate button press
-    post telegram_webhook_path,
-      params: telegram_callback_payload(data: "option_1"),
-      headers: telegram_headers
-
-    assert_response :success
-  end
+## Writing a choice mapper
 
-  private
-
-  def telegram_message_payload(text:)
-    {
-      message: {
-        from: { id: 12345, username: "testuser" },
-        text: text,
-        message_id: rand(1000),
-        date: Time.current.to_i
-      }
-    }.to_json
-  end
+A choice mapper turns what the platform sends back into the key the flow branches on. Get one rule right and the rest follows:
 
-  def telegram_headers
-    {
-      "Content-Type" => "application/json"
-    }
-  end
-end
-```
+> **Decide ambiguity under the same equivalence your resolver matches on.**
 
-## Advanced Gateway Features
+Every choice bug FlowChat has had came from breaking it — the resolver normalised input one way, and nothing checked whether two choices became indistinguishable under that normalisation, so one of them silently became unreachable.
 
-### File Upload Support
+`FlowChat::ChoiceTitles` enforces the rule for you. Pass it the `fold` your resolver applies and the `measure` your platform sizes fields in, and it hands back titles that are guaranteed distinct — numbering the whole set when they otherwise would not be:
 
 ```ruby
-def handle_file_upload(context, telegram_payload)
-  message = telegram_payload["message"]
-  
-  if message["photo"]
-    # Handle photo upload
-    photo = message["photo"].last  # Get highest resolution
-    file_info = get_telegram_file(photo["file_id"])
-    
-    context["request.media"] = {
-      type: "image",
-      file_id: photo["file_id"],
-      url: download_telegram_file(file_info["file_path"])
-    }
-    
-    context.input = "$media$"  # Special input to indicate media
-    
-  elsif message["document"]
-    # Handle document upload
-    doc = message["document"]
-    context["request.media"] = {
-      type: "document",
-      file_id: doc["file_id"],
-      filename: doc["file_name"],
-      mime_type: doc["mime_type"]
-    }
-    
-    context.input = "$document$"
-  end
-end
+FlowChat::ChoiceTitles.build(choices, title_cap, measure: :characters)
+# => [[key, original_label, displayed_title, was_truncated], ...]
 ```
 
-### Real-time Updates
+Then make the displayed title the value you put on the wire. It is already unique within the set, so it needs no separate id space to be unique in — a tap sends it back as the payload, and a user who types what they read sends the same string, so one map resolves both.
 
-```ruby
-class MyCompany::Slack::Gateway::BoltJS
-  def call(context)
-    # ... standard processing ...
-    
-    # Send typing indicator for long operations
-    if processing_time_estimate > 2.seconds
-      send_typing_indicator(context["slack.channel"])
-    end
-    
-    # ... continue processing ...
-  end
+**The best fold is no fold, and today no mapper uses one:**
 
-  private
+| Mapper | Resolves on | Measure |
+|---|---|---|
+| WhatsApp, Messenger, Instagram | the displayed title, matched exactly | characters |
+| Telegram | the displayed title, cut to `callback_data`'s limit | **bytes** |
+| HTTP | the displayed title, matched exactly | characters |
+| USSD, Intercom | the position printed beside each option | — |
 
-  def send_typing_indicator(channel)
-    slack_client.web_client.conversations_typing(channel: channel)
-  end
-end
-```
+USSD and Intercom are the strongest form of the rule: positions are unique whatever the labels say, so their equivalence relation is already injective and there is nothing to check. If your platform prints a number and asks for one, do that and you need none of this. Intercom used to match labels case-insensitively as well, and that is exactly what made two options reading the same collapse onto one entry — the number beside them was already doing that job unambiguously.
 
-### Multi-Message Responses
+The rest match exactly, because a tapped payload and a client-echoed string are both produced by machines rather than typed. Every transform that could absorb a drift in those strings can also merge two choices, so none is worth adding on speculation. If you do add one — a platform where a person types freely might justify case folding — pass it as `fold:` so the ambiguity check uses it too, and expect more sets to be numbered as a result.
 
-```ruby
-def send_slack_response(type, prompt, choices, media, context)
-  channel = context["slack.channel"]
-  
-  # Send main message
-  response = slack_client.web_client.chat_postMessage(
-    channel: channel,
-    text: prompt
-  )
-  
-  # Send media as separate attachment if present
-  if media.present?
-    slack_client.web_client.files_upload(
-      channels: channel,
-      file: media[:url],
-      title: media[:filename]
-    )
-  end
-  
-  # Add interactive buttons if choices present
-  if choices.present?
-    slack_client.web_client.chat_update(
-      channel: channel,
-      ts: response.ts,
-      text: prompt,
-      blocks: build_slack_blocks(choices)
-    )
-  end
-end
-```
+Where the number is already on screen — Intercom's numbered list, or the Meta `:numbered` rung — the mapper does not prefix anything, because the renderer is doing it. Prefixing in both places reads as `1. 1. Savings`.
 
-## Best Practices
+Number the set rather than disambiguating with a suffix. A position prefix sits at the front and survives truncation from the right, which is what makes it work even on a platform as tight as Telegram's 64 bytes; a suffix is the first thing a cut removes.
 
-### Error Handling
+## Supporting async
 
-```ruby
-def call(context)
-  parse_request(context)
-  type, prompt, choices, media = @app.call(context)
-  render_response(type, prompt, choices, media, context)
-rescue JSON::ParserError => e
-  Rails.logger.error "Gateway: Invalid JSON payload: #{e.message}"
-  send_error_response("Invalid request format", context)
-rescue NetworkError => e
-  Rails.logger.error "Gateway: Network error: #{e.message}"
-  send_error_response("Service temporarily unavailable", context)
-rescue => e
-  Rails.logger.error "Gateway: Unexpected error: #{e.class.name}: #{e.message}"
-  Rails.logger.debug e.backtrace.join("\n")
-  send_error_response("An error occurred", context)
-end
-```
-
-### Rate Limiting
+Include `FlowChat::GatewayAsyncSupport` to let the gateway run flows in a background job. The concern provides `should_enqueue_async?` (true when async is enabled, the gateway supports it, and the request is not already running in the background) and `enqueue_async_job` (serializes the request and enqueues the job). Override `async_supported?` to return `false` on a synchronous protocol:
 
 ```ruby
-def call(context)
-  check_rate_limit(context["request.user_id"])
-  # ... continue processing ...
-end
-
-private
-
-def check_rate_limit(user_id)
-  key = "rate_limit:#{user_id}"
-  count = Rails.cache.increment(key, 1, expires_in: 1.minute) || 1
-  
-  if count > 30  # 30 requests per minute
-    raise RateLimitExceeded, "Too many requests"
-  end
-end
-```
+class Twilio
+  include FlowChat::GatewayAsyncSupport
 
-### Security
-
-```ruby
-def call(context)
-  verify_webhook_signature(context)
-  # ... continue processing ...
-end
-
-private
+  def call(context)
+    @context = context
+    @controller = context.controller
+    return if enqueue_async_job   # enqueued; respond immediately
 
-def verify_webhook_signature(context)
-  signature = context.controller.request.headers["X-Platform-Signature"]
-  payload = context.controller.request.body.read
-  
-  expected = generate_signature(payload, @webhook_secret)
-  
-  unless secure_compare(signature, expected)
-    raise SecurityError, "Invalid webhook signature"
+    # ... otherwise process inline as above
   end
 end
-
-def secure_compare(a, b)
-  return false unless a.bytesize == b.bytesize
-  
-  l = a.unpack("C*")
-  r = b.unpack("C*")
-  
-  l.zip(r).reduce(0) { |sum, (x, y)| sum | (x ^ y) } == 0
-end
-```
-
-## Publishing Your Gateway
-
-### Gem Structure
-
-If you're building a reusable gateway, structure it as a gem:
-
 ```
-my_platform_gateway/
-├── lib/
-│   └── flow_chat/
-│       └── my_platform/
-│           ├── gateway.rb
-│           ├── configuration.rb
-│           ├── middleware/
-│           └── renderer.rb
-├── spec/
-├── README.md
-└── my_platform_gateway.gemspec
-```
-
-### Documentation
-
-Document your gateway's:
-- Installation instructions
-- Configuration options
-- Platform-specific features
-- Middleware stack
-- Testing helpers
-
-### Examples
-
-Provide working examples:
 
-```ruby
-# examples/basic_controller.rb
-class MyPlatformController < ApplicationController
-  def webhook
-    processor = FlowChat::Processor.new(self) do |config|
-      config.use_gateway FlowChat::MyPlatform::Gateway, platform_config
-      config.use_session_store FlowChat::Session::CacheSessionStore
-    end
+`enqueue_async_job` returns `false` when async should not be used (for example when the request is already the background job), so you fall through to inline processing. See [async-background-processing.md](async-background-processing.md).
 
-    processor.run WelcomeFlow, :start
-  end
-end
-```
+## Related
 
-Custom gateways make FlowChat incredibly powerful and flexible. With this foundation, you can integrate virtually any conversational platform into FlowChat's unified framework. 
+- [Architecture](architecture.md)
+- [Gateway context variables](gateway-context-variables.md)
+- [Async and background processing](async-background-processing.md)