Desktop Client (Electron + Next.js)
Relevant source files
The following files were used as context for generating this wiki page:
- apps/client/src/prompts/system_prompt.ts
- specs/main/plan.md
- Comprehensive.md
- specs/001-skill-builder-core/research.md
- apps/client/forge.config.ts (Referenced via Comprehensive.md and research.md)
The Desktop Client is a cross-platform application built using a combination of Electron and Next.js, designed for creating, managing, and testing AI skills. It serves as the primary user interface for the bl1nk platform, providing a real-time environment where users can interact with an AI editor to modify web applications and view live previews.
The client architecture leverages the maturity of the Electron ecosystem to provide native OS integration (such as secure credential storage and file system access) while utilizing Next.js 15 and React 19 for a high-performance, responsive frontend experience.
Sources: Comprehensive.md:21-25, specs/001-skill-builder-core/research.md:105-115, apps/client/src/prompts/system_prompt.ts:57-65
System Architecture
The Desktop Client operates using a multi-process architecture typical of Electron applications, divided into a Main Process and a Renderer Process.
Process Division
- Main Process: Handles high-level application lifecycle, native OS integrations, and hosts a local Express + tRPC server. It manages the SQLite database via Prisma and handles sensitive credential encryption.
- Renderer Process: Hosts the Next.js frontend application. It communicates with the Main Process via IPC (Inter-Process Communication) and HTTP/tRPC for data operations.
The diagram shows the separation between the local backend server running in the Electron main process and the React-based frontend.
Sources: specs/001-skill-builder-core/research.md:120-140, Comprehensive.md:33-40
Core Technical Stack
The client utilizes a modern tech stack to ensure type safety, modularity, and real-time responsiveness.
| Component | Technology | Description |
|---|---|---|
| Frontend Framework | Next.js 15 / React 19 | Provides the UI structure and rendering logic. |
| Styling | Tailwind CSS / shadcn/ui | Used for responsive design and consistent component patterns. |
| State Management | Zustand | Manages application state with debounced persistence for auto-save. |
| Backend Integration | tRPC | Ensures end-to-end type safety between frontend and backend. |
| Local Database | SQLite + Prisma | File-based storage for local-first data management. |
| Native Secure Storage | node-keytar | Hardware-backed keychain for API credentials. |
Sources: Comprehensive.md:21-26, specs/001-skill-builder-core/research.md:9-15, specs/main/plan.md:11-15
AI Integration & Real-time Edits
The client functions as an AI-powered editor ("bl1nk"). The AI assists users by chatting and performing real-time modifications to the application code.
Execution Flow
- Thinking Process: The AI uses a structured thinking process (within
<think>tags) to analyze debugging or feature requests. - Command Execution: The AI can suggest UI-driven commands such as Rebuild, Restart, and Refresh using specific
<bl1nk-command>tags. - Code Modifications: Edits are performed using
<bl1nk-write>for creating/updating files,<bl1nk-rename>for renames, and<bl1nk-delete>for removals. - Live Preview: Changes are immediately rendered in an iframe on the right side of the screen.
The sequence diagram illustrates the loop between user input, AI-driven file modification, and the immediate feedback in the live preview.
Sources: apps/client/src/prompts/system_prompt.ts:7-50, apps/client/src/prompts/system_prompt.ts:57-65, apps/client/src/prompts/system_prompt.ts:98-105
Security and Credential Management
Security is a primary concern for a desktop client managing API keys (e.g., AWS Bedrock, OpenRouter).
Encryption Strategy
- Primary Mechanism: The client uses
node-keytarto leverage the OS keychain for hardware-backed security. - Fallback Mechanism: If the keychain is unavailable (e.g., specific Linux distros), the client falls back to AES-256 encrypted file storage.
- Key Derivation: Encryption keys are derived from machine-specific identifiers to ensure data remains locked to the device.
Sources: specs/001-skill-builder-core/research.md:35-50, Comprehensive.md:66-70
Build and Distribution
The client is packaged for multi-platform distribution using Electron Forge and Electron Builder.
| Platform | Format | Security |
|---|---|---|
| Windows | .exe, .msi | Signed via DigiCert certificate. |
| macOS | .dmg, .zip | Signed via Apple Developer ID + Notarization. |
| Linux | .deb, .rpm, .AppImage | Standard distribution packages. |
Sources: specs/main/plan.md:255-275, Comprehensive.md:105-115
Conclusion
The Desktop Client (Electron + Next.js) provides a robust, local-first development environment for AI skills. By combining native system capabilities with modern web technologies, it delivers a secure, real-time platform for building and testing applications. Its architecture ensures that code modifications are instantly reflected in a live preview while maintaining high standards for security and type safety.
Sources: specs/001-skill-builder-core/research.md:175-185, Comprehensive.md:145-155