Search & Discovery

Status: ✅ Fully Implemented Phase: Phase 1 (MVP) Completion: 100%

The Search & Discovery surface helps users answer two different questions:

• Which source should I follow? Search the checked-in source catalog.
• What has been published recently? Search recent pulled articles from the most relevant feeds.

Features

Unified Search Interface

Single search bar at /search with an explicit scope switch for Sources vs Articles.

Local Source Search

Source search reads the repository catalog directly and returns feeds that match:

• Feed titles
• Descriptions and notes
• Topics
• Source type and verification filters

This is the default mode and works without any external backend.

Recent Article Search

Article search stays local-first as well, but it is intentionally bounded:

• The app first ranks candidate sources from the catalog
• It fetches recent posts from the best-matching feeds
• It searches within those pulled article titles, summaries, authors, and categories

The response metadata reports how many sources were scanned so the UI can make the bounded behavior explicit.

Autocomplete Suggestions

Autocomplete returns:

• Top matching feeds
• Top matching topics

It is powered by the shipped feed catalog, not by runtime search infrastructure.

Faceted Filtering

Filter both scopes with shared controls:

• Source Type
• Topics
• Verified status

For source results, each match can link directly into the live reader.

Analytics Logging

If a Python backend is configured, the web app logs executed searches using the anonymous user identity bootstrap. If no backend is configured, search still works and the analytics write is skipped.

Configuration

# Optional backend for search analytics logging
BACKEND_URL=http://localhost:8000

Usage

Web Interface

Navigate to /search:

1. Type query in search bar
2. Choose Sources or Articles
3. Select an autocomplete suggestion or press Enter
4. Apply source-type, topic, or verified filters
5. Open a matching source in the reader when you want the live post stream

Keyboard Shortcuts:

• Cmd/Ctrl+K: Focus search bar
• Arrow keys: Navigate autocomplete suggestions
• Enter: Execute search

CLI

# Catalog search
uv run aiwebfeeds search "transformer attention" --limit 20

# Filter by source type and topic
uv run aiwebfeeds search "pytorch" --source-type blog --topic deeplearning

# Autocomplete against the catalog
uv run aiwebfeeds search autocomplete openai --limit 5

API

// Source search
const response = await fetch("/api/search?q=transformer&scope=sources&limit=20");
const results = await response.json();

// Article search
const articleResults = await fetch("/api/search?q=neural%20networks&scope=articles&limit=20");

// Autocomplete
const suggestions = await fetch("/api/search/autocomplete?prefix=mach");

Performance

• Autocomplete: Catalog-backed and lightweight enough for interactive typing
• Source Search: Reads checked-in data without depending on a backend runtime
• Article Search: Bounded on purpose so the browser can stay responsive

Zero Results Handling

When no results are found, the UI steers the user toward:

• Broader source search
• Fewer filters
• Switching from article search back to source search first

Success Criteria

• ✅ Local source search returns feed matches without a backend dependency
• ✅ Article search exposes bounded-scan metadata to explain its coverage
• ✅ Source results can jump directly into the reader

Related

• Analytics Dashboard - View search analytics and popular queries
• Reader - Open matching sources as a live merged timeline
• Recommendations - AI-powered feed suggestions
• Search architecture - Runtime and local search split