NativePHP

Arkhein is built with NativePHP, which allows us to wrap a Laravel-based PHP application in a macOS-native container. This provides a bridge between standard web technologies and the macOS desktop experience.

The nativephp Connection

A core requirement for Arkhein is persistence. Unlike a standard web app that might use a central database, Arkhein is local-first.

• SQLite SSOT: All models that store domain knowledge must use the nativephp connection.
• Connection Isolation: In NativePHP, the default connection is often transient. Arkhein uses the nativephp connection to ensure your data survives application restarts.

Invariants

• Desktop UX: Arkhein uses macOS-native features like the menu bar and system notifications.
• Background Queues: Heavy work like indexing and LLM inference is dispatched to the background queue connection to keep the user interface responsive.
• File System Access: NativePHP provides access to the local filesystem, but Arkhein enforces strict boundaries via Managed Folders.

Common Failures

Ghost Data

Writing models to the default connection instead of the nativephp connection will result in data loss or "ghost data" that disappears on reboot.

Application Lifecycle

Because it's a desktop app, the PHP process might be shut down if the user quits. Ensure all long-running tasks are handled via the queue.