amethyst/docs/brainstorms/2026-03-10-advanced-search-brainstorm.md

# Brainstorm: Advanced Search for Desktop

**Date:** 2026-03-10
**Status:** Draft
**Branch:** TBD (`feat/desktop-advanced-search`)

## What We're Building

Full-featured advanced search for Amethyst Desktop with:
1. **Twitter-style query operators** (`from:`, `kind:`, `since:`, etc.) that map to NIP-50 Filter fields
2. **Form-based UI** (expandable panel below search bar) for users who don't want to learn syntax
3. **Bidirectional sync** between text operators and form controls — editing one updates the other
4. **Extensible kind presets** — toggle groups like Notes, Articles, Media, Communities
5. **Future AI bridge** (follow-up) — natural language → structured query conversion

**Philosophy:** Relay-first, pragmatic. Desktop users have resources; we prioritize completeness over privacy. Privacy controls available but not default friction.

## Why This Approach

- **No standard Nostr query language exists** — we define one that maps cleanly to `Filter` fields
- **Dual interface (text + form)** — power users get speed, casual users get discoverability
- **Current desktop search is minimal** — only kind 0 + 1, no operators, no kind filtering
- **Android has 30+ kinds** but no query language — desktop leapfrogs with both
- **AI deferred** — core query system must work standalone first; AI is a parsing layer on top

## How Other Clients Do Search

| Client | Approach | Operators | Notable |
|--------|----------|-----------|---------|
| **Amethyst Android** | Local cache + NIP-50, 30+ kinds | None (plain text) | Search relay list (kind 10007) |
| **Primal** | Proprietary caching server | Form UI only | Event type, time range, scope dropdowns |
| **Coracle** | NIP-50 + configurable relays | None | Also supports DVM requests (NIP-90) |
| **Damus** | NIP-50 relay search | None | User/profile focused |
| **noStrudel** | Local relay + NIP-50 | None | IndexedDB local indexing |
| **Gossip** | NIP-50 relay search | None | Desktop Rust client |
| **Noogle.lol** | NIP-90 DVM search | `from:npub` `from:me` | Pay-per-query via Lightning |

**Key insight:** No client ships a query operator language. This is greenfield.

## Proposed Query Schema

Operators map directly to `Filter` fields and NIP-50 extensions:

### Core Operators

| Operator | Maps To | Example | Notes |
|----------|---------|---------|-------|
| `from:<npub\|name>` | `Filter.authors` | `from:npub1abc...` | Resolve names via NIP-05/local cache |
| `kind:<number\|name>` | `Filter.kinds` | `kind:note` or `kind:1` | Named aliases for common kinds |
| `since:<date>` | `Filter.since` | `since:2025-01-01` | ISO 8601 date parsing |
| `until:<date>` | `Filter.until` | `until:2025-06-30` | ISO 8601 date parsing |
| `#<tag>` | `Filter.tags["t"]` | `#bitcoin` | Hashtag filter |
| `"exact phrase"` | Quoted in `Filter.search` | `"lightning network"` | Relay-dependent support |
| `-<term>` | Client-side exclusion | `-spam` | Post-filter after relay results |

### NIP-50 Extension Operators

| Operator | NIP-50 Extension | Example |
|----------|-----------------|---------|
| `lang:<code>` | `language:xx` | `lang:en` |
| `domain:<nip05>` | `domain:xx` | `domain:nostr.com` |
| `nsfw:<bool>` | `nsfw:xx` | `nsfw:false` |

### Kind Name Aliases

| Alias | Kind(s) | Description |
|-------|---------|-------------|
| `note` | 1 | Short text note |
| `article` | 30023 | Long-form content |
| `repost` | 6 | Reposts |
| `reply` | 1 (with `e` tag) | Replies (client-side filter) |
| `media` | 1 (with `imeta` tag) | Notes with media |
| `channel` | 40, 41, 42 | Public channels |
| `live` | 30311 | Live activities |
| `community` | 34550 | Communities |
| `wiki` | 30818 | Wiki pages |
| `video` | 34235 | Video events |
| `classified` | 30402 | Classifieds |
| `profile` | 0 | Metadata/profiles |

### Boolean Logic

| Syntax | Behavior |
|--------|----------|
| `bitcoin lightning` | AND (default) |
| `bitcoin OR lightning` | OR — requires multiple relay queries |
| `-spam` | NOT — client-side exclusion |

## UX Design

### Search Bar (Default State)
```
[  Search notes, people, tags...  ] [Advanced v]
```

### Expanded Advanced Panel
```
[  from:npub1abc kind:note since:2025-01 bitcoin          ] [Advanced ^]
+------------------------------------------------------------------+
| Content Type: [x] Notes [ ] Articles [ ] Media [ ] All           |
| Author:       [ npub or name...              ] [+ Add]           |
| Date Range:   [ 2025-01-01 ] to [ today ]                       |
| Language:     [ Any v ]                                          |
| Hashtags:     [ #bitcoin ] [+ Add]                               |
| Exclude:      [ spam, nsfw...                ] [+ Add]           |
|                                                                  |
| [Clear Filters]                          [Search]                |
+------------------------------------------------------------------+
```

