Skip to main content

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.

The frontend connects to Archie Core 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: 
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 instead of session tokens

​
Real-time subscriptions

For data that changes live (an order list, a chat thread, a dashboard counter), use a subscription: 
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: 
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.

​
Error handling

Each method’s return type includes typed errors. You handle errors with normal try/catch or by checking the result: 
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 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 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.