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

# Architecture

> The model behind all three SDKs. Read this once and the rest of the API explains itself.

All three SDKs are a thin client over the ClarioDesk backend. They own four things
(a device identity, a local cache, a realtime connection, and an optional set of
prebuilt screens) and expose a small, identical public API on top.

## The contract is tiny

The SDK keeps all of its state internal and private. Your app's state
management (Riverpod, Bloc, Provider, Redux, Zustand, Context, MobX) is never
involved. There are only ever a handful of calls from your app into the SDK:

1. `init(apiKey)` once at app start.
2. `identify({ externalId, email, traits })` when the user logs in or changes.
3. `handlePushPayload(...)` / `openTicketFromPush(...)` when a push fires.
4. `reset()` on logout or user switch.

> That's the entire contract. Your app sends identity and push events in; reads
> come back to you as live streams (Flutter), subscriptions/hooks (React
> Native), or `AsyncStream`s (Swift), not as state you have to wire.

## Headless vs prebuilt

<CardGroup cols={2}>
  <Card title="Headless" icon="code">
    Public methods + live reads only. You build the UI in your own design
    system. This is the primary integration mode.
  </Card>

  <Card title="Prebuilt screens" icon="layout-panel-left">
    Inbox, ticket detail, new ticket, and bug report, presented in a
    self-owned modal. Limited theming (colors + app bar). Minutes to integrate.
  </Card>
</CardGroup>

Both modes ship in the same package. The prebuilt screens are just a
consumer of the same headless methods.

## Routing: the sandbox model

The prebuilt UI never touches your router (GoRouter, Navigator 2.0, React
Navigation, Expo Router). Your app pushes one route (a full-screen modal), and
the SDK owns a private nested navigator inside it for all internal navigation
(inbox → ticket detail → compose → image viewer). Control returns to your app
when the user dismisses the modal.

## Data model

Three objects you'll touch:

| Object         | What it is                                                                                                                        |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Ticket**     | One support conversation. Has a status (`new` → `open` → `resolved` → `closed`), an unread indicator, and a last-message preview. |
| **Message**    | One entry in a ticket thread. Carries `body`, an author type (end user / agent / system), a timestamp, and any `attachments`.     |
| **Attachment** | A photo, video, or file bound to a message. Rendered via presigned URLs.                                                          |

## Where to go next

<CardGroup cols={2}>
  <Card title="Authentication" icon="shield-check" href="/concepts/authentication">
    Why there are no JWTs and the publishable key is safe to ship.
  </Card>

  <Card title="Identity & lifecycle" icon="user-check" href="/concepts/identity-lifecycle">
    The four host events that touch the SDK: login, launch, logout, switch.
  </Card>
</CardGroup>