Backoffice REST as a Framework Channel

This project now treats the TIM/ANATEL Backoffice REST contracts as a corporate channel instead of letting the HTTP routes call a domain workflow executor directly.

Target execution model

Legacy-compatible REST endpoint
        ↓
BackofficeRestChannelAdapter
        ↓
ChannelGateway normalization path
        ↓
BackofficeWorkflowDispatcher
        ↓
Backoffice workflow LangGraph
        ↓
Framework layers: guardrails, supervisor, judges, checkpoint, telemetry, MCP
        ↓
Legacy-compatible REST response adapter

What changed

New files

app/channels/backoffice_rest_adapter.py
- Converts legacy Backoffice REST payloads into BackofficeChannelEnvelope.
- Preserves the original payload under request_context.
- Extracts canonical business_context such as customer_key, contract_key, interaction_key and session_key.
- Passes the request through ChannelGateway.normalize(...) using channel = backoffice_rest.
- Falls back to the web adapter shape when the installed framework does not yet have a dedicated backoffice_rest adapter.
app/workflows/backoffice_workflow_dispatcher.py
- Receives a normalized channel envelope.
- Emits framework telemetry events for channel normalization and workflow dispatch.
- Invokes the correct operational workflow:
  - backoffice_checklist
  - backoffice_response_emulator

Updated file

app/main.py
- The compatibility routes no longer call BackofficeWorkflowExecutor.execute_workflow(...) directly.
- They now call:

BackofficeRestChannelAdapter
        ↓
BackofficeWorkflowDispatcher
        ↓
BackofficeWorkflowExecutor

The BackofficeWorkflowExecutor still owns the compiled LangGraph workflows, but it is now behind the channel/dispatcher boundary rather than being the direct REST entrypoint.

Why this is architecturally cleaner

The REST routes are now only transport adapters. They preserve the old external contract, but the request enters the same conceptual pipeline used by other framework channels.

This avoids the previous coupling:

REST route → BackofficeWorkflowExecutor

and replaces it with:

REST route → channel adapter → ChannelGateway → workflow dispatcher → LangGraph workflow

Compatibility

The existing routes remain available:

POST /agent/process-ticket
POST /agent/execute
POST /agent/process-and-stream
POST /case/{transaction_id}/response-emulator/generate
POST /case/{transaction_id}/response-emulator/finalize

The response builders are preserved, so external clients should not need to change their payload or response handling.

Runtime notes

The metadata added to workflow state now includes:

framework_entrypoint = channel_gateway
channel = backoffice_rest
normalized_channel = backoffice_rest or web fallback
business_context = canonical business keys
channel_context = normalized gateway context

This makes Langfuse/telemetry easier to interpret because Backoffice REST is visible as a channel entrypoint, not as an ad-hoc executor call.

3.1 KiB Raw Blame History