HotTea Documentation

Getting Started

HotTea brings web browsing, multi-engine search, offline note taking, and local data persistence into one application built with Flutter and Dart.

Unlike traditional browsers that push user data to proprietary cloud services, HotTea operates locally on your machine. Bookmarks, history records, and research notes are saved directly into a SQLite database without external analytics or tracking beacons.

Architecture & System Design

HotTea enforces strict layer boundaries to decouple the user interface from platform-specific web rendering engines and storage mechanisms:

• UI Layer (lib/main.dart): Premium Glassmorphic Flutter interface with responsive desktop, tablet, and mobile layouts.
• Theme & Brand Tokens (lib/core/theme/): GlassTheme, GlassDock, GlassSurface, AmbientCanvasBackground, and the official vector HotTeaLogo.
• Browser Domain (lib/features/browser/domain/): Core abstractions including BrowserEngine, BrowserTab, SearchEngine, and AddressBarParser.
• Browser Data (lib/features/browser/data/): Concrete platform engine implementations (InAppBrowserEngine with WebKit/WebView, and WebFallbackEngine).
• Persistence Layer (lib/core/persistence/): LocalPersistenceRepository backed by SQLite (sqflite_common_ffi on desktop, sqflite on iOS/Android, and sqflite_common_ffi_web on Web).

Glassmorphic UI System

HotTea delivers a state-of-the-art glassmorphism design across macOS, iOS, Android, Linux, and Windows, featuring ambient backdrop blurs, luminous amber highlights, and unified control docks:

• GlassDock Bottom Bar: A floating, frosted glass dock on mobile platforms housing quick-access navigation buttons (Back, Forward, New Tab, Tab Switcher, Settings, and More Actions).
• Integrated Settings Control: Direct access to browser preferences from both the primary mobile dock, the desktop top toolbar & sidebar, and the frosted Action Sheet.
• Ambient Canvas Background: Multi-layered radial gradients emitting warm amber (#D48B47) and icy blue atmospheric glows behind all window content.
• Official HotTea Vector Identity: Precision SVG-rendered tea-cup icon (with steam trails and saucer) integrated natively into headers, modals, and brand badges.
• Frosted Action Sheets: High-blur (20px) modal overlays providing quick toggles for Private Mode, Desktop Site, Bookmarks, and in-place zoom controls.

Android Release (APK)

HotTea is officially packaged and available as a standalone Android application package (APK):

To install HotTea on your Android device:

1. Download app-release.apk from the HotTea Downloads page or latest GitHub Release.
2. Enable "Install unknown apps" in your Android Settings for your browser or file manager.
3. Open the downloaded APK to install, or deploy via Android Debug Bridge:

   adb install -r app-release.apk

Search Engine System

HotTea provides a provider-independent search engine abstraction in lib/features/browser/domain/search_engine.dart supporting four search providers:

Search URLs are constructed safely using Dart's Uri.https() APIs with strict query-parameter encoding to prevent unescaped string injection.

Tab Management

HotTea tabs operate with completely independent state. Each BrowserTab maintains its own URL history stack, title, favicon, loading indicator, and zoom level:

• Creating a Tab: Click the + button in the tab strip or press Cmd+T (macOS) / Ctrl+T (Windows/Linux).
• Closing a Tab: Click the × icon on the tab card or press Cmd+W. If the last tab is closed, a clean default tab is opened automatically.
• Mobile Tab Switcher: On iPhone and mobile screen sizes, the tab switcher button in the bottom bar opens an ergonomic card grid displaying active hosts and private status badges.

Private / Incognito Browsing

Private browsing tabs isolate your session from persistent storage:

• WebKit Incognito Mode: Initialized with incognito: true, disabling disk caches and persistent DOM cookies.
• Zero History Logging: The navigation listener checks tab.isPrivate before recording history entries; visits made in private tabs are never written to the database.
• Visual Indicators: Private tabs feature purple shield iconography and purple borders in the tab overview.

Downloads System

Downloads are handled through lib/features/browser/data/download_manager.dart with real-time status reporting:

• Files are written to the sandboxed user Downloads directory ($HOME/Documents/Downloads on iOS, standard user Downloads on macOS/desktop).
• Real-time download progress tracking with byte counters, cancellation, and restart capabilities.

Local SQLite Persistence

HotTea uses native SQLite bindings without cloud backends. Database tables:

• bookmarks: id, title, url, category, created_at
• browsing_history: id, title, url, visited_at, visit_count
• research_notes: id, title, content, source_url, source_title, created_at, updated_at

Research Notes & Web Clipping

The research workspace enables side-by-side note taking with web evidence:

• Clip Selection: Highlight any passage on a webpage and click "Clip to Notes" to create a Markdown note pre-filled with the source URL and document title.
• Filtering & Search: Instantly search across note content, tags, and source hosts offline.

Development Setup

Follow these steps to set up your local development workspace:

Troubleshooting

For common build questions regarding CocoaPods, macOS sandboxing, and iOS Xcode 27 multi-architecture configurations, refer to our dedicated Troubleshooting Guide.

Contributing Guidelines

HotTea welcomes contributions from everyone. Please review our Contributing Guide for code standards, testing policies, and responsible security disclosure instructions.