compass-redis-explorer

---

This explorer was built as a proof of concept to showcase what Nova can do — from architecture planning and code generation to UI design and systems integration, end-to-end. Built using GLM-5.1, DeepSeek-V4-Pro, and Kimi-K2.6 models.

---

Nova is part of the Compass suite of AI agents. Here's what the full family can do:

Agent	Specialty
Compass Partner	GUI companion for Nova — chat, manage projects, share files, collaborate
Nova	Full-stack web/app development — architecture, code, UI
Gilford	Excel data wrangling — formulas, pivots, Power Query, VBA
Barnaby	PowerPoint presentation builder — slides, charts, branding
Marlowe	Word document analysis — contracts, reports, research
Alfred	Outlook email assistant — drafts, replies, thread summaries
Office 365	OneDrive, SharePoint, Teams, Outlook calendar integration

Compass brings them together. All agents share context and can hand off work between each other — for example, Gilford prepares the data and hands it off to Barnaby to build the presentation, or Nova scaffolds an app and hands it off to Marlowe to document it.

Learn more at compassap.ai.

---

About this project

A desktop Redis explorer built with Tauri v2 + React + TypeScript + redis-rs. Connect to multiple Redis instances simultaneously, browse keys by prefix hierarchy, view/edit all Redis data types, and execute raw commands via a CLI panel.

Inspired by skills.sh — modern brutalist terminal aesthetic, monospace-first, high-contrast, structurally honest.

---

Tech Stack

Layer	Technology	Notes
Shell	Tauri v2	Native desktop wrapper
Frontend	React 19 + TypeScript	UI layer
Styling	Tailwind CSS v4 + shadcn/ui	Brutalist custom theme
Redis Client	redis-rs (Rust crate)	All Redis operations in Rust
State	Zustand	Lightweight, desktop-optimized
Data Display	TanStack Table v8	Virtualized, handles large key sets
IPC	Tauri Commands	Typed Rust ↔ TypeScript bridge

---

Architecture

React UI (TypeScript)
    ↕  Tauri IPC commands
Rust backend (redis-rs)
    ↕  Redis protocol
Redis server(s)

All Redis operations go through Rust #[tauri::command] handlers. The frontend never calls Redis directly — it invokes typed Tauri commands that return structured JSON.

---

Project Structure

src/                          # Frontend (React + TypeScript)
├── components/
│   ├── ui/                   # shadcn/ui primitives (brutalist overrides)
│   ├── connection/           # Connection sidebar
│   ├── browser/              # Key browser + tree
│   ├── viewer/               # Value viewer/editor
│   ├── cli/                  # CLI panel
│   └── layout/               # App shell, panels, resize
├── stores/                   # Zustand stores
├── hooks/                    # Custom React hooks
├── lib/                      # Utilities, Tauri command wrappers
├── types/                    # TypeScript types (mirroring Rust structs)
└── styles/                   # Global CSS, Tailwind config

src-tauri/                    # Backend (Rust)
├── src/
│   ├── commands/              # Tauri command handlers
│   ├── redis/                 # Redis client logic (redis-rs)
│   ├── connection/            # Connection pool management
│   └── serialization/         # Serde helpers
├── Cargo.toml
└── tauri.conf.json

docs/adr/                     # Architecture Decision Records

---

Getting Started

Prerequisites

• Node.js ≥ 20
• Rust (stable)
• Tauri v2 prerequisites

Installing Rust

Rust is required for Tauri v2. If cargo is not found when running npm run tauri dev, install Rust first.

Windows

# Option 1: winget (recommended)
winget install Rustlang.Rust.MS

# Option 2: Direct installer
# Download and run https://rustup.rs/

macOS / Linux

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

After installation, restart your terminal and verify:

rustc --version    # Should print e.g. rustc 1.85.0
cargo --version    # Should print e.g. cargo 1.85.0

Rust toolchain configuration

# Ensure you're on the stable toolchain (default)
rustup default stable

# Update to the latest stable release
rustup update stable

# Add MSVC target (Windows — required for Tauri on Windows)
# This is typically auto-detected, but if you get linker errors:
rustup target add x86_64-pc-windows-msvc

# Useful cargo commands

cargo check       # Quick compile check (faster than build)
cargo clippy      # Lint your Rust code
cargo fmt         # Format Rust code

Windows Defender exclusions (required on Windows)

Windows Defender real-time scanning can quarantine Cargo's .exe build scripts during compilation, causing Access is denied (os error 5) errors on crates like proc-macro2, quote, serde_core, etc.

