Skip to content

feat: evaluate embedding SurrealDB inside the Electron desktop runtime #89

@ibourgeois

Description

@ibourgeois

Context

As a desktop user, I need Katra's local SurrealDB runtime to stay private to the app process when possible so the desktop experience does not depend on exposing a localhost database port on the host machine.

Acceptance Criteria

  • Investigate whether Katra can run SurrealDB embedded inside the Electron/Node runtime instead of spawning a host-visible local server.
  • Document the architecture tradeoffs between an Electron-embedded runtime and the current localhost CLI-backed runtime.
  • Prototype or define a bridge so Laravel can talk to the embedded runtime without requiring a host-visible database port.
  • Preserve the separate server-mode story where deployed Katra instances use an external SurrealDB instance or cluster.

Notes

Current SurrealDB docs indicate this is possible in server-side JavaScript:

Important caveat from the current docs: embedded databases are intended for single-process access. Multi-process or distributed access should still use a remote SurrealDB server.

This issue is specifically about the desktop runtime path. It should not change the broader Katra direction where server deployments use external SurrealDB infrastructure.

Out of Scope

  • Replacing the server deployment model with embedded storage.
  • General SurrealDB schema design or application-level graph modeling work unrelated to the desktop runtime boundary.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions