🎯 Architectural Vision

SveltyCMS leverages a Modular Namespace pattern to organize its database capabilities. Instead of a single monolithic adapter, functionality is divided into specialized domains. This ensures that as the system grows, the database layer remains maintainable, testable, and strictly type-safe.

Core Principle: Write once (in the application layer), deploy everywhere (MongoDB, SQL, etc.).

🛠️ Global Interface Contract

All methods in the SveltyCMS database layer follow the DatabaseResult<T> pattern. They MUST NOT throw exceptions for expected failures; instead, they return a structured object.

export type DatabaseResult<T> =
  | { success: true; data: T; meta?: QueryMeta }
  | { success: false; message: string; error: DatabaseError };

🛡️ auth.* Namespace

Responsibility: Identity, Session Management, and RBAC.

🗂️ collection.* Namespace

Responsibility: Dynamic Schema and Model Management.

⚡ crud.* Namespace

Responsibility: High-performance, standardized data operations.

findPage (shared product path)

Use for admin tables, media grids, and REST/GraphQL list connections. Avoids a default COUNT(*).

import type { FindPageResult } from "@src/databases/db-interface";

const res = await db.crud.findPage<Post>("posts", filter, {
  limit: 50,
  tenantId,
  sort: { updatedAt: -1 },
  fields: ["_id", "title", "status", "updatedAt"],
  total: "none", // or "exact" | "estimate" | "auto"
});

if (res.success) {
  const { items, hasMore, nextCursor, total, totalEstimated }: FindPageResult<Post> = res.data;
}

Files: core/sql-adapter-core.ts, mongodb/crud-methods.ts, core/page-utils.ts.

count modes & short-lived cache

// Exact (billing / RBAC)
await db.crud.count("posts", { status: "publish" }, { tenantId, mode: "exact" });

// Estimate when empty + no tenant (dashboard global size)
await db.crud.count("posts", {}, { mode: "estimate" });

// Force skip L1/L2 count cache
await db.crud.count("posts", filter, { tenantId, bypassCache: true });

See Performance Architecture — Product-layer list & count.

📦 content.* Namespace

Responsibility: CMS Workflows (Nodes, Drafts, Revisions).

🖼️ media.* Namespace

Responsibility: File Metadata and Organization.

⚙️ system.* Namespace

Responsibility: Preferences, Jobs, Multi-Tenancy, and external API credentials.

🔐 Credential Storage (Website Tokens & API Keys)

SveltyCMS treats website tokens and sck_ API keys as credentials, not user records. The database layer enforces the same invariants on all four engines while allowing engine-native optimizations.

Shared contract (ISystemAdapter.websiteTokens)

Per-engine implementation

Indexes (all SQL engines + MongoDB)

• Unique on token (hashed value) — O(1) bearer authentication lookup
• Compound { tenantId, name } — tenant-scoped name resolution and admin list filters

MongoDB-specific notes

• Mongoose strict: true requires every persisted field to be declared on the schema. Undeclared fields (e.g. tenantId) are silently stripped on insert and break tenant-scoped list queries.
• Credential lookup without request tenant context uses bypassTenantCheck only (not bypassSafeQuery), so safeQuery still applies soft-delete boundaries.
• Do not use bypassSafeQuery for routine website-token CRUD; it is reserved for other internal fast-paths documented in the MongoDB implementation guide.

SQL migration note

After pulling schema changes that add the { tenantId, name } compound index, run:

bun run db:push

🚀 Implementation Matrix (Status 2026)

¹ SCIM 2.0 endpoints are production-ready (RFC 7644: Users, Groups, Bulk, filters, PATCH, Okta/Azure) but route through the auth.* adapter directly rather than a dedicated IScimAdapter namespace.

📓 Developer Best Practices

1. Always use the Interface: Never cast IDBAdapter to a concrete class like SQLiteAdapter unless performing emergency maintenance.
2. Favor LocalCMS: Use the SDK bridge in server files for 0ms internal latency.
3. Respect tenantId: Ensure every query includes a tenant scope to maintain data isolation. For bearer auth, pass locals.tenantId into websiteTokens.getByToken() when the request tenant is already resolved.
4. Error Checking: Always check result.success before accessing result.data.

Related Documentation

• Core Infrastructure - The internal engine and db.ts lifecycle.
• Database Resilience - Error handling and recovery patterns.
• SQLite Implementation - Specific optimizations for edge deployments.
• PostgreSQL Implementation - Enterprise scaling with JSONB.