### Bidirectional Sync
- Typing `from:npub1abc` in search bar → Author field populates in panel
- Selecting "Articles" checkbox → `kind:article` appears in search bar
- Editing either side updates the other in real-time
- Form is the "visual representation" of the query string

### Result Display
- Results grouped by type: People, Notes, Articles, Channels
- Each result shows: content preview, author, timestamp, kind badge
- Infinite scroll with "Load more from relays" button
- Sort: Relevance (default, relay-determined) or Chronological

## Architecture

### Query Pipeline

```
User Input (text or form)
    |
    v
QueryParser (commons/commonMain)
    |-- Tokenize operators: from:, kind:, since:, etc.
    |-- Resolve names → hex pubkeys (local cache + NIP-05)
    |-- Parse dates → unix timestamps
    |-- Map kind aliases → kind numbers
    |
    v
SearchQuery (data class in commons)
    |-- text: String (free text for NIP-50 search field)
    |-- authors: List<HexKey>
    |-- kinds: List<Int>
    |-- since: Long?
    |-- until: Long?
    |-- tags: Map<String, List<String>>
    |-- excludeTerms: List<String>
    |-- language: String?
    |-- nip50Extensions: Map<String, String>
    |
    v
FilterBuilder (desktop)
    |-- Convert SearchQuery → List<Filter>
    |-- Split by kind groups (like Android: 3 filters, ~10 kinds each)
    |-- Inject NIP-50 extensions into search string
    |
    v
Relay Subscription
    |-- Use search relay list (kind 10007) or connected relays
    |-- Send REQ with filters
    |-- Aggregate results
    |
    v
Client-side Post-filter
    |-- Apply exclusions (-term)
    |-- Apply "reply" detection (has e tag)
    |-- Apply "media" detection (has imeta tag)
    |
    v
Results Display
```

### Module Placement

| Component | Module | Rationale |
|-----------|--------|-----------|
| `QueryParser` | `commons/commonMain` | Reusable for Android later |
| `SearchQuery` | `commons/commonMain` | Shared data model |
| `QuerySerializer` | `commons/commonMain` | SearchQuery ↔ string conversion |
| `AdvancedSearchPanel` | `desktopApp` | Desktop-specific UI |
| `SearchScreen` (updated) | `desktopApp` | Desktop layout |
| `FilterBuilder` (updated) | `desktopApp` | Desktop filter assembly |
| Kind alias registry | `commons/commonMain` | Shared kind name mapping |

### Search Relay Management

- Use existing `SearchRelayListEvent` (kind 10007) from quartz
- Desktop UI to configure search relays (settings page)
- Default fallback: `relay.nostr.band`, `nostr.wine`, `relay.damus.io`
- Future: auto-discover NIP-50 capable relays via NIP-11

## Privacy Considerations

| Concern | Mitigation | Default |
|---------|-----------|---------|
| Relay sees search queries | User-configurable search relay list | On (kind 10007) |
| Relay sees IP + query | VPN/Tor support (system-level) | Not enforced |
| Query history stored | No server-side history; client-side optional | Off |
| NIP-05 resolution leaks interest | Cache NIP-05 lookups locally | On |
| Author search reveals social graph | Already visible via follow lists | N/A |

**Stance:** Relay-first, pragmatic. Desktop users accept relay visibility for better results. Advanced users can configure search relays or use Tor.

## Key Decisions

1. **Query language is NOT a Nostr standard** — it's a client-side UX convention that maps to `Filter` fields
2. **Bidirectional sync** between text bar and form panel — single source of truth (`SearchQuery` data class)
3. **Kind presets with extensibility** — start with core groups, users can toggle individual kinds
4. **Relay-first execution** — NIP-50 search as primary, local cache as supplement
5. **AI deferred** — follow-up feature, will parse natural language → `SearchQuery`
6. **Query parser in commons** — shared module so Android can adopt later
7. **Client-side post-filtering** for operators relays can't handle (exclusions, reply detection, media detection)

## Resolved Questions

1. **Name resolution** — Async + refine. Search immediately with text, resolve `from:name` in background, refine results when pubkey resolved. No blocking.
2. **OR queries** — Yes in v1. `bitcoin OR lightning` sends parallel relay subscriptions, merges results.
3. **Search history** — Recent history (last 20) stored locally.
4. **Saved searches** — Yes in v1. Pin/save queries. Future: persist as Nostr events.
5. **Result caching** — Session cache only (in-memory). Cleared on app restart. No disk persistence.

## Open Questions

None — all resolved.

## Follow-up Features (Out of Scope)

- AI natural language → query parsing (local Ollama / cloud API / NIP-90 DVM)
- Local SQLite FTS5 index for offline search
- NIP-90 DVM search integration
- Search analytics / trending topics
- Collaborative search (shared saved searches via Nostr events)