CDK backend

This page describes the backend side of a CDK editor integration: runtime requirements, persistence model, and API surface.

Runtime requirements

For a production-ready CDK editor backend, you typically need:

  • Node.js 22 or newer.
  • An HTTP API layer (Modula uses Hono mounted in SvelteKit under /api).
  • Persistent database storage for modules, versions, users, and permissions.
  • A cache/KV service for collaboration signaling and short-lived locks.
  • Object/media storage for uploaded assets and transformed variants.

In Modula, these concerns are split into route packages and repository interfaces, so each endpoint can be mounted independently.

Database and persistence

The editor writes structured module content and version history. A typical model includes:

  1. Module metadata: title, ownership, visibility, timestamps.
  2. Current content snapshot: module data including block list.
  3. Version log: immutable past revisions for rollback and audit.
  4. Permission mapping: who can read/edit a module.

Content shape

The module model contains a blocks array with typed entries (text, gallery, exercise, timeline, and others), plus optional metadata like title, subtitle, abstract, and theme.

For editor-native persistence, you can also store the State.toJSON() snapshot (NodeJSON[]) and restore it with State.fromJSON().

API surface

Core module APIs

The main content workflow is exposed under /api/modules:

  • GET /api/modules: list accessible modules.
  • GET /api/modules/search: search modules.
  • GET /api/modules/:id: get one module descriptor.
  • POST /api/modules/:id: save a new version of module content.
  • DELETE /api/modules/:id: soft delete.
  • GET /api/modules/:id/versions: list version history.
  • GET /api/modules/:id/versions/:version_id: fetch a specific version.
  • GET /api/modules/:id/linked-data: linked-data representation.
  • GET /api/modules/:id/download: export offline package.

POST /api/modules/:id supports optimistic concurrency through a rev field and can return 409 Conflict when the revision is stale.

Collaboration APIs

Realtime collaboration signaling is exposed at /api/collab/:ref_id/signal:

  • GET: heartbeat, peers, locks, pending signals.
  • POST: broadcast lock/unlock/transaction/signaling events.
  • DELETE: peer leave and lock cleanup.

This endpoint is short-lived by design (TTL-based presence/lock/signal data in cache/KV).

Media and support APIs

Editor workflows commonly depend on:

  • /api/streams: upload/list/manage media streams.
  • /api/oembed: resolve external embeds.
  • /api/iam: user profile, avatar, theme resources.

Integration checklist

  1. Expose module save/version APIs.
  2. Configure media upload and storage.
  3. Enable collaboration signaling if multi-user editing is required.
  4. Enforce auth and per-module access checks at repository level.
  5. Add optimistic concurrency (rev) on save endpoints.

With this baseline, the CDK editor can run in local mode first and scale to collaborative, versioned editing without changing the frontend model.