HyperTagBrowser

A modern, native macOS file browser with advanced tagging and filtering capabilities built with SwiftUI.

Overview

HyperTagBrowser is a sophisticated file management application that goes beyond traditional file browsers by providing powerful tagging, filtering, and organization features. Built entirely with SwiftUI for macOS, it offers a native experience with modern design patterns and efficient file indexing.

Features

🏷️ Advanced Tagging System

• Multi-domain tagging: Organize files with descriptive, attribution, creation date, and queue-based tags
• Smart tag suggestions: Context-aware tag recommendations as you type
• Tag hierarchies: Create relationships between tags for better organization
• Bulk tag operations: Apply or remove tags from multiple files simultaneously

🔍 Powerful Filtering & Search

• Real-time filtering: Instantly filter files by tags, dates, artists, creators, and more
• Complex queries: Combine multiple filter criteria for precise results
• Date-based filtering: Filter by creation dates with flexible date ranges
• Search suggestions: Intelligent autocomplete for tag and content search

📱 Modern SwiftUI Interface

• Native macOS design: Built with SwiftUI following Apple's Human Interface Guidelines
• Responsive layout: Adapts to different window sizes and screen configurations
• Dark mode support: Full support for light and dark appearance modes
• Keyboard navigation: Comprehensive keyboard shortcuts for power users

🖼️ Rich Media Support

• Thumbnail generation: Automatic thumbnail creation for images and documents
• Grid and table views: Multiple viewing modes for different use cases
• Detail inspector: Comprehensive file information and metadata display
• Image preview: Built-in image viewing with zoom and pan capabilities

⚡ Performance & Efficiency

• Background indexing: Efficient file system scanning without blocking the UI
• SQLite database: Fast, reliable storage for file metadata and tags
• Memory optimization: Smart caching and resource management
• Incremental updates: Only re-index changed files for better performance

System Requirements

• macOS: 15.0 or later
• Architecture: Apple Silicon (M1/M2/M3) or Intel
• Memory: 4GB RAM minimum, 8GB recommended
• Storage: 100MB for the application, additional space for database

Installation

From Source

1. Clone the repository

   git clone https://github.com/robinsr/HyperTagBrowser.git
   cd HyperTagBrowser

2. Open in Xcode

   open HyperTagBrowser.xcodeproj

3. Build and run

   • Select your target device (Mac)
   • Press Cmd+R to build and run
   • Or use Product > Run from the menu

Development Setup

The project uses several dependencies managed through Swift Package Manager:

• GRDB: Database layer with SQLite
• Factory: Dependency injection
• Defaults: User preferences management
• GRDBQuery: Reactive database queries
• MacSettings: Settings UI components

Usage

Getting Started

1. Launch the app and grant necessary permissions for file access
2. Select a folder to index using the folder picker or drag and drop
3. Wait for indexing to complete (progress is shown in the status bar)
4. Start tagging files by selecting them and using the tag panel

Key Features

Tagging Files

• Select one or more files
• Open the tag panel (⌃T)
• Type tag names and press Enter to apply
• Use tag suggestions for consistency

Filtering Content

• Use the browse refinements panel (⌃F)
• Add multiple filter criteria
• Combine tags, dates, and other attributes
• Save frequently used filter combinations

Navigation

• Grid view: Visual browsing with thumbnails
• Table view: Detailed list with sortable columns
• Detail view: Full file information and preview
• Sidebar: Quick access to bookmarks and work queues

Keyboard Shortcuts

Action	Shortcut
Show Quick Actions	⇧⌘P
Toggle Sidebar	⌃S
Show Filters	⌃F
Show Bookmarks	⌃B
Show Work Queues	⌃Q
Manage Tags	⌃T
Edit Tags	⌘E
Select All	⌘A
Navigate Back	⌘[
Navigate Forward	⌘]

Architecture

Core Components

• AppViewModel: Main application state management
• IndexerService: File system scanning and metadata extraction
• Database Layer: SQLite-based storage with GRDB
• Tag System: Flexible tagging with multiple domains and types
• UI Components: Modular SwiftUI views and modifiers

Design Patterns

• MVVM: Model-View-ViewModel architecture
• Dependency Injection: Using Factory for service management
• Reactive Programming: GRDBQuery for database observations
• Composition: Modular UI components and modifiers

Development

Project Structure

HyperTagBrowser/
├── App/
│   ├── Components/          # Reusable UI components
│   ├── Data/               # Domain models and view models
│   ├── Screens/            # Main application screens
│   ├── Services/           # Business logic and external services
│   └── Utilities/          # Helper functions and extensions
├── Extensions/             # Swift extensions
├── Resources/              # Assets and resources
└── Tests/                  # Unit and UI tests

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Code Style

• Follow Swift API Design Guidelines
• Use SwiftUI best practices
• Maintain consistent naming conventions
• Include comprehensive documentation
• Write unit tests for new features

Testing

Running Tests

# Run all tests
xcodebuild test -scheme HyperTagBrowser -destination 'platform=macOS'

# Run specific test target
xcodebuild test -scheme HyperTagBrowser -destination 'platform=macOS' -only-testing:HyperTagBrowserTests

Test Coverage

The project includes:

• Unit tests: Core business logic and data models
• UI tests: User interface interactions
• Integration tests: Database and service layer testing

Performance

Optimization Features

• Lazy loading: Images and thumbnails loaded on demand
• Background processing: File indexing doesn't block the UI
• Memory management: Efficient caching and cleanup
• Database optimization: Indexed queries and connection pooling

Benchmarks

• Indexing speed: ~1000 files/second on SSD
• Memory usage: <100MB for typical usage
• Startup time: <2 seconds on modern hardware

Troubleshooting

Common Issues

App won't start

• Check macOS version compatibility
• Verify file permissions
• Check Console.app for crash logs

Slow performance

• Reduce the number of indexed files
• Check available disk space
• Restart the application

Tags not saving

• Verify database permissions
• Check disk space
• Try rebuilding the database

Debug Mode

Enable debug features by adding development flags in the settings panel:

• SQL query logging
• Performance metrics
• UI debugging tools

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with SwiftUI
• Database powered by GRDB
• Icons from SF Symbols
• Design inspiration from native macOS applications

---

HyperTagBrowser - Organize your digital life with intelligent tagging