Fix: Add the Cargo target directory as a Windows Defender exclusion.

Option 1 — PowerShell (run as Administrator):

Add-MpPreference -ExclusionPath "C:\Users\<YOUR_USER>\source\repos\compass-redis-explorer\src-tauri\target"

Option 2 — GUI:

1. Open Windows Security → Virus & threat protection → Manage settings
2. Scroll to Exclusions → Add exclusion → Folder
3. Add the src-tauri\target folder path

After adding the exclusion, clean and rebuild:

# Clean any corrupted build artifacts
cd src-tauri
cargo clean
cd ..

# Rebuild
npm run tauri dev

Tauri-specific notes

• Windows: Requires the Visual Studio C++ Build Tools (install the "Desktop development with C++" workload). The winget Rust installer includes this prompt.
• macOS: Requires Xcode Command Line Tools (xcode-select --install).
• Linux: Requires system dependencies — see Tauri Linux prerequisites.

Install

# Install frontend dependencies
npm install

# Build and run in development mode
npm run tauri dev

Build for Production

npm run tauri build

Output binaries go to src-tauri/target/release/bundle/.

---

Features

• Multi-connection -- Connect to multiple Redis instances simultaneously
• Key hierarchy -- Tree view by : delimiter with lazy-loaded nodes
• Value viewer/editor -- Handles strings, hashes, lists, sets, sorted sets, streams, JSON
• TTL management -- View and modify key expiration
• CLI panel -- Raw Redis command input with formatted output
• Dark/Light mode -- Respects OS preference, manual toggle, persisted
• Brutalist UI -- No rounded corners, no shadows, monospace data, maximum density

---

Key Design Decisions

All architectural decisions are documented in docs/adr/:

ADR	Decision
ADR-0001	Tauri v2 as application shell
ADR-0002	React + TypeScript for frontend UI
ADR-0003	shadcn/ui with Tailwind CSS (brutalist customization)
ADR-0004	Zustand for state management
ADR-0005	redis-rs for Redis client
ADR-0006	Tauri IPC for frontend-backend communication
ADR-0007	TanStack Table for data display
ADR-0008	Connection management architecture
ADR-0009	Key hierarchy navigation pattern
ADR-0010	Data serialization format

---

Security & Architecture Highlights

This project was designed with security-first and production-ready principles from the ground up:

• No localhost attack surface — All frontend-backend communication uses Tauri IPC (no HTTP/WebSocket server). This eliminates CSRF, port-scanning, and credential-interception vectors that plague local-server approaches (ADR-0006).
• Capability-based permissions — Tauri v2's permission model means the frontend can only invoke explicitly-allowed commands. No blanket access to system APIs.
• AES-256-GCM credential encryption — Connection profiles (including passwords and service keys) are encrypted at rest with AES-256-GCM before being written to disk. Random 12-byte nonces per encryption operation prevent nonce reuse. The encryption key is auto-generated and stored separately from the encrypted data (ADR-0011).
• URL redaction — Redis connection URLs are constructed with a to_url_redacted() method that masks passwords (***) in logs, debug output, and UI display. Credentials never appear in plaintext outside of the encryption boundary.
• Structured error types — All IPC errors use a typed IpcError envelope (code, message, details) instead of raw strings. This prevents credential leakage through error messages and enables the UI to show contextual recovery actions.
• SCAN-only key iteration — Never uses KEYS *. All key browsing uses SCAN with cursor-based pagination, which is safe for production Redis instances regardless of dataset size (ADR-0009).
• Typed IPC boundary — Rust RedisValue enum with #[serde(tag)] produces a discriminated union at the TypeScript boundary. The compiler enforces exhaustive handling of all Redis types — no silent data loss (ADR-0010).
• Connection health monitoring — Periodic PING commands (configurable, default 30s) detect dropped connections early, with exponential backoff reconnection (1s → 30s max) and frontend notification via Tauri events.
• TLS-first connections — Automatic TLS detection based on port (6380/6381) or explicit toggle. Uses rustls backend — no OpenSSL dependency, smaller binary, simpler cross-compilation.

---

Design System

The UI follows a modern brutalist terminal aesthetic -- see NOVA.md for the full specification:

• Compass purple/indigo/blue color palette (light + dark)
• Monospace-first typography (JetBrains Mono for data, Inter for headings)
• No rounded corners, no box shadows, 1px solid borders only
• Dense spacing, resizable panels, three-column IDE layout

---

License

This project is licensed under the MIT License.

---

Last updated: 2026-05-08
Co-authored by Nova