> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chatropic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> How the embed and SDK interact with the agent runtime

Whether the chat UI is the web embed or the React Native SDK, the flow is the same: the widget sends the user's message to the agent runtime, the runtime plans a single turn (retrieve knowledge, call an action if needed, compose a reply), and the widget renders the streamed reply along with any structured UI.

## Message lifecycle

```mermaid theme={null}
sequenceDiagram
    participant User as Customer
    participant Widget as Chat UI (web embed / RN SDK)
    participant Agent as Agent runtime
    participant KB as Knowledge
    participant API as Your APIs

    User->>Widget: Types a message
    Widget->>Agent: Authenticated turn (publishable key, tenant)
    Agent->>Agent: Understand intent & plan
    Agent->>KB: Retrieve relevant context
    KB-->>Agent: Grounding snippets
    alt Action needed
        Agent->>API: Execute configured action
        API-->>Agent: Structured result
    end
    Agent-->>Widget: Streamed text + optional UI payload
    Widget-->>User: Rendered reply, widgets, navigation cards
```

<Info>
  The integration surface is **messages**, **sessions**, and **UI payloads**. Internal graph nodes, service routes, and model configuration stay server-side and are managed in the dashboard.
</Info>

## Knowledge grounding

```mermaid theme={null}
flowchart LR
    A[User question] --> B[Retrieval]
    B --> C[Ranked chunks]
    C --> D[Compose reply]
    D --> E[Grounded answer]
```

Builders manage sources in the dashboard under **Sources**. Your integration does not need to know which documents exist; answers arrive already grounded.

## Sessions

Each conversation runs on a session that carries memory across turns, so the agent can ask follow-up questions and fill in missing details without a dialog state machine in your app. The web embed creates an anonymous session per visitor automatically, and the React Native SDK can persist sessions locally. See [Messages & sessions](/developer-guides/integration/messages-and-sessions).

## Tenant isolation

Every publishable key maps to exactly one workspace. A widget or app using your key can only reach your workspace's agent, knowledge, and actions.

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/developer-guides/quick-start/quickstart">
    First message from your React Native app.
  </Card>

  <Card title="Authentication & identity" icon="key" href="/developer-guides/quick-start/authentication">
    Keys and signed-in user identity.
  </Card>
</CardGroup>