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

# Connecting to the backend

> How your Archie frontend talks to Archie Core — typed API client, authentication tokens, and real-time subscriptions.

The frontend connects to [Archie Core](/features/backend/overview) through a generated, typed API client. Your data, auth, file storage, and real-time subscriptions all flow through this client.

## The API client

When you build, Archie generates a TypeScript client for your project's API surface. It includes:

* One method per GraphQL query, mutation, and subscription
* One method per REST endpoint
* Type definitions matching your data model
* Error types for each failure mode

The client lives in `lib/api/` (or your stack's equivalent). Use it from any component:

```typescript theme={null}
import { api } from '@/lib/api'

const { data } = api.orders.list({ status: 'active' })
```

The client handles authentication, request signing, retries, and error formatting. You write one line; the client handles the rest.

## Authentication tokens

The API client picks up the active session token automatically. When a user signs in, their token is stored (httpOnly cookie by default) and attached to subsequent requests. Sign-out clears the token.

Three flows are wired:

* **Browser session** — the user's auth token, used for browser-side calls
* **Server-side** — for SSR/RSC, the framework reads the cookie on each request
* **External clients** — server-to-server callers use [API keys](/features/backend/settings/api-keys) instead of session tokens

## Real-time subscriptions

For data that changes live (an order list, a chat thread, a dashboard counter), use a subscription:

```typescript theme={null}
const orders = api.orders.subscribe({ status: 'active' })
```

Subscriptions use GraphQL over WebSocket. The hook returns the live data and re-renders your component when the data changes. Cleanup happens automatically when the component unmounts.

## File uploads

Files upload through a dedicated endpoint:

```typescript theme={null}
const url = await api.files.upload(file)
```

The client returns a URL you can store and reference. Behind the scenes, the upload streams to your project's [file storage provider](/features/backend/app-services/file-manager).

## Error handling

Each method's return type includes typed errors. You handle errors with normal try/catch or by checking the result:

```typescript theme={null}
try {
  await api.orders.create(orderData)
} catch (err) {
  if (err.code === 'INSUFFICIENT_INVENTORY') {
    // ...
  }
}
```

Common errors (auth, validation, server) have shared types. Spec-level rules generate domain-specific error types automatically.

## Environments

The client picks up the active environment automatically. In development, it points at your dev environment's API URL. In production, it points at production. See [Environments](/features/backend/environments/overview) for the full setup.

## Custom requests

For requests outside the auto-generated surface (calling a custom function with a non-standard signature, calling a third-party API), use the lower-level fetch utilities the client exposes. Or write a [custom function](/features/backend/custom-functions/overview) that wraps the call and exposes it through the typed API.

## Performance

The client batches GraphQL queries by default — multiple component-level queries on a page resolve in one network request. Subscriptions multiplex over a single WebSocket. You write per-component data needs; the client makes them efficient.