SF Agent Platform — Architecture flow

flowchart LR
  U[End User] --> D[Next.js Dashboard]
  U --> API[FastAPI Backend]
  D --> API
  API --> MCP[FastMCP Server]
  API --> BR[AWS Bedrock Runtime]
  API --> PG[(PostgreSQL)]
  API --> SF[(Salesforce OAuth + APIs)]
  MCP --> PG
  MCP --> SF

sequenceDiagram
  participant Client
  participant Backend as FastAPI /api/chat/stream
  participant Agent as Conversation Agent
  participant MCP as MCP Tools (loaded)
  participant Bedrock as Bedrock LLM

  Client->>Backend: POST message + session_id
  Backend->>Agent: run_agent_turn(...)
  Agent->>Bedrock: prompt + chat_history + retrieval
  alt tool required
    Agent->>MCP: invoke tool (register/reset/list/create ticket)
    MCP-->>Agent: SUCCESS/FAILED/TOOL_INCOMPLETE
  end
  Agent-->>Backend: final text
  Backend-->>Client: SSE chunks + done

sequenceDiagram
  participant Backend as FastAPI Lifespan
  participant Adapter as langchain-mcp-adapters
  participant MCP as FastMCP HTTP /mcp
  participant Registry as mcp_client registry

  Backend->>Adapter: MultiServerMCPClient(...).get_tools()
  Adapter->>MCP: discover tools
  MCP-->>Adapter: tool schemas
  Adapter-->>Backend: tool objects
  Backend->>Registry: set_mcp_langchain_tools(tools)
  Note over Registry: wraps async-only tools with sync shim

sequenceDiagram
  participant UI as Dashboard/API Client
  participant Backend as FastAPI tickets route
  participant Repo as ticket_repository
  participant Scheduler as run_ticket_scheduler_loop
  participant Actions as ticket_triage_actions
  participant Triage as ticket_triage_bedrock
  participant Bedrock as Bedrock LLM
  participant SF as Salesforce

  UI->>Backend: POST /api/tickets {name,description}
  Backend->>Repo: create_ticket(status=pending)
  Repo-->>Backend: ticket_id

  loop every interval
    Scheduler->>Triage: process_pending_tickets_once()
    Triage->>Repo: list_pending_tickets()
    alt account intent inferred
      Triage->>Actions: run_ticket_mcp_actions(ticket)
      Actions->>Bedrock: extract intent JSON
      alt new_user
        Actions->>SF: create user flow
      else password_reset
        Actions->>SF: reset email flow
      end
    end
    Triage->>Bedrock: triage DECISION/REPLY
    Triage->>Repo: update status + agent_reply
  end

flowchart TD
  A[GET /api/users] --> B{salesforce_source_users_api && configured?}
  B -- yes --> C[salesforce_auth.fetch_org_users()]
  C --> D[map to UserListItem]
  D --> E[response]
  B -- no --> F[user_store.list_all()]
  F --> G[map to UserListItem]
  G --> E