SveltyCMS provides a comprehensive programmatic surface for building custom frontends, automating workflows, and synchronizing external data. Built on a architecture that supports the fastest unified OpenAPI specification, it enables maximum flexibility for any setup — from simple headless blogs to enterprise-grade multi-tenant platforms.

---

⚡ Core Access Patterns

Pattern	Context	Latency	Best For
🎯 Remote Functions	Client→Server (.server.ts)	Typed	Auth, Setup, User profile forms
⚡ Local SDK	Server-side (.server.ts)	0–5ms	Native SvelteKit, high-throughput
🌐 REST API	External (Mobile, Apps)	50–150ms	Simple CRUD & Integrations
📊 GraphQL API	Frontend (React, Vue, SPA)	50–200ms	Complex data fetching
🔌 GraphQL Subscriptions	Real-time (WebSocket)	<50ms	Live updates, collaborative editing
📖 OpenAPI Spec	Documentation & SDKs	Unified	Fastest automated client generation

---

🎯 Remote Functions (2026 Architecture) {#remote-functions-2026-architecture}

SveltyCMS uses SvelteKit Remote Functions (.server.ts files) for type-safe client-to-server communication. These replace traditional form actions and manual fetch() calls with fully typed async functions that provide complete TypeScript inference between components and server logic.

File Structure

src/routes/
├── login/
│   ├── +page.server.ts     ← load, OAuth redirects, 2FA, resetSetup
│   └── auth.server.ts      ← signIn, signUp, forgotPW, resetPW, prefetch (592 lines)
├── setup/
│   ├── +page.server.ts     ← load, installDriver (~200 lines)
│   └── setup.server.ts     ← testDatabaseConnection, seedDatabase, completeSetup, testEmailConnection, testRedisConnection (665 lines)
└── (app)/user/
    ├── +page.server.ts     ← load
    └── user.server.ts      ← uploadAvatar, updateUserProfile, createToken, exportUserData, anonymizeAccount
```

### Enterprise Gains (Measured)

| Metric                   | Before (Form Actions)               | After (Remote Functions)                                      |
| ------------------------ | ----------------------------------- | ------------------------------------------------------------- |
| `login/+page.server.ts`  | 1,625 lines                         | **310 lines (-81%)**                                          |
| `setup/+page.server.ts`  | 1,345 lines                         | ~200 lines (-85%)                                             |
| Type safety              | `formData.get("email")?.toString()` | `signIn(email: string, password: string, event)`              |
| Rate limiting            | Embedded in monolithic file         | Explicit `RateLimiter` per function — auditable               |
| Timing-attack mitigation | Buried in 1,625-line file           | Explicit argon2 verify visible in `signIn`                    |
| Audit logging            | Interleaved with form parsing       | Fire-and-forget at function boundaries                        |
| Testability              | Requires full SvelteKit event mock  | Plain async functions with typed params                       |
| Security audit surface   | 2,970 lines across 2 monoliths      | 510 lines (page servers) + 1,524 lines (organized .server.ts) |

### Available Remote Functions

| Module                      | Functions                                                                                                                                                                   | Security Preserved                                               |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `login/auth.server.ts`      | `signIn`, `signUp`, `forgotPW`, `resetPW`, `prefetchFirstCollection`                                                                                                        | Rate limiting, Argon2id, timing-attack mitigation, audit logging |
| `setup/setup.server.ts`     | `testDatabaseConnection`, `seedDatabase`, `completeSetup`, `testEmailConnection`, `testRedisConnection`                                                                     | Valibot validation, setup gating, preset-based seeding           |
| `(app)/user/user.server.ts` | `uploadAvatar`, `deleteAvatar`, `updateUserProfile`, `verifyPassword`, `batchUserAction`, `createToken`, `updateToken`, `deleteToken`, `exportUserData`, `anonymizeAccount` | CSRF tokens, RBAC                                                |

### What Stays as Form Actions

OAuth redirects (`signInOAuth`, `signInOAuthGithub`), 2FA verification (`verify2FA` — hidden form for CSRF), setup reset (`resetSetup` — disk I/O), and driver installation (`installDriver` — spawn-based) remain as traditional form actions because they involve browser redirects, hidden form patterns, or OS-level operations.

---

## 🛡️ Unified Gatekeeper Architecture

SveltyCMS uses a high-performance **Unified Gatekeeper** (`src/routes/api/[...path]`) that dispatches requests to domain-specific handlers.

### Key Benefits

- **Zero-Latency Dispatching**: Internal server-to-server calls bypass HTTP overhead via the `LocalCMS` bridge.
- **Fail-Closed Security**: Every request must pass central authorization before being dispatched.
- **ETag Conditional Requests**: All GET 200 responses include XXH3 (xxhash64) ETag headers via `hash-wasm` — a high-performance non-cryptographic hash ~10× faster than SHA-256. Clients sending `If-None-Match` receive `304 Not Modified` with zero body when content hasn't changed.
- **API Versioning**: All responses include `X-API-Version: 1` header. `/api/v1/` path prefix automatically routes to the current API version.

---

## 📚 Complete API Reference (Handler Based)

### Content & Data

- [📚 **Collections (collections.ts)**](/docs/reference/api/collections) — Entry CRUD, schema discovery, and revisions.
- [🔍 **Content & Search (content.ts)**](/docs/reference/api/content) — Global search, SSE events, and GraphQL.
- [🖼️ **Media (media.ts)**](/docs/reference/api/media) — Asset uploads, processing, and folder management.

### Identity & Access

- [👥 **Auth & Identity (auth.ts)**](/docs/reference/api/auth) — Login, 2FA, SAML SSO, and Profiles.
- [🔐 **Tokens (tokens.ts)**](/docs/reference/api/tokens) — Invitation links and programmatic API keys.
- [🌐 **SCIM 2.0 (scim.ts)**](/docs/reference/api/scim) — Standardized user provisioning.

### System & Infrastructure

- [⚙️ **System & Setup (system.ts / setup.ts)**](/docs/reference/api/system) — Settings, widgets, webhooks, AI translation, and job scheduling.
- [📈 **Dashboard (dashboard.ts)**](/docs/reference/api/dashboard) — Metrics, logs, and health data.
- [🛠 **Utilities (utility.ts)**](/docs/reference/api/utility) — Cache, trash, and email services.

**New** `GET /api/health`, `POST /api/system-jobs`, `POST /api/ai/translate`

### 📦 Data Operations

APIs for configuration promotion, content transfer, migrations, importers, backups, and content sync.

- [📤 **Configuration Promotion**](/docs/reference/api/configuration-promotion) — Promote CMS structure between environments with plan-first workflow.
- [📦 **Content Transfer**](/docs/reference/api/content-transfer) — Export/import editorial content as portable packages with NDJSON streaming.
- [🔄 **Data Migrations**](/docs/reference/api/data-migrations) — Idempotent schema/data transformations with locking and risk scoring.
- [📥 **External Importers**](/docs/reference/api/importers) — Import from WordPress, Drupal, CSV, JSON, and other sources.
- [💾 **Backups & Restore**](/docs/reference/api/backups) — Encrypted disaster recovery with manifest validation and restore plans.
- [🔁 **Content Sync**](/docs/reference/api/content-sync) — Controlled cross-environment content synchronization.

---

## 📡 Response Strategy

All REST endpoints follow a unified response shape:

### Success (200 / 201)

```
{ "success": true, "data": { ... } }
```

### Error (4xx / 5xx)

```
{ "success": false, "error": "UNAUTHORIZED", "message": "Invalid Bearer token." }
```

---

**Next Steps**: Start with the [Collections Reference](/docs/reference/api/collections) for data fetching. For real-time updates, see [Content & Search](/docs/reference/api/content). For type-safe client-server calls, use [Remote Functions](#remote-functions-2026-architecture).