Web UI

MOSAIC includes an optional graphical web interface built with Flask, HTMX, and Pico CSS. It mirrors all the features of the CLI in a browser-based interface.

Installation

The web UI requires the ui extra:

pipx inject mosaic-search "flask>=3.0" "waitress>=3.0"   # pipx
uv tool inject mosaic-search "flask>=3.0" "waitress>=3.0" # uv
pip install 'mosaic-search[ui]'                            # pip / venv

Launch

mosaic ui

This starts a local Waitress server (production-grade, multi-threaded) and opens your browser to http://127.0.0.1:5555.

Options

Flag	Default	Description
--port	5555	Port number
--host	127.0.0.1	Bind address (0.0.0.0 for LAN access)
--no-browser	off	Don't auto-open the browser
--debug	off	Use Flask dev server with hot-reload

mosaic ui --port 8080                 # custom port
mosaic ui --host 0.0.0.0             # accessible on LAN
mosaic ui --no-browser                # headless / remote
mosaic ui --debug                     # development mode (hot-reload)

Pages

Search

The main page. Enter a query, select sources, apply filters, and view results in a paginated table.

Features:

• Source selection — check/uncheck individual sources, select all / deselect all
• Filters — year (range, list, or single), author, journal, field scope
• Sort — by default order, citations, or year
• Post-filters — open-access only, PDF available only
• Per-source progress — live badges show which sources are done, pending, or errored
• Parallel queries — sources are queried concurrently (up to 8 threads) for faster results
• Pagination — results are paginated (25 per page) when there are many hits
• Export — download results as CSV, JSON, BibTeX, or Markdown

Paper Detail

Click any paper title in the results table to see the full record:

• Title, authors, year, journal, volume/issue/pages
• DOI and arXiv links (clickable)
• Open Access and citation count
• Full abstract
• Action buttons: Open PDF, Open URL, DOI Link, Download PDF, Find Similar

Similar Papers

Find papers related to a known DOI or arXiv ID. Uses OpenAlex related_works and Semantic Scholar recommendations.

History

All past searches are saved to the local SQLite cache. The history page lists them with result counts, timestamps, and a Re-run button to repeat any previous search.

Configuration

View and edit all MOSAIC settings from the browser:

• Download directory and filename pattern
• API keys for all sources (Elsevier, Semantic Scholar, CORE, NASA ADS, IEEE, Springer, NCBI, Zotero)
• Unpaywall email
• Enable/disable individual sources

Changes are saved to ~/.config/mosaic/config.toml, the same file used by the CLI.

Keyboard Shortcuts

Shortcut	Action
Ctrl+Enter (or Cmd+Enter)	Submit the current form
/	Focus the search input

Theme

Click the ◑ icon in the navigation bar to cycle between auto, light, and dark mode. The setting is persisted in your browser's local storage.

Standalone Desktop App (Windows / macOS / Linux)

Pre-built standalone executables are attached to each GitHub release — no Python installation required.

Platform	Download	Notes
Windows	MOSAIC-Windows.zip	No extra runtime required
macOS (Apple Silicon)	MOSAIC-macOS-arm64.zip	macOS 12+
Linux	MOSAIC-Linux.tar.gz	x86-64, glibc 2.31+

The app starts a local server and opens your default browser automatically. No installation, no extra runtimes needed.

Extract and run

# Windows (PowerShell)
Expand-Archive MOSAIC-Windows.zip .
.\MOSAIC\MOSAIC.exe

# macOS
unzip MOSAIC-macOS-arm64.zip
open MOSAIC.app   # or double-click in Finder

# Linux
tar xzf MOSAIC-Linux.tar.gz
./MOSAIC/MOSAIC

Architecture Notes

• Server: Waitress (pure-Python, multi-threaded WSGI server). --debug mode falls back to Flask's built-in dev server for hot-reload.
• Frontend: HTMX for dynamic interactions (no page reloads), Pico CSS for styling (~130 KB total static assets).
• Background jobs: Long-running searches and PDF downloads run in a thread pool and report progress via polling. An SSE stream endpoint (/stream/<job_id>) is also available.
• Database: Shares the same SQLite cache as the CLI (~/.local/share/mosaic/cache.db). Papers found via the UI are available to the CLI and vice versa.