Architecture

​

System overview

User <-> React SPA <-> Cloudflare Worker <-> Claude API
              |               |
          WebSocket    Durable Object (agent state)
                              |
                      SAP Connector (Java/JCo)
                           ^
                workspace_connections (N per workspace)

1. Frontend — React SPA with WebSocket streaming, tool approval UI, and file attachments
2. Worker — Cloudflare Worker handling HTTP routing, auth, rate limiting, and Durable Object orchestration
3. Durable Object — One per agent. Holds conversation state, manages the Claude agentic loop, executes tools, and gates write operations behind approval
4. Connector — Java 21 Spring Boot service that talks to SAP via JCo. Each workspace can configure multiple named SAP connections via workspace_connections

​

Entry point

• Agent — The Durable Object class (re-exported for Cloudflare binding)
• Default { fetch, scheduled } — Worker handlers

​

Durable Object: Agent

​

Persistent state

​

Write-through sync and restoration

1. Messages — Upserted to the messages table (keyed by message ID) after every saveState() call
2. model_messages + llm_model (+ derived llm_provider) — PATCHed to the agents row for lossless restoration and provider/model continuity

1. Fetches messages from the messages table (ordered by seq)
2. Fetches model_messages, llm_provider, and llm_model from the agents row — llm_model is canonicalized to provider:model and provider is derived from it. If model_messages exists, uses it directly (lossless). If null, falls back to rebuildModelMessages() (lossy text-only reconstruction)
3. Re-saves to DO storage for future fast reads

​

In-memory state

• sessions — Map of connected WebSocket clients
• streamingAccumulator / thinkingAccumulator — Partial content for reconnecting clients
• currentAbortController — Active generation controller (for stop support)
• cachedSystemPrompt — System prompt with 5-minute TTL
• userCredentials — Per-request decrypted SAP credentials (never persisted to DO storage)
• sandboxToken / sandboxContextId — Sandbox session state (see Sandbox Code Execution)

​

Request lifecycle

POST /api/agents/:id/message
  → Worker forwards to Durable Object via stub
    → Agent.processUserMessage()
      → Adds message to state
      → Fetches attachments from R2 (PDF/image)
      → Triggers title generation (first message only)
      → Calls generateResponse()

​

Agentic loop: generateResponse()

​

Approval flow

1. Agent broadcasts approval_needed with tool name, arguments, and a unique toolCallId
2. Frontend shows an ApprovalCard for each pending tool
3. User clicks approve or reject (individually or bulk)
4. POST /api/agents/:id/approve resolves the pending entry
5. If approved → tool executes, result stored
6. If rejected → error result stored (“User rejected this tool call”)
7. Once all entries in the group are resolved, checkGroupComplete() merges results and continues the loop

​

WebSocket protocol

​

Tool system

​

Tool definitions

interface ToolDefinition {
  name: string;
  description: string;
  parameters: z.ZodType<any>;    // Validated at runtime
  needsApproval: boolean;       // true = write tool
  returnDescription: string;    // Return dict shape, auto-propagated to execute_code docs
  execute: (args, context) => Promise<unknown>;
}

​

Tool routing

• Examples: sap_read_table, sap_get_table_schema, sap_execute_rfc, sap_search_index
• Single-connection context: connection_id defaults automatically
• Multi-connection context: connection_id is required

​

Server tools (web search & fetch)

​

Cross-system tools

• generate_field_mapping — Compares schemas between source and target
• preview_data_transform — Shows before/after data transformation
• ETL tools (suggest_transforms, validate_migration, extract_transform_load, reconcile_migration)

​

Tool execution context

interface ToolExecutionContext {
  connections?: ConnectionInfo[];
  connectionSecrets?: Record<string, Record<string, string>>;
  userCredentials?: Record<string, { sapUser: string; sapPassword: string }>;
  workspaceId?: string;
  environment?: string;
  searchSapIndex?: (query, category, detail, limit, connectionId, mode?) => Promise<unknown>;
}

​

Connector client

1. POSTs JSON to the connector endpoint
2. Adds X-Connector-Key header when auth.connectorKey is present
3. Adds X-SAP-User / X-SAP-Password headers when user credentials are present
4. Returns response.json().data on success
5. Blocks redirects (security measure)

• Blocks private IPs (10.x, 192.168.x, 172.16-31.x, 169.254.x) and cloud metadata IPs
• Allows localhost/127.x only in non-production environments
• Enforces HTTPS in production

​

System prompt

• Base instructions (SAP domain knowledge, tool usage patterns, safety rules)
• SAP index fingerprint (if the workspace has indexed SAP metadata — includes table counts, BAPI counts, custom object counts)
• ETL execution guidance (mandatory validation → dry run → execute → reconcile)
• Transform type reference (12 valid types)
• BAPI verification rules (verify on target system, not source)

​

Frontend

• AuthContext — Supabase auth session
• DashboardContext — Shared workspace/agent state
• SWR for API data fetching with automatic revalidation

• Frontend accumulates stream WebSocket events into the current message
• stream_end finalizes the message
• Thinking blocks render in a collapsible UI
• Reconnecting clients receive full state (including partial stream content) via the init message

​

Data flow

​

Message storage

• messages table — UI-facing conversation (user, assistant, tool messages with seq ordering). Written via non-blocking upsert after each saveState().
• agents.model_messages — Full provider-agnostic model conversation as JSONB. PATCHed alongside message sync.
• agents.llm_model — Canonical model selection (provider:model) for the agent. agents.llm_provider is derived from this value for compatibility.
• DO ctx.storage — Primary store during active sessions. Provides strong consistency and low latency.

​

File attachments

​

SAP metadata indexing & enrichment

1. Indexing (fast, metadata-only) — runFullIndex() calls the connector phases: index-custom-objects, index-relationships, index-custom-code, index-catalog-context, index-enhancements, and index-s4-extensions (S/4HANA only).
2. Enrichment (slow, doc + analysis) — SAPSyncWorkflow generates docs, infers business processes, runs Clean Core or conversion readiness analysis, and generates embeddings.

​

Sync workflow (Cloudflare Workflows)

1. Probe (/api/sap/probe-changes) to skip no-op delta runs
2. Index metadata with runFullIndex(workspaceId, connectionId, ...) and update workspace_sap_graph
3. Enrich by generating docs, inferring processes, running Clean Core or conversion readiness, and embedding docs