🚀 Kabang: Self-Hosted Search Shortcut Engine

Kabang is a high-performance, self-hosted search redirection service inspired by DuckDuckGo’s !bang syntax. Built with a modern TypeScript stack (Bun, Hono, React 19), it allows users to reclaim their search workflow with privacy-focused, customizable shortcuts that route queries across the web instantly.

---

🛠️ The Tech Stack

Layer	Technology	Why?
Runtime	Bun	High-performance JS runtime, bundler, and package manager.
Backend	Hono	Ultrafast, middleware-friendly web framework.
Frontend	React 19	Latest features with TanStack Router & Query for state.
Styling	Tailwind CSS 4	Utility-first, modern CSS-in-JS alternative.
Database	SQLite / PostgreSQL	Lightweight defaults with Drizzle ORM for type-safety.
DevOps	Docker	Seamless deployment and environment parity.

---

✨ Key Features

⚡ Instant Redirection

Route searches to any engine or internal tool using simple prefixes.

• !gh react → Search GitHub
• !yt lofi → Search YouTube
• !gmail → Direct navigation to inbox (no query required)

🧠 OpenSearch Suggestions

Full implementation of the OpenSearch Suggestions Extension 1.1. As you type in your browser's address bar, Kabang provides real-time, fuzzy-matched autocomplete suggestions for your custom bangs.

🛠️ "Ka-Bang-Bang" (System Commands)

Beyond simple searches, Kabang features built-in system shortcuts for power users:

• !!add <bang> <url>: Create a new shortcut directly from the search bar.
• !!mark <url> "note": Instant bookmarking system with metadata support.
• !!sync: Hot-reload the in-memory cache from the database.

📊 Management Dashboard

A clean, responsive UI for managing your bang collection, importing/exporting JSON configurations, and setting global defaults for query-less searches.

---

🏗️ Architecture Overview

The project is structured as a monorepo designed for vertical scalability and ease of deployment:

• kabang-api/: The core "brain" handling the routing logic, SQLite/Postgres integration, and the suggestion engine.
• kabang-ui/: A modern SPA built with React 19, utilizing TanStack’s suite for robust routing and server-state management.
• kabang-collections/: A modular system for importing pre-curated search shortcuts (e.g., developer tools, office productivity, or entertainment).

---

🚀 Deployment

Kabang is containerized for immediate deployment. Users can spin up a production-ready instance with a single command:

docker-compose up -d