Desktop App Overview

The Gunsole desktop app is where your logs end up. It’s a native application that runs on macOS, Windows, and Linux.

What it does

1. Receives logs — runs an HTTP server on localhost:17655
2. Stores them — in a local SQLite database
3. Displays them — in a real-time, virtualized log table
4. Filters them — by level, bucket, tags, message search, time range

Architecture

SDK (your app)
  ↓ POST /logs (gzip JSON)
HTTP Server (port 17655)
  ↓ async channel
Log Batcher (buffers per project)
  ↓ flush every 100ms or 50 logs
SQLite (local database)
  ↓ event
UI (virtualized table)

The HTTP server accepts logs and returns 200 OK immediately. Logs are processed asynchronously — batched, stored in the database, and emitted to the frontend as events. This keeps ingestion fast even under high log volume.

Performance

• Virtualized rendering — handles 100K+ log entries smoothly
• Server-side filtering — all filtering happens via SQL, not in the UI layer
• Indexed queries — timestamps, levels, buckets, and tags all have database indexes
• Log batching — incoming logs are buffered and flushed in batches to reduce rendering churn
• Gzip decompression — the server automatically handles compressed payloads

Database

SQLite with WAL mode, stored locally. No external database, no server, no configuration.

Tables: workspaces, projects, buckets, filters, logs, tags, log_tag_map, app_preferences. Migrations run automatically on startup.

See Installation for database file locations per OS.

Auto-creation

Projects, buckets, and tags are all auto-created. The first time the app receives a log with a new projectId, it creates the project. First time it sees a new bucket name, it creates the bucket. First time it sees a new tag key-value pair, it indexes it. Each new project gets a default “All Logs” filter.

You never need to configure anything before sending logs.

Window management

• Main Window: App shell with sidebar + content area. macOS overlay title bar with traffic lights and drag region. Closing hides to tray (doesn’t quit).
• Settings Window: Separate dedicated window (750x650). Opened via Cmd+, / gear icon / tray menu. If already open, focuses and navigates to the requested section.
• Inspector Window: Per-log detail view (700x800). Reuses existing window for same log ID. Shows full context JSON, tags as chips, and all metadata fields.
• New Window: Cmd+N / Ctrl+N creates a new main window instance, optionally scoped to a workspace.

System tray

• Icon: Custom monotone icon, uses template mode on macOS (adapts to light/dark menu bar).
• Menu: Open Gunsole, Settings…, Exit.
• Left-click: Show and focus the main window.
• Behavior: Main window hides on close (stays in tray). App runs in background receiving logs even when all windows are hidden.

Menu bar

Full system menu bar with keyboard accelerators:

• macOS: Gunsole | File | View | Go | Filter | Logs | Window | Help
• Windows/Linux: File | View | Go | Filter | Logs | Help

Menu	Items
View	Toggle Sidebar, Zoom In/Out/Reset, Full Screen, Refresh Logs
Go	Quick Switch (Cmd+K), Back, Forward
Filter	New Filter, Save Filter, Duplicate Filter, Reset Filter, Toggle individual levels (Cmd+1–4)
Logs	Export Logs, Copy Selected, Pause/Resume Live Tail, Scroll to Top/Bottom, Project Data (opens settings)
Help	Documentation, Keyboard Shortcuts (Cmd+/)

Settings

Opens in a separate window with these sections:

• Workspace Management: Create, rename, delete, and reorder workspaces. Custom emoji icons from a curated icon set. Default workspace (“Unsorted”) is locked.
• Project Settings: Per-project log retention days, auto-delete toggle. Clear logs per project or per bucket. Project workspace assignment, rename, delete. Accessible via /settings/projects and /settings/projects/$projectId.
• General Preferences: Theme selection (Auto / Light / Dark).
• About Gunsole: App version, platform info, links to GitHub and documentation.
• Danger Zone: “Clear All Logs” (keeps structure — projects, buckets, filters remain) and “Clear All Data” (nuclear reset — deletes everything, recreates default workspace). Both require confirmation.

Command palette (Cmd+K)

• Quick switcher dialog for navigating across all projects and filters
• Fuzzy search by project name, filter name, or workspace name
• Arrow keys + Enter to navigate, Escape to close

Keyboard shortcuts

Shortcut	Action
Cmd+, (Ctrl+,)	Open Settings
Cmd+N (Ctrl+N)	New Window
Cmd+K (Ctrl+K)	Quick Switch (Command Palette)
Cmd+B (Ctrl+B)	Toggle Sidebar
Cmd+R (Ctrl+R)	Refresh Logs
Cmd+= / Cmd+- / Cmd+0	Zoom In / Out / Reset
Cmd+F (Ctrl+F)	Full Screen
Cmd+[ / Cmd+]	Navigate Back / Forward
Cmd+Shift+N	New Filter
Cmd+S (Ctrl+S)	Save Filter
Cmd+D	Duplicate Filter
Cmd+1 / 2 / 3 / 4	Toggle Info / Debug / Warn / Error
Cmd+E (Ctrl+E)	Export Logs
Cmd+Shift+C	Copy Selected Logs
Cmd+P (Ctrl+P)	Pause/Resume Live Tail
Cmd+Up / Cmd+Down	Scroll to Top / Bottom
Cmd+A (Ctrl+A)	Select All Logs
Cmd+/ (Ctrl+/)	Keyboard Shortcuts Reference

Theme

• Color Palette: Grayscale (50–900) with green accent #22C55E.
• Log Level Colors: Info (grey), Debug (light grey), Warn (amber #F59E0B), Error (red #EF4444), Fatal (error.dark).
• Typography: IBM Plex Sans, 12px base.
• Light/Dark Mode: Full support with system auto-detection and manual override.
• UI Style: Border-based (no shadows), no ripple effects, custom scrollbars.

Toast notifications

• Fixed bottom-right corner, stacked vertically.
• Severities: success, info, warning, error.
• Auto-dismiss after 4 seconds with manual close button.

Welcome page

Shown on first launch or when no project is selected. Contains:

1. Gunsole logo and tagline: “A bucket-based log viewer”
2. SDK installation command: pnpm add @gunsole/web
3. Copyable quick-start code example
4. “How it works” explainer (bucket grouping, auto-sidebar, saved filters, local persistence)
5. Listening status: http://localhost:17655

Real-time events

When logs arrive, the backend emits events to update the frontend instantly:

Event	Payload	Description
gunsole-log-batch	{ projectId, logs }	New logs arrived
gunsole-new-project	Project	Project auto-created
gunsole-new-bucket	Bucket	Bucket auto-created
gunsole-tags-updated	—	New tags discovered

Routes

Route	View
/welcome	Getting started page
/project/$projectId	Project dashboard
/project/$projectId/$filterId	Log viewer with filter
/inspector/$logId	Log inspector (separate window)
/settings	Settings (separate window)
/settings/projects	Project list
/settings/projects/$projectId	Project settings