links/mobile/README.md

# Heygo iOS App (黑狗)

A comprehensive iOS link management application that replicates the functionality of the Django-based link management system. Built with SwiftUI, Core Data, and modern iOS development practices.

## Features

### Core Link Management
- ✅ Create, edit, and delete links with unique aliases
- ✅ Support for regular links, custom markdown content, and template URLs
- ✅ URL template processing with parameter placeholders (`{param,default=value}`)
- ✅ Real-time alias validation and duplicate prevention
- ✅ Click tracking and analytics

### Advanced Features
- ✅ Tag-based organization with auto-completion
- ✅ Powerful search with fuzzy matching
- ✅ Comprehensive analytics with charts
- ✅ Markdown rendering for custom content
- ✅ Multi-language support (English and Chinese)
- ✅ Dark mode support
- ✅ Accessibility features

### Analytics & Insights
- ✅ Click tracking with timestamps
- ✅ Visual charts showing usage trends
- ✅ Top performing links analysis
- ✅ Link type distribution
- ✅ Time-based filtering (1 week to all time)
- ✅ Export capabilities

### User Experience
- ✅ Clean, modern SwiftUI interface
- ✅ Intuitive navigation with tab-based structure
- ✅ Pull-to-refresh functionality
- ✅ Swipe actions for quick operations
- ✅ Real-time search and filtering
- ✅ Template parameter input dialogs

## Architecture

### Design Pattern
- **MVVM** (Model-View-ViewModel) with Combine framework
- **Core Data** for persistent storage
- **SwiftUI** for modern, declarative UI

### Key Components

#### Models
- `Link` - Core link entity with alias, URL, type, and metadata
- `Tag` - Categorization system with many-to-many relationship
- `ClickLog` - Track individual clicks with timestamps
- `ChangeLog` - Audit trail for link modifications

#### ViewModels
- `LinkViewModel` - Manages link CRUD operations and business logic
- `TagManager` - Handles tag creation, search, and suggestions

#### Views
- `LinkListView` - Main interface showing all links with search/filter
- `LinkFormView` - Create/edit links with validation
- `LinkDetailView` - Comprehensive link information and analytics
- `SearchView` - Advanced search with filters and suggestions
- `AnalyticsView` - Charts and insights dashboard

#### Utilities
- `URLTemplateProcessor` - Parse and process template URLs
- `MarkdownRenderer` - Render markdown content to AttributedString
- `AnalyticsCalculator` - Generate chart data and statistics
- `PersistenceController` - Core Data stack management

## Technology Stack

### Frameworks & Libraries
- **SwiftUI** - Modern declarative UI framework
- **Core Data** - Local data persistence
- **Charts** - Native charting framework (iOS 16+)
- **Combine** - Reactive programming framework
- **Foundation** - Core system services

### iOS Features Used
- **Universal App** - Supports iPhone and iPad
- **Internationalization** - English and Chinese localization
- **Accessibility** - VoiceOver and accessibility features
- **URL Schemes** - Handle external link opening
- **Share Extensions** - (Future enhancement)

## Project Structure

```
Heygo/
├── HeygoApp.swift              # App entry point
├── ContentView.swift           # Main tab navigation
├── Views/                      # SwiftUI views
│   ├── LinkListView.swift      # Main link list interface
│   ├── LinkFormView.swift      # Link creation/editing
│   ├── LinkDetailView.swift    # Detailed link information
│   ├── SearchView.swift        # Advanced search interface
│   └── AnalyticsView.swift     # Analytics dashboard
├── ViewModels/                 # Business logic
│   └── LinkViewModel.swift     # Main view model
├── Models/                     # Core Data entities
│   ├── CoreDataModel.xcdatamodeld
│   ├── PersistenceController.swift
│   └── [Entity]+CoreDataClass.swift
├── Utils/                      # Utility classes
│   ├── URLTemplateProcessor.swift
│   ├── TagManager.swift
│   ├── MarkdownRenderer.swift
│   └── AnalyticsCalculator.swift
└── Resources/                  # Assets and localization
    ├── Assets.xcassets
    ├── Info.plist
    ├── en.lproj/
    └── zh-Hans.lproj/
```

## Requirements

- **iOS 17.0+** (for Charts framework and latest SwiftUI features)
- **Xcode 15.0+**
- **Swift 5.9+**

## Installation & Setup

1. Open `Heygo.xcodeproj` in Xcode
2. Select your development team in project settings
3. Choose your target device or simulator
4. Build and run (⌘+R)

## Key Features Implementation

### URL Template System
The app supports dynamic URL templates with parameters:
```
https://google.com/search?q={query}
https://github.com/{user}/{repo}
https://maps.apple.com/?q={location,default=New York}
```

### Analytics Engine
Comprehensive analytics with multiple time ranges and metrics:
- Click trends over time
- Top performing links
- Link type distribution
- Activity timeline

### Tag Management
Intelligent tag system with:
- Auto-completion based on existing tags
- Tag suggestions based on URL patterns
- Bulk tag operations
- Usage statistics

### Search & Filter
Advanced search capabilities:
- Fuzzy text matching
- Filter by link type and tags
- Search history
- Quick URL opening

## Performance Considerations

- **Lazy Loading** - Large link collections loaded incrementally
- **Core Data Optimization** - Proper indexing and fetch request optimization
- **Memory Management** - Efficient image and data caching
- **Background Processing** - Analytics calculations performed off main thread

## Accessibility

- **VoiceOver Support** - All UI elements properly labeled
- **Dynamic Type** - Respects user's text size preferences
- **High Contrast** - Supports accessibility color schemes
- **Keyboard Navigation** - Full keyboard accessibility

## Localization

Currently supports:
- **English (en)**
- **Simplified Chinese (zh-Hans)**

Easy to extend for additional languages by adding new `.lproj` directories.

## Future Enhancements

- [ ] iCloud sync capabilities
- [ ] Share extension for adding links from other apps
- [ ] Widgets for quick access to popular links
- [ ] Shortcuts app integration
- [ ] Export/import functionality
- [ ] QR code generation for links
- [ ] Backup and restore features

## Contributing

This iOS app is designed to be a faithful replica of the Django web application. When adding new features, ensure they maintain parity with the web version while taking advantage of iOS-specific capabilities.

## License

[Add your license information here]