Desktop App Overview

The Gunsole desktop app is where your logs end up. It’s a native application built with Tauri (Rust backend, React frontend) 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 (Axum, port 17655)
  ↓ async channel
Log Batcher (buffers per project)
  ↓ flush every 100ms or 50 logs
SQLite (local database)
  ↓ Tauri event
React 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.

Tech stack

• Frontend: React 19, TanStack Router (file-based), MUI v7, Zustand, Vite
• Backend: Rust, Tauri 2, Axum (HTTP server on port 17655), SQLx + SQLite
• Communication: Tauri IPC (invoke/emit) + HTTP for SDK log ingestion

Performance

• Virtualized rendering — React Virtuoso handles 100K+ log entries
• Server-side filtering — all filtering happens in Rust via SQL, not in JavaScript
• 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.

Settings

Opens in a separate window with these sections:

• Workspace Management: Create, rename, delete, and reorder workspaces. Custom emoji icons. Default workspace (“Unsorted”) is locked.
• Project Settings: Per-project log retention days, auto-delete toggle. Clear logs per project or per bucket.
• 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) and “Clear All Data” (nuclear reset, recreates default workspace). Both require confirmation.

Keyboard shortcuts

Shortcut	Action
Cmd+, (Ctrl+,)	Open Settings
Cmd+N (Ctrl+N)	New Window

Theme

• Color Palette: Grayscale (50–900) with green accent #22C55E.
• Log Level Colors: Info (grey), Debug (light grey), Warn (amber #F59E0B), Error (red #EF4444).
• 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-js
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 Tauri 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