@c15t/backend 2.0.0-rc.3 → 2.0.0-rc.5

package/docs/README.md

@@ -0,0 +1,49 @@
+# c15t Backend Docs
+
+Self-hosted c15t backend docs for configuration, policy packs, APIs, and operational behavior.
+
+If you are changing consent flows, consent UI, script loading, server-side setup, or backend configuration in an app that uses this package, start here before editing code.
+
+## Start Here
+
+- [Quickstart](./quickstart.md)
+- [Database Setup](./guides/database-setup.md)
+- [Policy Packs](./guides/policy-packs.md)
+- [Configuration](./api/configuration.md)
+
+## Workflow Rules
+
+### Database & Initial Setup
+
+Use this when:
+- configuring a self-hosted backend
+- choosing adapters or initial backend wiring
+
+Prefer:
+- Start with the documented database setup guide.
+- Prefer the documented adapter and setup path before custom backend wiring.
+
+If that is not enough:
+- Use the API reference when you need exact option-level behavior.
+
+Read next:
+- [Quickstart](./quickstart.md)
+- [Database Setup](./guides/database-setup.md)
+- [Configuration](./api/configuration.md)
+
+### Policy Packs & Regional Behavior
+
+Use this when:
+- configuring region-aware consent behavior
+- deciding whether logic belongs in backend policy config or frontend code
+
+Prefer:
+- Prefer policy-pack and documented backend configuration over frontend-only regional logic.
+- Keep consent behavior centralized in backend policy configuration where possible.
+
+Avoid:
+- Do not scatter policy decisions across client code when the backend can own them.
+
+Read next:
+- [Policy Packs](./guides/policy-packs.md)
+- [Configuration](./api/configuration.md)

package/docs/api/configuration.md

