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

# Building a Kralis Client

> Structure authentication, API access, permissions, caching, and school workflows in a custom frontend.

A dependable Kralis client is a presentation and interaction layer over Kralis-owned business rules. It improves the experience without trying to replace server authorization.

## Recommended client layers

```mermaid theme={null}
flowchart TD
    A[Pages and screens] --> B[Feature workflows]
    B --> C[Typed API operations]
    C --> D[Auth and request transport]
    D --> E[Kralis API]
    B --> F[Local UI state]
    C --> G[Normalized or query cache]
```

| Layer               | Responsibility                                                         |
| ------------------- | ---------------------------------------------------------------------- |
| Auth/session        | Login, token refresh, logout, current user and school context          |
| Transport           | API base URL, Bearer header, request cancellation, and network errors  |
| Generated API layer | GraphQL operations and types derived from the current schema           |
| Feature service     | Product-specific variables, pagination, and result normalization       |
| UI                  | Filters, forms, loading states, permission-aware actions, and feedback |

## Model school workflows, not database tables

Use product actions exposed by the API. For example, publishing a Classroom event, generating a result, syncing a CBT score, or promoting students carries rules beyond changing one field.

## Loading and mutation states

Every data-backed screen should distinguish:

| State            | UI behavior                                                         |
| ---------------- | ------------------------------------------------------------------- |
| Initial loading  | Show a skeleton resembling the expected content                     |
| Empty result     | Explain the current filters and useful next action                  |
| Validation error | Keep entered values and show actionable field or operation feedback |
| Permission error | Remove unsafe retry loops and explain that access is unavailable    |
| Network failure  | Offer a bounded retry without duplicating a mutation                |
| Mutation pending | Disable duplicate submission and show progress                      |
| Success          | Update or refetch the affected data and confirm completion          |

## IDs, names, and URLs

Use returned opaque IDs for API variables. Use slugs or names only where the schema or product URL documents them. Do not parse Relay IDs or construct IDs from school acronyms.

## Use Kralis Web alongside your client

Your custom client does not have to reproduce every management screen. Schools can use [Kralis Web](https://kralis.app) for setup and full administration while your client focuses on the experience it is designed to provide.

```mermaid theme={null}
flowchart LR
    A[School operator] --> B[Kralis Web]
    C[Your users] --> D[Custom client]
    B --> E[Kralis API]
    D --> E
    E --> F[One school data model]
```