System Architecture Overview

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/felixdotgo/querybox/llms.txt

Use this file to discover all available pages before exploring further.

​

System Architecture

​

Core Components

​

Technology Stack

​

Backend (Go)

• Framework: Wails v3 (native desktop wrapper)
• Database: SQLite (modernc.org/sqlite) for connections & credential fallback
• Keyring: zalando/go-keyring for OS-native credential storage
• IPC: Protobuf JSON for plugin communication
• Event Bus: Wails Event system for backend → frontend messaging

​

Frontend (Vue 3)

• UI Framework: Vue 3 (Composition API)
• Component Library: Naive UI
• Styling: Tailwind CSS
• Routing: Vue Router (Hash mode)
• Build Tool: Vite
• Type Safety: TypeScript (auto-generated bindings)

​

Plugin System

• Protocol: JSON stdin/stdout
• Contract: Protobuf definitions in rpc/contracts/plugin/v1
• Commands: info, exec, authforms, connection-tree, test-connection
• Timeout: 30s (exec/tree), 15s (test), 5s (info), 2s (authforms)
• Location: User config directory or bundled bin/plugins

​

Data Storage

​

Platform-Specific Paths

​

Database Files

• connections.db: Connection metadata (name, driver, credential_key, timestamps)
• credentials.db: Encrypted credential storage (fallback when OS keyring unavailable)
• plugins/: User-installed plugin binaries (synced from bundled plugins on startup)

​

Credential Security

1. OS Keyring (primary): macOS Keychain, Windows Credential Manager, Linux libsecret/KWallet
2. SQLite (fallback): Encrypted database when keyring unavailable (headless, containers)
3. Memory (last-resort): In-memory map when filesystem unavailable

​

Key Architectural Patterns

​

1. On-Demand Plugin Execution

Frontend → PluginManager.ExecPlugin() → spawn subprocess → JSON stdin/stdout → parse result → terminate

• No memory overhead when idle
• Automatic cleanup on timeout/crash
• Simple protocol (JSON, not gRPC)
• No plugin state management

​

2. Event-Driven UI Updates

ConnectionService.CreateConnection() → emit connection:created → Frontend updates list (no re-fetch)

​

3. Service Injection

// main.go:67
connSvc.SetApp(app.App)  // Enables event emission
mgr.SetApp(app.App)

​

4. TypeScript Bindings

// frontend/bindings/github.com/felixdotgo/querybox/services/connectionservice.js
export function CreateConnection(name, driverType, credential) {
  return window.wails.Call.ByName('ConnectionService.CreateConnection', name, driverType, credential)
}

​

Application Lifecycle

​

Startup Sequence

1. main.go Initialization (main.go:36)
   • Construct ConnectionService (opens SQLite, runs migrations)
   • Construct PluginManager (starts async plugin scan)
   • Create Wails application with services bound
   • Inject app references via SetApp()
   • Create main window
   • Defer creation of connections/plugins windows (1s delay)
2. Frontend Mount (frontend/src/main.js:44)
   • Create Vue app with Router and Naive UI
   • Mount to #app
   • Subscribe to app:log and connection:* events
3. Plugin Discovery (async, services/pluginmgr/pluginmgr.go:203)
   • Scan user directory and bundled directory for executables
   • Probe each binary with plugin info (5s timeout)
   • Populate registry with metadata
   • Emit plugins:ready event

​

Shutdown Sequence

1. User closes main window or selects Quit
2. App.CloseMainWindow() calls app.App.Quit() (services/app.go:126)
3. Wails calls Shutdown() on all bound services:
   • ConnectionService.Shutdown(): Close SQLite connections
   • PluginManager.Shutdown(): No-op (no background processes)
4. Process exits

​

Cross-Platform Considerations

​

macOS

• Native Menu: Application menu in menu bar (services/menu.go)
• Window Style: Translucent backdrop with hidden inset title bar
• Bundled Plugins: Located inside .app/Contents/MacOS/bin/plugins

​

Windows

• Console Hiding: Plugin subprocesses hidden via hideWindow() (pluginmgr_windows.go)
• Executable Detection: .exe extension required
• File Paths: Backslash separators handled by filepath package

​

Linux

• Keyring: Requires libsecret or KWallet; falls back to SQLite if unavailable
• AppImage: User config directory resolved via $XDG_CONFIG_HOME
• Executable Detection: Checks 0111 mode bits

​

Security Model

​

Credential Isolation

• Credentials never stored in connection metadata
• OS keyring access isolated to CredManager
• Frontend receives credentials only when needed (via GetCredential())
• Plugins receive credentials as opaque JSON blobs

​

Plugin Sandboxing

• Plugins run as separate processes (OS-level isolation)
• Timeouts prevent runaway plugins (30s exec, 15s test)
• No network access required for host application
• Plugin stdout parsed, stderr captured for debugging

​

Data Protection

• SQLite databases in user config directory (protected by OS permissions)
• No plaintext credentials in logs (see Event System naming rules)
• Connection credentials keyed by UUID, not connection name

​

Next Steps

• Core Services - Detailed API documentation for ConnectionService, PluginManager, and CredManager
• Frontend Architecture - Vue 3 component structure and composables
• Event System - Event contracts and communication patterns