@@ -0,0 +1,197 @@
+---
+title: Configuration Reference
+description: Complete reference for all c15t backend configuration options.
+---
+All options are passed to `c15tInstance()`. Only `adapter` and `trustedOrigins` are required.
+
+## Options
+
+### C15TOptions
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|adapter|[FumaDBAdapter](https://v2.c15t.com/docs/self-host/guides/database-setup)|The database adapter to use.|-|✅ Required|
+|tenantId|string \|undefined|Tenant ID for multi-tenant deployments. When set, all database queries are automatically scoped to this tenant.|-|Optional|
+|tablePrefix|[string \|undefined](https://v2.c15t.com/docs/self-host/guides/database-setup)|Optional prefix for all database table names. Useful when sharing a database with other applications to avoid naming conflicts.|-|Optional|
+|appName|[string \|undefined](https://v2.c15t.com/docs/self-host/api/configuration)|Application name used as backend metadata and identity. Returned by \`/init\` (\`appName\`), used in logs, telemetry defaults (\`service.name\`), and cache key prefixing.|"c15t"|Optional|
+|basePath|[string \|undefined](https://v2.c15t.com/docs/self-host/api/endpoints)|Base path prefix for all API routes (e.g. \`/api/self-host\`).|-|Optional|
+|trustedOrigins|[string\[\]](https://v2.c15t.com/docs/self-host/api/configuration)|Allowed origins for CORS. Required for browser-based consent collection. Protocol is optional; matching is protocol-agnostic and normalized.|-|✅ Required|
+|logger|LoggerOptions \|undefined|Logger configuration.|-|Optional|
+|disableGeoLocation|boolean \|undefined|Disables the use of Geo Location to determine the jurisdiction. When enabled, the jurisdiction will be set to "GDPR" to show the strictest version of the banner as we don't know the jurisdiction in this case.|false|Optional|
+|customTranslations|Record\<string, Partial\<Translations>> \|undefined|Override base translations.|-|Optional|
+|i18n|I18nOptions \|undefined|Internationalization message profiles used by runtime policies.|-|Optional|
+|policyPacks|[PolicyConfig \|undefined](https://v2.c15t.com/docs/self-host/guides/policy-packs)|Runtime regional policy pack resolved per request.|-|Optional|
+|branding|"c15t" \|"consent" \|"none" \|undefined|Select which branding to show in the consent banner. Use "none" to hide branding.|"c15t"|Optional|
+|openapi|[OpenAPIOptions \|undefined](https://v2.c15t.com/docs/self-host/api/endpoints)|OpenAPI spec generation and documentation UI options.|-|Optional|
+|telemetry|[TelemetryOptions \|undefined](https://v2.c15t.com/docs/self-host/guides/observability)|OpenTelemetry configuration for tracing and metrics. Telemetry is opt-in and disabled by default. Users must provide their own SDK setup (Node, Bun, edge, etc.).|-|Optional|
+|ipAddress|[IPAddressOptions \|undefined](https://v2.c15t.com/docs/self-host/api/configuration)|IP address tracking and masking options.|-|Optional|
+|cache|[CacheOptions \|undefined](https://v2.c15t.com/docs/self-host/guides/caching)|Cache configuration for external persistent storage. Used for caching GVL and other data.|-|Optional|
+|apiKeys|string\[] \|undefined|API keys for authenticated endpoints. Used for server-side endpoints like GET /subjects.|-|Optional|
+|iab|[IABOptions \|undefined](https://v2.c15t.com/docs/self-host/guides/iab-tcf)|IAB TCF configuration including GVL, CMP registration, and custom vendors. Disabled by default - most users don't need IAB TCF. Set enabled: true to activate IAB support.|-|Optional|
+|policySnapshot|PolicySnapshotOptions \|undefined|Optional signed policy snapshots used to keep /init and /subjects consistent.|-|Optional|
+|background|BackgroundOptions \|undefined|Optional background task runner for non-critical side effects.|-|Optional|
+
+#### `adapter` FumaDBAdapter
+
+The database adapter to use.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|name|string|Name of the adapter|-|✅ Required|
+|generateSchema|Object \|undefined|Generate ORM schema based on FumaDB Schema|-|Optional|
+|createMigrationEngine|((this: FumaDBAdapterContext) => Migrator) \|undefined|-|-|Optional|
+
+#### `logger` LoggerOptions
+
+Logger configuration.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|disabled|boolean \|undefined|Whether logging is disabled.|-|Optional|
+|level|"info" \|"warn" \|"error" \|"debug" \|undefined|The minimum log level to publish.|-|Optional|
+|log|((level: LogLevel, message: string, ...args: unknown\[]) => void) \|undefined|Custom log handler function.|-|Optional|
+|appName|string \|undefined|Custom application name to display in log messages.|-|Optional|
+|getTraceContext|(() => TraceContext \|null) \|undefined|Optional callback to get trace context for log correlation.|-|Optional|
+
+#### `i18n` I18nOptions
+
+Internationalization message profiles used by runtime policies.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|messages|I18nMessageProfiles \|undefined|Named translation catalogs grouped by profile.|-|Optional|
+|defaultProfile|string \|undefined|Fallback profile used when a policy does not provide \`messageProfile\`.|-|Optional|
+
+#### `policyPacks` PolicyConfig
+
+Runtime regional policy pack resolved per request.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|id|string|-|-|✅ Required|
+|match|Object \|undefined|-|-|✅ Required|
+|i18n|Object \|undefined|-|-|Optional|
+|consent|Object \|undefined|-|-|Optional|
+|ui|Object \|undefined|-|-|Optional|
+|proof|Object \|undefined|-|-|Optional|
+
+#### `policySnapshot` PolicySnapshotOptions
+
+Optional signed policy snapshots used to keep /init and /subjects consistent.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|signingKey|string|Secret used for signing and verifying policy snapshot tokens.|-|✅ Required|
+|onValidationFailure|"reject" \|"resolve\_current" \|undefined|How writes should behave when snapshot validation fails.|-|Optional|
+|issuer|string \|undefined|JWT issuer claim for snapshot tokens.|-|Optional|
+|audience|string \|undefined|JWT audience claim for snapshot tokens. When omitted, c15t derives a default snapshot audience and scopes it per tenant.|-|Optional|
+|ttlSeconds|number \|undefined|Snapshot token lifetime in seconds.|-|Optional|
+
+#### `background` BackgroundOptions
+
+Optional background task runner for non-critical side effects.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|run|(task: () => Promise\<void>) => void|Executes non-critical tasks after the response path has completed.|-|✅ Required|
+
+### OpenAPIOptions
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|enabled|boolean \|undefined|Enable/disable OpenAPI spec generation|true|Optional|
+|specPath|string \|undefined|Path to serve the OpenAPI JSON spec|"/spec.json"|Optional|
+|docsPath|string \|undefined|Path to serve the API documentation UI|"/docs"|Optional|
+|options|Object \|undefined|OpenAPI specification options|-|Optional|
+|customUiTemplate|string \|undefined|Custom template for rendering the API documentation UI If provided, this will be used instead of the default Scalar UI|-|Optional|
+
+#### `options`
+
+OpenAPI specification options
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|info|Object \|undefined|-|-|Optional|
+|servers|Array\<Object> \|undefined|-|-|Optional|
+|security|Record\<string, string\[]>\[] \|undefined|-|-|Optional|
+
+### TelemetryOptions
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|enabled|boolean \|undefined|Enable telemetry (tracing and metrics). Must be explicitly set to true to activate.|false|Optional|
+|tracer|Tracer \|undefined|User-provided tracer instance. Users should set up their own OpenTelemetry SDK and pass the tracer here.|-|Optional|
+|meter|Meter \|undefined|User-provided meter instance for metrics. Users should set up their own OpenTelemetry SDK and pass the meter here.|-|Optional|
+|defaultAttributes|Record\<string, string \|number \|boolean> \|undefined|Default attributes to include on all spans and metrics.|-|Optional|
+
+### IPAddressOptions
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|tracking|boolean \|undefined|Enable/disable IP address tracking. When disabled, all IP addresses will be stored as null.|true|Optional|
+|masking|boolean \|undefined|Enable/disable IP address masking to reduce PII collection.|true|Optional|
+|ipAddressHeaders|string\[] \|undefined|Override the default IP address headers used to extract client IP. Headers are checked in order, first match wins.|-|Optional|
+
+### CacheOptions
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|adapter|CacheAdapter \|undefined|External cache adapter (Redis, KV, etc.). If not provided, only in-memory cache is used.|-|Optional|
+
+### IABOptions
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|enabled|true|Enable IAB TCF support. When false or not provided, /init does not include IAB payload fields. When true, /init includes IAB payload only when IAB is active for the resolved request policy (or when no policies are configured).|-|✅ Required|
+|cmpId|number \|undefined|CMP ID registered with IAB Europe. This is returned to clients via the /init endpoint so they can use the correct CMP identity in TC Strings. See List of registered CMPs: https\://iabeurope.eu/cmp-list/|-|Optional|
+|bundled|Object \|undefined \|null|Bundled GVL translations by language code. These are checked first before any cache or fetch.|-|Optional|
+|vendorIds|number\[] \|undefined|Vendor IDs to filter when fetching non-bundled languages. Reduces payload size.|-|Optional|
+|endpoint|string \|undefined|Override the default GVL endpoint.|'https\://gvl.consent.io'|Optional|
+|customVendors|Array\<Object> \|undefined|Custom vendors not registered with IAB. These are synced to the frontend via the /init endpoint.|-|Optional|
+
+## Return Value
+
+`c15tInstance()` returns:
+
+```ts
+interface C15TInstance {
+  /** Standard Fetch API handler */
+  handler: (request: Request) => Promise<Response>;
+
+  /** Resolved configuration */
+  options: C15TOptions;
+
+  /** Internal context (database, registry, logger) */
+  $context: C15TContext;
+
+  /** OpenAPI spec as JSON */
+  getOpenAPISpec: () => Promise<Record<string, unknown>>;
+
+  /** OpenAPI docs UI as HTML string */
+  getDocsUI: () => string;
+}
+```
+
+## Edge Init Options
+
+`c15tEdgeInit()` from `@c15t/backend/edge` accepts a subset of `C15TOptions` — only the fields needed for consent policy resolution without a database. See the [Edge Deployment guide](/docs/self-host/guides/edge-deployment) for usage.
+
+### C15TEdgeOptions
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|C15TEdgeOptions|C15TEdgeOptions|Type alias for C15TEdgeOptions|-|✅ Required|
+
+## defineConfig Helper
+
+For type-safe configuration in a separate file:
+
+```ts title="c15t.config.ts"
+import { defineConfig } from '@c15t/backend';
+
+export default defineConfig({
+  adapter: kyselyAdapter(db),
+  trustedOrigins: ['https://example.com'],
+  // full autocomplete on all options here
+});
+```

package/docs/api/endpoints.md

@@ -0,0 +1,211 @@
+---
+title: API Endpoints
+description: Full reference for every c15t consent backend endpoint.
+---
+All endpoints are relative to your configured `basePath` (e.g. `/api/c15t`).
+
+> ℹ️ **Info:**
+> The backend auto-generates interactive API docs at \{basePath}/docs using your OpenAPI spec. Visit this URL in a browser to explore endpoints with a visual UI.
+
+## GET /init
+
+Returns the initial consent state for a client. This is the first call made by the frontend SDKs.
+
+**Response:**
+
+```json
+{
+  "jurisdiction": "GDPR",
+  "location": {
+    "countryCode": "DE",
+    "regionCode": "BY"
+  },
+  "translations": {
+    "language": "de",
+    "translations": { "...": "..." }
+  },
+  "branding": "c15t",
+  "gvl": null
+}
+```
+
+|Field|Description|
+|--|--|
+|`jurisdiction`|Detected regulation (`GDPR`, `UK_GDPR`, `CCPA`, etc.)|
+|`location`|Geo-location from IP address|
+|`translations`|Server-side translations based on `Accept-Language`|
+|`branding`|Branding configuration|
+|`gvl`|Global Vendor List (if IAB TCF is enabled)|
+
+## GET /status
+
+Health check endpoint. Returns server version and client info.
+
+**Response:**
+
+```json
+{
+  "version": "1.8.0",
+  "timestamp": "2026-02-11T12:00:00.000Z",
+  "client": {
+    "ip": "192.168.1.0",
+    "acceptLanguage": "en-US",
+    "userAgent": "Mozilla/5.0 ...",
+    "region": { "countryCode": "US", "regionCode": "CA" }
+  }
+}
+```
+
+## POST /subjects
+
+Records a consent event. This is an append-only operation — every call creates a new consent record.
+
+**Request:**
+
+```json
+{
+  "type": "cookie_banner",
+  "subjectId": "sub_abc123",
+  "domain": "example.com",
+  "preferences": {
+    "necessary": true,
+    "measurement": true,
+    "marketing": false
+  },
+  "givenAt": 1707648000000,
+  "metadata": {}
+}
+```
+
+|Field|Type|Required|Description|
+|--|--|--|--|
+|`type`|string|Yes|`cookie_banner`, `privacy_policy`, `dpa`, `terms_and_conditions`, `marketing_communications`, `age_verification`, `other`|
+|`subjectId`|string|Yes|Client-generated subject identifier|
+|`domain`|string|Yes|Domain where consent was given|
+|`preferences`|object|No|Consent category preferences (for `cookie_banner` type)|
+|`givenAt`|number|Yes|Epoch timestamp|
+|`policyId`|string|No|Associated policy ID|
+|`metadata`|object|No|Arbitrary metadata|
+|`externalSubjectId`|string|No|External user ID for cross-device linking|
+|`identityProvider`|string|No|Identity provider name|
+
+**Response:**
+
+```json
+{
+  "subject": { "id": "sub_abc123", "...": "..." },
+  "consent": { "id": "con_xyz789", "type": "cookie_banner", "...": "..." }
+}
+```
+
+## GET /subjects/:id
+
+Retrieves consent status for a subject.
+
+**Query Parameters:**
+
+|Parameter|Description|
+|--|--|
+|`type`|Comma-separated consent types to filter (e.g. `cookie_banner,privacy_policy`)|
+
+**Response:**
+
+```json
+{
+  "subject": { "id": "sub_abc123" },
+  "consents": [
+    {
+      "id": "con_xyz789",
+      "type": "cookie_banner",
+      "givenAt": "2026-02-11T12:00:00.000Z",
+      "jurisdiction": "GDPR",
+      "preferences": { "necessary": true, "measurement": true }
+    }
+  ],
+  "isValid": true
+}
+```
+
+## PATCH /subjects/:id
+
+Links a subject to an external user ID for cross-device consent resolution.
+
+**Request:**
+
+```json
+{
+  "externalId": "user_12345",
+  "identityProvider": "auth0"
+}
+```
+
+**Response:**
+
+```json
+{
+  "subject": {
+    "id": "sub_abc123",
+    "externalId": "user_12345",
+    "identityProvider": "auth0"
+  }
+}
+```
+
+## GET /consents/check
+
+Check consent status by external ID — useful for cross-device consent resolution.
+
+**Query Parameters:**
+
+|Parameter|Description|
+|--|--|
+|`externalId`|The external user ID to look up|
+|`type`|Comma-separated consent types|
+
+**Response:**
+
+```json
+{
+  "found": true,
+  "consents": [
+    { "id": "con_xyz789", "type": "cookie_banner", "...": "..." }
+  ]
+}
+```
+
+## GET /subjects (Authenticated)
+
+List subjects by external ID. Requires an API key.
+
+**Headers:**
+
+```
+Authorization: Bearer sk_live_abc123
+```
+
+**Query Parameters:**
+
+|Parameter|Description|
+|--|--|
+|`externalId`|The external user ID to search|
+
+**Response:**
+
+```json
+{
+  "subjects": [
+    { "id": "sub_abc123", "externalId": "user_12345" }
+  ]
+}
+```
+
+> ℹ️ **Info:**
+> This endpoint requires API key authentication. Configure API keys in the apiKeys option. The key is passed via the Authorization: Bearer header using timing-safe comparison.
+
+## GET /spec.json
+
+Returns the OpenAPI 3.1 specification for the consent API.
+
+## GET /docs
+
+Serves the interactive API documentation UI (Scalar).

package/docs/guides/caching.md

@@ -0,0 +1,85 @@
+---
+title: Caching
+description: Add a caching layer to your self-hosted c15t backend for production performance.
+---
+The backend includes a caching layer for frequently accessed data like GVL (Global Vendor List) lookups and custom server-side translations. By default, an in-memory cache is used — suitable for single-instance deployments. For production with multiple instances, plug in Redis or Cloudflare KV so all instances share the same cache.
+
+## In-Memory (Default)
+
+No configuration needed. The default memory cache has a 5-minute TTL and is suitable for development and single-instance deployments.
+
+## Upstash Redis
+
+```ts title="c15t.ts"
+import { c15tInstance } from '@c15t/backend';
+import { createUpstashRedisAdapter } from '@c15t/backend/cache';
+
+export const c15t = c15tInstance({
+  // ...
+  cache: {
+    adapter: createUpstashRedisAdapter({
+      url: process.env.UPSTASH_REDIS_REST_URL,
+      token: process.env.UPSTASH_REDIS_REST_TOKEN,
+    }),
+  },
+});
+```
+
+If you already have an Upstash Redis client, pass it directly:
+
+```ts
+import { createUpstashRedisAdapterFromClient } from '@c15t/backend/cache';
+import { Redis } from '@upstash/redis';
+
+const redis = new Redis({
+  url: process.env.UPSTASH_REDIS_REST_URL,
+  token: process.env.UPSTASH_REDIS_REST_TOKEN,
+});
+
+const adapter = createUpstashRedisAdapterFromClient(redis);
+```
+
+## Cloudflare KV
+
+For Cloudflare Workers deployments:
+
+```ts title="worker.ts"
+import { c15tInstance } from '@c15t/backend';
+import { createCloudflareKVAdapter } from '@c15t/backend/cache';
+
+export default {
+  async fetch(request: Request, env: Env) {
+    const c15t = c15tInstance({
+      // ...
+      cache: {
+        adapter: createCloudflareKVAdapter(env.GVL_CACHE),
+      },
+    });
+
+    return c15t.handler(request);
+  },
+};
+```
+
+## Custom Cache Adapter
+
+Implement the `CacheAdapter` interface to use any cache backend:
+
+```ts
+import type { CacheAdapter } from '@c15t/backend/cache';
+
+const customCache: CacheAdapter = {
+  async get<T>(key: string): Promise<T | null> {
+    // retrieve from your cache
+  },
+  async set<T>(key: string, value: T, ttlMs?: number): Promise<void> {
+    // store in your cache
+  },
+  async delete(key: string): Promise<void> {
+    // remove from cache
+  },
+  async has(key: string): Promise<boolean> {
+    // check existence
+  },
+};
+```

package/docs/guides/database-setup.md

@@ -0,0 +1,128 @@
+---
+title: Database Setup
+description: Configure a database adapter for your self-hosted c15t backend.
+---
+The c15t backend requires a database to store consent records, subjects, audit logs, and policies. Five adapters are supported — choose the one that matches your existing stack.
+
+## Adapters
+
+### Kysely
+
+```ts title="c15t.ts"
+import { c15tInstance } from '@c15t/backend';
+import { kyselyAdapter } from '@c15t/backend/db/adapters/kysely';
+import { Kysely, PostgresDialect } from 'kysely';
+import { Pool } from 'pg';
+
+const db = new Kysely({
+  dialect: new PostgresDialect({
+    pool: new Pool({ connectionString: process.env.DATABASE_URL }),
+  }),
+});
+
+export const c15t = c15tInstance({
+  adapter: kyselyAdapter(db),
+  trustedOrigins: ['https://example.com'],
+});
+```
+
+### Drizzle
+
+```ts title="c15t.ts"
+import { c15tInstance } from '@c15t/backend';
+import { drizzleAdapter } from '@c15t/backend/db/adapters/drizzle';
+import { drizzle } from 'drizzle-orm/node-postgres';
+
+const db = drizzle(process.env.DATABASE_URL);
+
+export const c15t = c15tInstance({
+  adapter: drizzleAdapter(db),
+  trustedOrigins: ['https://example.com'],
+});
+```
+
+### Prisma
+
+```ts title="c15t.ts"
+import { c15tInstance } from '@c15t/backend';
+import { prismaAdapter } from '@c15t/backend/db/adapters/prisma';
+import { PrismaClient } from '@prisma/client';
+
+const prisma = new PrismaClient();
+
+export const c15t = c15tInstance({
+  adapter: prismaAdapter(prisma),
+  trustedOrigins: ['https://example.com'],
+});
+```
+
+### TypeORM
+
+```ts title="c15t.ts"
+import { c15tInstance } from '@c15t/backend';
+import { typeormAdapter } from '@c15t/backend/db/adapters/typeorm';
+import { DataSource } from 'typeorm';
+
+const dataSource = new DataSource({
+  type: 'postgres',
+  url: process.env.DATABASE_URL,
+});
+
+export const c15t = c15tInstance({
+  adapter: typeormAdapter(dataSource),
+  trustedOrigins: ['https://example.com'],
+});
+```
+
+### MongoDB
+
+```ts title="c15t.ts"
+import { c15tInstance } from '@c15t/backend';
+import { mongoAdapter } from '@c15t/backend/db/adapters/mongo';
+import { MongoClient } from 'mongodb';
+
+const client = new MongoClient(process.env.MONGODB_URI);
+
+export const c15t = c15tInstance({
+  adapter: mongoAdapter(client),
+  trustedOrigins: ['https://example.com'],
+});
+```
+
+## Migrations
+
+To create & update the database you can use the migrator which is included in the CLI:
+
+|Package manager|Command|
+|:--|:--|
+|npm|`npx @c15t/cli@rc`|
+|pnpm|`pnpm dlx @c15t/cli@rc`|
+|yarn|`yarn dlx @c15t/cli@rc`|
+|bun|`bunx @c15t/cli@rc`|
+
+## Table Prefix
+
+If you share a database with other applications, use `tablePrefix` to namespace the c15t tables:
+
+```ts
+c15tInstance({
+  adapter: kyselyAdapter(db),
+  tablePrefix: 'c15t_',
+  trustedOrigins: ['https://example.com'],
+});
+```
+
+This prefixes all table names (e.g. `c15t_subject`, `c15t_consent`, `c15t_audit_log`).
+
+## Schema Overview
+
+The backend creates and manages these tables:
+
+|Table|Purpose|
+|--|--|
+|`subject`|Consent subjects (users/devices). Tracks identification status and external IDs.|
+|`consent`|Append-only consent records. Stores preferences, jurisdiction, IP, and timestamps.|
+|`domain`|Domain/website configuration for multi-domain setups.|
+|`consent_policy`|Versioned consent policies.|
+|`consent_purpose`|Maps consent purposes to categories.|
+|`audit_log`|Immutable log of all consent-related actions.|