Stash: Spotlight-Inspired Link Management

Overview

Stash is a modern web-based link and bookmark manager featuring a Spotlight-inspired search interface for organizing and retrieving saved links efficiently. Built with React 19, TypeScript, and Vite, it provides a centralized hub for all your bookmarks with powerful search and categorization capabilities.

Core Features

Spotlight-Style Search Interface

• CMD+K Focused Search: Instant keyboard shortcut to access search
• Real-time Fuzzy Matching: Powered by Fuse.js with weighted field matching
• Multi-dimensional Filtering: Filter by category, collections, tags, and date ranges
• Sort Options: Recent, oldest, alphabetical (ascending/descending)

Smart Categorization System

• Domain Pattern Recognition: 60+ rules for automatic categorization (github.com → Development, youtube.com → Entertainment)
• URL Path Analysis: Pattern recognition for /docs/, /blog/, etc.
• Platform-Specific Tags: Automatic tag extraction for YouTube, GitHub, Twitter, Instagram, Reddit, Spotify, and more
• Nested Category Hierarchy: Support for parent-child relationships

Collections Organization

• User-Organizable Groups: Create collections like folders or playlists
• Nested Structure: Support for sub-collections with cascade deletion
• Default Collections: Favorites, Reading List, Watch Later, Work Projects, Resources
• Multi-Collection Links: A link can belong to multiple collections

Dual Storage Strategy

• localStorage First: Instant access and offline capability
• Supabase Cloud Sync: Optional cloud backup with graceful degradation
• Optimistic Updates: Instant UI feedback with background sync
• Sync Status Tracking: Know which items are local, synced, or pending

Modern UI/UX

• View Modes: Grid and list view for displaying links
• Neumorphic Design: Clean aesthetic with Tailwind CSS v4
• GSAP Animations: Smooth transitions and micro-interactions
• Three.js Background: Subtle animated background effects
• Dark/Light Theme: Full theme support
• Responsive Design: Mobile and desktop optimized

Authentication

• Supabase Auth: Magic links and Google OAuth support
• Graceful Fallback: Works without auth configuration

How It Works

Categorization Pipeline

// The categorizer applies rules in order:
1. Check domain patterns (github.com → development)
2. Check URL path patterns (/docs/ → documentation)
3. Extract platform-specific tags (YouTube video ID, etc.)
4. Fallback to title keyword analysis

Search System

// Fuse.js weighted search configuration
{
  keys: [
    { name: 'title', weight: 0.4 },
    { name: 'url', weight: 0.3 },
    { name: 'description', weight: 0.2 },
    { name: 'tags', weight: 0.1 }
  ]
}

Data Sync Architecture

Schema Transformation:

• Local: camelCase (previewImage, isFavorite, categoryId)
• Supabase: snake_case (preview_image, is_favorite, category_id)

Technical Architecture

Core Hooks

• useLinks - Link CRUD with localStorage + Supabase sync
• useCategories - Category management with system category protection
• useCollections - Collection management with cascade deletion
• useSearch - Fuzzy search with Fuse.js + multi-dimensional filtering
• useFilters - Filter state management
• useAuth - Supabase authentication flow
• useTheme - Dark/light mode management

Component Structure

App.tsx (root state)
├── AuthPage (if not logged in)
├── UserPage / SettingsPage (modals)
└── Main Interface
    ├── SpotlightSearch (Cmd+K focused search)
    ├── FilterBar (category/tag/date filters)
    ├── ActiveFilters (removable filter chips)
    └── Results
        ├── ResultsHeader (view mode toggle, sort)
        ├── LinkGrid / LinkList (grid/list views)
        └── LinkCard (individual link)

Technology Stack

Frontend

• React 19: Latest React with improved concurrent features
• TypeScript 5.9: Type-safe development
• Vite 7: Fast build tool with HMR
• Tailwind CSS v4: Utility-first styling
• GSAP: Production-grade animations
• Three.js: WebGL background effects
• Fuse.js: Fuzzy search library
• Radix UI: Accessible component primitives

Backend/Storage

• Supabase: PostgreSQL database, auth, and real-time sync
• localStorage: First-party local storage for offline access

Why I Built This

The Problem

Existing bookmark managers have limitations:

• Basic Search: Only exact keyword matching
• Flat Organization: No hierarchy or smart categorization
• Slow Access: Multiple clicks to find bookmarks
• No Cloud Sync: Bookmarks trapped in one browser

The Solution

Stash addresses these issues:

• Spotlight Search: Find any link instantly with fuzzy matching
• Smart Organization: Auto-categorization with 60+ domain rules
• Keyboard First: CMD+K to search, CMD+N to add
• Cloud Sync: Access your links anywhere with Supabase
• Offline First: Works without internet connection

Development Status

Current Features

• Spotlight-style fuzzy search
• Hierarchical categories and collections
• Multi-dimensional filtering
• Automatic categorization
• Dual storage (localStorage + Supabase)
• GSAP animations
• Dark/light theme
• Responsive design

Technical Highlights

• Optimistic UI updates
• Graceful degradation without Supabase
• Platform-specific tag extraction (20+ platforms)
• Cascade deletion for nested collections
• Custom hooks pattern for state management

Impact & Vision

Stash represents a new approach to bookmark management - combining the speed of Spotlight with the intelligence of automatic categorization. Whether you're a developer saving documentation, a researcher curating papers, or anyone who wants to organize their web discoveries, Stash helps you find what you need instantly.

The project is part of a larger link management ecosystem including a Chrome extension for saving links while browsing and a FastAPI backend for URL content extraction.