{"id":37592442,"url":"https://github.com/raulshma/uniarr","last_synced_at":"2026-01-16T09:52:54.464Z","repository":{"id":319515873,"uuid":"1070081682","full_name":"raulshma/uniarr","owner":"raulshma","description":"UniArr: React Native/Expo app for self-hosted media servers. Unified search, calendar \u0026 management across Radarr, Sonarr, Jellyfin, Bazarr, qBittorrent, Jellyseerr \u0026 more. Offline-first with smart sync, home screen widgets, bulk downloads, VPN diagnostics, anime integration, and conversational AI assistant. iOS/Android/Web.","archived":false,"fork":false,"pushed_at":"2025-12-18T16:43:32.000Z","size":6821,"stargazers_count":2,"open_issues_count":6,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-21T20:34:18.741Z","etag":null,"topics":["adguard-home","ai-assistant","animehub","arr-suite","expo","homelab","jellyfin","jellyseerr","media-management","media-server","myanimelist","prowlarr","qbittorrent","radarr","react-native","s3-backup","selfhosted","sonarr","vercel-ai-sdk","widgets"],"latest_commit_sha":null,"homepage":"https://github.com/raulshma/uniarr","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/raulshma.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-05T08:19:11.000Z","updated_at":"2025-12-04T12:10:34.000Z","dependencies_parsed_at":"2025-10-19T10:29:34.014Z","dependency_job_id":"e69e12f7-4e51-452e-9af5-cc0458460a34","html_url":"https://github.com/raulshma/uniarr","commit_stats":null,"previous_names":["raulshma/uniarr"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/raulshma/uniarr","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raulshma%2Funiarr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raulshma%2Funiarr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raulshma%2Funiarr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raulshma%2Funiarr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/raulshma","download_url":"https://codeload.github.com/raulshma/uniarr/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raulshma%2Funiarr/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28478049,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T06:30:42.265Z","status":"ssl_error","status_checked_at":"2026-01-16T06:30:16.248Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adguard-home","ai-assistant","animehub","arr-suite","expo","homelab","jellyfin","jellyseerr","media-management","media-server","myanimelist","prowlarr","qbittorrent","radarr","react-native","s3-backup","selfhosted","sonarr","vercel-ai-sdk","widgets"],"created_at":"2026-01-16T09:52:54.312Z","updated_at":"2026-01-16T09:52:54.402Z","avatar_url":"https://github.com/raulshma.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# UniArr\n\n[![Version](https://img.shields.io/badge/version-0.1.0-blue.svg)](package.json)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Expo SDK](https://img.shields.io/badge/Expo%20SDK-54-000.svg)](https://expo.dev/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-Strict-blue.svg)](https://www.typescriptlang.org/)\n\nUniArr consolidates your media tooling into a single mobile app. Using connector implementations and secure storage, it lets you discover, manage, and sync releases across services while supporting offline workflows and robust diagnostics. Ideal for power users who run self-hosted media stacks and want a polished, mobile-first control surface.\n\n## Overview\n\nUniArr provides a comprehensive, unified interface for managing all your media automation and management services from a single mobile application. With support for 12+ implemented connectors (and a few planned/referenced services), including Sonarr, Radarr, Jellyseerr, qBittorrent, Jellyfin, and more, it offers advanced features like multi-service data aggregation, intelligent caching, offline support, and a sophisticated widget system.\n\n## Core Features\n\n### Media Management Hub\n\n- **Multi-Service Integration**: Native support for 15+ media services:\n  - **Media Managers**: Sonarr (TV), Radarr (Movies), Lidarr (Music), Jellyseerr (Requests)\n  - **Download Clients**: qBittorrent, Transmission, Deluge, SABnzbd\n  - **Supporting Services**: Prowlarr (Indexer), Bazarr (Subtitles), Jellyfin (Media Server), AdGuard Home (DNS/Ad-blocking)\n  - **External APIs**: The Movie Database (TMDb) integration for movie/TV discovery and metadata\n- **Unified Search**: Cross-service search with intelligent deduplication and filtering\n- **Release Calendar**: Comprehensive calendar merging releases from all Sonarr/Radarr instances with multiple view modes (Month, Week, Day, List)\n- **Anime Integration**: MyAnimeList (Jikan) integration with detailed anime information and tracking\n- **Download Management**: Centralized download queue management with progress tracking and remote control capabilities\n- **Media Editor**: Advanced media metadata editing with multi-source ratings\n- **Content Ranking**: Intelligent release quality scoring and ranking system\n\n### Advanced User Interface\n\n- **Dynamic Widget System**: 15+ customizable widgets including:\n  - **Bookmarks Widget**: Custom navigation shortcuts with health monitoring and icon picker\n  - **Weather Widget**: Animated weather gradients with real-time updates and location services\n  - **Service Status Widget**: Real-time service monitoring with health checks\n  - **Download Progress Widget**: Active download tracking with queue management\n  - **Calendar Preview Widget**: Upcoming releases preview with statistics\n  - **Statistics Widget**: Overview metrics aggregation and analytics\n  - **Social Media Widgets**: Reddit, Twitch, YouTube, Hacker News integration\n  - **RSS Feed Widget**: RSS feed reader with custom sources\n  - **Recent Activity Widget**: Activity feed across all services\n  - **Shortcuts Widget**: Quick access to common actions and navigation\n- **Sophisticated Theming**: Custom MD3 themes with multiple presets (UniArr, Netflix, Disney+, Max, etc.)\n- **Dark/Light Modes**: Full theme support with OLED optimization for power efficiency\n- **Frosted Glass Effects**: Animated UI elements with native blur and transparency effects\n- **Responsive Design**: Adaptive layouts for phones, tablets, and web platforms\n- **Custom Navigation**: Curved tab bar with advanced navigation patterns\n- **Modal System**: Advanced modal management with contextual interactions\n\n### Network \u0026 Connectivity\n\n- **VPN Diagnostics**: Advanced VPN detection and troubleshooting with connection testing\n- **Network Scanner**: Auto-discovery of services on local network with intelligent detection\n- **Offline-First Architecture**: Full offline functionality with intelligent synchronization and mutation queuing\n- **Connection Health**: Real-time service status monitoring with automatic recovery\n- **Network-Aware Updates**: Battery-conscious refresh intervals (5-120 minutes) based on data type\n- **AdGuard Home Integration**: Advanced DNS blocking with query log management, protection status monitoring, and filter refresh capabilities\n- **Network History**: Recent IP addresses and connection history tracking\n\n### Technical Excellence\n\n- **TypeScript Strict Mode**: Complete type safety with comprehensive coverage\n- **Performance Optimized**: React Compiler integration, FlashList for high-performance scrolling, and aggressive caching\n- **Multi-Layer Caching**: Sophisticated image caching with memory/disk optimization and authenticated requests\n- **Error Boundaries**: Comprehensive error handling and recovery mechanisms\n- **State Management**: TanStack Query for server state + Zustand for client state with offline support\n- **MMKV Storage**: High-performance storage backend with ~30x faster operations than AsyncStorage and automatic fallback\n- **Image Cache Intelligence**: Smart prefetching with concurrent background processing and automatic cleanup\n- **Mutation Queue Service**: Offline mutation queuing with intelligent synchronization and retry mechanisms\n- **Thumbhash Integration**: Blur hash placeholders for better user experience during image loading\n\n### Authentication \u0026 Security\n\n- **Clerk Authentication**: Complete end-user authentication with social providers and secure token management\n- **Multi-Provider Service Auth**: Support for API keys, basic authentication, session-based authentication, and OAuth\n- **Secure Storage**: Hardware-backed encrypted credential storage using Expo SecureStore\n- **ServiceAuthHelper**: Unified authentication abstraction with automatic token refresh\n- **Permission Management**: Fine-grained permission control for app features and services\n- **Authentication Providers**: Specialized providers for different service types (Jellyfin, API Key, Basic Auth, Session-based)\n\n### Voice Assistant \u0026 AI Integration\n\n- **Siri \u0026 Google Assistant Integration**: Native voice shortcuts with iOS Siri and Android Google Assistant support\n- **Natural Language Processing**: Advanced voice command recognition for media search, service status, and download management\n- **Voice Shortcut Customization**: Create custom voice commands for navigation and service actions\n- **Platform-Specific Voice Features**: Siri shortcuts on iOS, App Actions on Android with cross-platform compatibility\n- **Voice Feedback System**: Optional voice responses for accessibility and hands-free operation\n\n### Advanced Notification System\n\n- **Webhook Integration**: Full webhook processing with signature verification, event queuing, and notification management\n- **Smart Notification Management**: Type-based notification filtering with quiet hours and do-not-disturb modes\n- **Interactive Notifications**: Actionable notifications with buttons for immediate response to events\n- **Notification History**: Persistent notification history with read/unread tracking and search capabilities\n- **Push Notification Support**: Local and remote notification handling with delivery tracking\n\n### Advanced Backup \u0026 Recovery\n\n- **Comprehensive Backup System**: Full application state backup/restore with granular selection options\n- **Encrypted Backups**: AES-256 encryption with password protection for sensitive data\n- **Selective Backup Options**: Choose exactly what to backup - settings, services, widgets, credentials, network history\n- **Cross-Platform Restore**: Seamless restore across iOS, Android, and Web platforms\n- **Backup Profiles**: Save multiple backup configurations for different use cases\n- **Cloud Integration**: Export backups to cloud storage with automatic scheduling\n\n### Analytics \u0026 Monitoring\n\n- **Comprehensive Analytics Dashboard**: Detailed statistics for library growth, download performance, and usage patterns\n- **Service Health Monitoring**: Real-time service status tracking with automatic failure detection and recovery\n- **Performance Metrics**: Battery usage monitoring, network performance tracking, and cache optimization statistics\n- **Activity Timeline**: Chronological activity tracking with service-specific event logging\n- **Usage Analytics**: User behavior analysis with feature usage statistics and optimization suggestions\n- **Quality Profile Distribution**: Content quality analysis across different media types\n- **Library Growth Tracking**: Historical data for media library expansion and trends\n- **Download Statistics**: Comprehensive download performance analysis with success rates and speeds\n- **Request Analytics**: Jellyseerr request tracking and approval rate analysis\n- **Indexer Performance**: Prowlarr indexer effectiveness and performance metrics\n- **Activity Time Analysis**: Usage pattern analysis with peak activity time tracking\n\n### App Management \u0026 Utilities\n\n- **App Update Service**: Automatic update checking with GitHub integration and version tracking\n- **Widget Drawer System**: Global widget management with profile-based configurations\n- **Haptic Feedback System**: 9+ different haptic feedback types for enhanced user interaction\n- **File Sharing Integration**: Native file system integration with document picker and sharing capabilities\n- **Location Services**: Device location tracking with caching for weather and location-based features\n- **Dialog System**: Theme-aware dialog system with programmatic API for alerts and confirmations\n- **Homarr Icons Integration**: Icon management with CDN caching and extensive icon library\n- **Video Player**: Native video playback support for media content\n\n### Experimental Features \u0026 Debug Tools\n\n- **Feature Flag System**: Controlled rollout of experimental features with user opt-in options\n- **Debug Panel**: Comprehensive debugging interface with network logs, cache statistics, and system diagnostics\n- **Performance Monitoring**: Real-time performance tracking with FPS monitoring, memory usage, and network latency\n- **Network Diagnostics**: Advanced connection testing with VPN detection and troubleshooting guidance\n- **Developer Tools**: Debug logging, performance profiling, and system status monitoring\n\n## Screenshots\n\n\u003cimg width=\"300\" height=\"520\" alt=\"Screenshot_20251023-011701\" src=\"https://github.com/user-attachments/assets/fb0d9ddf-1011-46b6-86df-663c503770f4\" /\u003e\n\u003cimg width=\"300\" height=\"520\" alt=\"Screenshot_20251023-011614\" src=\"https://github.com/user-attachments/assets/b1fae191-6edf-4736-b8a1-d0556376713c\" /\u003e\n\u003cimg width=\"300\" height=\"520\" alt=\"Screenshot_20251023-011402\" src=\"https://github.com/user-attachments/assets/92ca0ba6-a191-493b-9f79-75b4d217ee04\" /\u003e\n\u003cimg width=\"300\" height=\"520\" alt=\"Screenshot_20251023-011352\" src=\"https://github.com/user-attachments/assets/9e31fd6c-9760-421f-8c4b-d5cab7afd6b6\" /\u003e\n\u003cimg width=\"300\" height=\"520\" alt=\"Screenshot_20251023-011325\" src=\"https://github.com/user-attachments/assets/f99d87ec-044e-488e-b8af-d8f675e82260\" /\u003e\n\u003cimg width=\"300\" height=\"520\" alt=\"Screenshot_20251023-011315\" src=\"https://github.com/user-attachments/assets/df221e25-42fe-4f9e-9db8-5c0706774a0b\" /\u003e\n\u003cimg width=\"300\" height=\"520\" alt=\"Screenshot_20251023-011236\" src=\"https://github.com/user-attachments/assets/6513d9ba-7db4-4268-aa94-56f0c2fa5b62\" /\u003e\n\u003cimg width=\"300\" height=\"520\" alt=\"Screenshot_20251023-012213\" src=\"https://github.com/user-attachments/assets/ff0f1f70-9c7f-4c5c-9cab-140ad76db278\" /\u003e\n\u003cimg width=\"300\" height=\"520\" alt=\"Screenshot_20251023-012202\" src=\"https://github.com/user-attachments/assets/90a13200-5b78-4329-b203-8be7bb490a85\" /\u003e\n\u003cimg width=\"300\" height=\"520\" alt=\"Screenshot_20251023-012147\" src=\"https://github.com/user-attachments/assets/6b20a262-44c1-4531-a9cd-f5514ccba264\" /\u003e\n\u003cimg width=\"300\" height=\"520\" alt=\"Screenshot_20251023-012014\" src=\"https://github.com/user-attachments/assets/ff95d037-70a5-47d3-a844-5398d22e2799\" /\u003e\n\u003cimg width=\"300\" height=\"520\" alt=\"Screenshot_20251023-011953\" src=\"https://github.com/user-attachments/assets/c026d302-0bb4-487f-a2c6-b31c5619690d\" /\u003e\n\u003cimg width=\"300\" height=\"520\" alt=\"Screenshot_20251023-011935\" src=\"https://github.com/user-attachments/assets/10e1df07-967c-424e-ba1e-ab1f0dbdb136\" /\u003e\n\u003cimg width=\"300\" height=\"520\" alt=\"Screenshot_20251023-011906\" src=\"https://github.com/user-attachments/assets/37c5d2b7-032b-41f3-a322-79d99beee6ea\" /\u003e\n\u003cimg width=\"300\" height=\"520\" alt=\"Screenshot_20251023-011851\" src=\"https://github.com/user-attachments/assets/a500be6a-b7bd-4274-aca7-524b9ce0cc09\" /\u003e\n\u003cimg width=\"300\" height=\"520\" alt=\"Screenshot_20251023-011832\" src=\"https://github.com/user-attachments/assets/ff554f6b-8ca6-499f-ba3c-0ff7e1e7a047\" /\u003e\n\n## Requirements\n\n- Node.js 18+\n- Expo CLI (`npm install -g @expo/cli`)\n- iOS: Xcode 14+ (for iOS development)\n- Android: Android Studio with Android SDK (for Android development)\n- Media services: Sonarr, Radarr, Jellyseerr, qBittorrent, etc.\n\n## Installation\n\n### Clone the repository\n\n```bash\ngit clone https://github.com/yourusername/uniarr.git\ncd uniarr\n```\n\n### Install dependencies\n\n```bash\nnpm install\n```\n\n### Configure Clerk Authentication\n\n1. Create a [Clerk](https://clerk.com/) account\n2. Set up your application and obtain the publishable key\n3. Configure the key in your environment\n\n### Start the development server\n\n```bash\n# Start Expo development server\nnpm start\n\n# Run on iOS\nnpm run ios\n\n# Run on Android\nnpm run android\n\n# Run on web\nnpm run web\n```\n\n## Development\n\n### Prerequisites\n\n- **Node.js 18+** - Latest LTS version recommended\n- **Expo CLI** - `npm install -g @expo/cli`\n- **Platform Dependencies**:\n  - **iOS**: Xcode 14+ and iOS Simulator\n  - **Android**: Android Studio with Android SDK\n  - **Web**: Modern web browser\n- **Media Services**: At least one supported service (Sonarr, Radarr, qBittorrent, etc.)\n\n### Quick Start\n\n#### 1. Clone and Install\n\n```bash\ngit clone https://github.com/yourusername/uniarr.git\ncd uniarr\nnpm install\n```\n\n#### 2. Configure Authentication\n\n```bash\n# Create a Clerk account at https://clerk.com\n# Set your publishable key in environment variables\necho \"EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY=your_key_here\" \u003e .env\n```\n\n#### 3. Start Development\n\n```bash\n# Start the Expo development server\nnpm start\n\n# Scan QR code with Expo Go app or run on specific platforms:\nnpm run ios          # iOS Simulator\nnpm run android      # Android Emulator\nnpm run web          # Web browser\n```\n\n### Available Scripts\n\n```bash\n# Development\nnpm start            # Start Expo development server\nnpm run ios          # Run on iOS Simulator\nnpm run android      # Run on Android Emulator\nnpm run web          # Run in web browser\n\n# Code Quality\nnpm run lint         # ESLint and Prettier\nnpm run typecheck    # TypeScript type checking\nnpm test             # Run Jest tests\nnpm run test:watch   # Run tests in watch mode\n\n# Code Generation\nnpm run generate:client-schemas    # Generate OpenAPI TypeScript schemas\n\n# Build \u0026 Deploy\nnpm run build        # Production build\nnpx eas build        # EAS application service build\nnpx eas submit       # Submit to app stores\n```\n\n### Development Environment\n\n#### **Code Quality Tools**\n\n- **TypeScript Strict Mode** - Complete type safety with `noImplicitAny`\n- **ESLint + React Compiler** - Code quality with performance optimization hints\n- **Prettier** - Consistent code formatting with automatic integration\n- **Husky + lint-staged** - Pre-commit hooks for quality assurance\n\n#### **Testing Infrastructure**\n\n- **Jest** - Unit testing framework with React Native support\n- **React Native Testing Library** - Component testing utilities\n- **Detox** - End-to-end testing for critical user flows\n- **Connector Mocks** - Comprehensive service mocking patterns\n- **Integration Testing** - Multi-service flow testing with real-world scenarios\n- **Storage Testing** - MMKV and AsyncStorage testing with migration scenarios\n- **Widget Testing** - Component testing for all widget types and configurations\n- **Service Testing** - End-to-end testing for all 15+ service connectors\n\n#### **Development Features**\n\n- **Hot Reloading** - Instant code updates during development\n- **Fast Refresh** - Component state preservation during updates\n- **React DevTools** - Component inspection and debugging\n- **Flipper** - Advanced debugging and performance profiling\n\n### Configuration\n\n#### **Environment Variables**\n\n```bash\n# Required\nEXPO_PUBLIC_CLERK_PUBLISHABLE_KEY=your_clerk_key\n\n# Optional\nEXPO_PUBLIC_API_BASE_URL=https://your-api.example.com\nEXPO_PUBLIC_LOG_LEVEL=info\nEXPO_PUBLIC_DEBUG_MODE=false\n```\n\n#### **Service Configuration**\n\nServices are configured through the app settings screen:\n\n1. Navigate to Settings → Services\n2. Add service configuration (URL, authentication)\n3. Test connection for validation\n4. Enable/disable services as needed\n\n#### **Platform-Specific Setup**\n\n**iOS Development:**\n\n```bash\n# Install additional dependencies\nnpx pod-install ios\n\n# Run on iOS Simulator\nnpm run ios\n```\n\n**Android Development:**\n\n```bash\n# Ensure Android SDK is configured\n# Run on Android Emulator or connected device\nnpm run android\n```\n\n**Web Development:**\n\n```bash\n# Run in web browser with live reload\nnpm run web\n```\n\n## Architecture Overview\n\n### System Architecture\n\nUniArr employs a sophisticated multi-layered architecture designed for scalability, maintainability, and exceptional mobile performance:\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                    Presentation Layer                        │\n│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │\n│  │   UI Components │  │   Screens/Layout│  │   Widget System │ │\n│  │   (React Native)│  │  (Expo Router)  │  │ (Dynamic Widgets)│ │\n│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │\n└─────────────────────────────────────────────────────────────┘\n                                │\n┌─────────────────────────────────────────────────────────────┐\n│                    Business Logic Layer                     │\n│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │\n│  │ Custom Hooks    │  │ Service Layer   │  │ State Management │ │\n│  │ (useCalendar,   │  │ (API services,  │  │ (TanStack Query,│ │\n│  │ useSearch, etc.)│  │ ImageCache, etc)│  │  Zustand stores) │ │\n│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │\n└─────────────────────────────────────────────────────────────┘\n                                │\n┌─────────────────────────────────────────────────────────────┐\n│                  Integration Layer                          │\n│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │\n│  │ Service Connectors│ │ Auth Management │  │ Offline Support │ │\n│  │ (BaseConnector,  │  │  (Clerk +       │  │ (Mutation Queue, │ │\n│  │ 15+ services)    │  │ ServiceAuth)    │  │ Network Sync)   │ │\n│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │\n└─────────────────────────────────────────────────────────────┘\n                                │\n┌─────────────────────────────────────────────────────────────┐\n│                    Data Layer                               │\n│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │\n│  │ External APIs   │  │ Local Storage   │  │ Cache Layer     │ │\n│  │ (Sonarr, Radarr,│  │ (SecureStorage, │  │ (Image Cache,   │ │\n│  │  qBittorrent)   │  │  AsyncStorage)  │  │ Query Cache)    │ │\n│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### Project Structure\n\n```\nuniarr/\n├── app/                           # Expo Router file-based routing\n│   ├── (auth)/                   # Protected routes (Clerk auth)\n│   │   ├── (tabs)/              # Main navigation tabs\n│   │   │   ├── dashboard/       # Overview dashboard\n│   │   │   ├── services/        # Service management\n│   │   │   ├── recently-added/  # Recent media activity\n│   │   │   ├── downloads/       # Download management\n│   │   │   └── settings/        # App configuration\n│   │   └── [screens]/           # Individual protected screens\n│   ├── (public)/                # Public routes (login, signup)\n│   └── _layout.tsx              # Root layout with providers\n├── src/\n│   ├── components/              # Reusable UI components\n│   │   ├── widgets/            # Dynamic widget system (15+ widget types)\n│   │   │   ├── BookmarksWidget/\n│   │   │   ├── WeatherWidget/\n│   │   │   ├── ServiceStatusWidget/\n│   │   │   ├── DownloadProgressWidget/\n│   │   │   ├── CalendarPreviewWidget/\n│   │   │   ├── StatisticsWidget/\n│   │   │   ├── RedditWidget/\n│   │   │   ├── TwitchWidget/\n│   │   │   ├── YouTubeWidget/\n│   │   │   ├── HackerNewsWidget/\n│   │   │   ├── RssWidget/\n│   │   │   └── ...\n│   │   ├── calendar/           # Multi-service calendar\n│   │   ├── search/             # Unified search components\n│   │   └── common/             # Shared UI components\n│   ├── connectors/              # Service integration layer\n│   │   ├── implementations/    # 15+ service connectors\n│   │   ├── openapi-specs/      # External API specifications\n│   │   └── client-schemas/     # Generated TypeScript schemas\n│   ├── hooks/                   # Custom React hooks\n│   │   ├── queryKeys.ts        # Hierarchical query key factory\n│   │   └── queryConfig.ts      # Query configuration presets\n│   ├── services/               # Business logic services\n│   │   ├── analytics/          # Analytics and metrics\n│   │   ├── auth/               # Authentication management\n│   │   ├── backup/             # Backup/restore functionality\n│   │   ├── calendar/           # Calendar aggregation service\n│   │   ├── dialogService.ts    # Theme-aware dialog system\n│   │   ├── download/           # Download management\n│   │   ├── haptic/             # Haptic feedback system\n│   │   ├── image/              # Image caching and processing\n│   │   ├── location/           # Location services\n│   │   ├── network/            # Network diagnostics \u0026 VPN\n│   │   ├── notifications/      # Push notification system\n│   │   ├── search/             # Unified search service\n│   │   ├── storage/            # Storage abstraction (MMKV/AsyncStorage)\n│   │   ├── voice/              # Voice assistant integration\n│   │   ├── webhooks/           # Webhook processing\n│   │   ├── widgets/            # Widget data providers\n│   │   └── ...\n│   ├── store/                   # Zustand state management\n│   │   ├── connectorsStore.ts  # Service connector management\n│   │   ├── settingsStore.ts    # User preferences\n│   │   ├── downloadStore.ts    # Download queue state\n│   │   └── ...\n│   ├── models/                  # TypeScript type definitions\n│   ├── utils/                   # Utility functions \u0026 helpers\n│   └── constants/               # App constants and theme config\n├── __tests__/                    # Test suites\n│   ├── connectors/              # Connector unit tests\n│   ├── integration/             # Multi-service integration tests\n│   └── mocks/                   # Service and component mocks\n└── scripts/                     # Build and generation scripts\n```\n\n### Technology Stack\n\n#### **Core Framework**\n\n- **React Native 0.81.4** with React 19.1.0 - Latest native mobile framework\n- **Expo SDK 54** - Complete development platform with managed workflow\n- **Expo Router** - File-based routing with automatic TypeScript support\n- **TypeScript 5.x** - Strict mode with comprehensive type coverage\n\n#### **UI \u0026 Theming**\n\n- **React Native Paper (MD3)** - Material Design 3 component library\n- **React Native Reanimated 3** - High-performance animations and gestures\n- **React Native Gesture Handler** - Advanced gesture recognition\n- **Expo Image** - Optimized image loading with caching\n- **Custom Theme System** - Dynamic theming with OLED optimization\n\n#### **State Management \u0026 Data**\n\n- **TanStack Query v5** - Server state management with offline support\n- **Zustand** - Lightweight client state management with persistence\n- **Expo SecureStore** - Encrypted credential storage\n- **AsyncStorage** - Local data persistence with migration support\n\n#### **Authentication \u0026 Security**\n\n- **Clerk Expo** - Complete authentication solution with social providers\n- **Expo SecureStore** - Hardware-backed secure storage\n- **ServiceAuthHelper** - Multi-provider authentication abstraction\n\n#### **Development \u0026 Tooling**\n\n- **ESLint with React Compiler** - Code quality with optimization hints\n- **Prettier** - Consistent code formatting\n- **Husky + lint-staged** - Pre-commit quality gates\n- **Jest + React Native Testing Library** - Comprehensive testing\n- **Detox** - End-to-end testing for critical user flows\n\n#### **OpenAPI Integration \u0026 Schema Generation**\n\n- **Local API Specifications**: OpenAPI specs stored in `src/connectors/openapi-specs/` for each external service\n- **Automatic Schema Generation**: TypeScript types generated via `npm run generate:client-schemas` command\n- **Client Stub Generation**: Automatic client stubs using `openapi-typescript` and `openapi-fetch`\n- **Multi-Spec Support**: Handles both YAML and JSON OpenAPI specifications\n- **Schema Validation**: Ensures compatibility with service APIs through generated types\n- **OperationId Deduplication**: Automatic handling of duplicate operation identifiers across services\n\n### Service Connector Architecture\n\nThe application's service integration follows a sophisticated connector pattern:\n\n#### **BaseConnector Pattern**\n\n```typescript\nabstract class BaseConnector {\n  protected auth: ServiceAuthHelper;\n  protected logger: LoggerService;\n\n  abstract initialize(): Promise\u003cvoid\u003e;\n  abstract testConnection(): Promise\u003cConnectionResult\u003e;\n  abstract getVersion(): Promise\u003cstring\u003e;\n}\n```\n\n#### **Supported Services**\n\n| Service Type            | Services                                 | Capabilities                           |\n| ----------------------- | ---------------------------------------- | -------------------------------------- |\n| **Media Managers**      | Sonarr, Radarr, Lidarr, Jellyseerr       | Search, Metadata, Monitoring           |\n| **Download Clients**    | qBittorrent, Transmission, Deluge        | Download Management, Remote Control    |\n| **NZB Clients**         | SABnzbd                                  | NZB Download Management                |\n| **Supporting Services** | Prowlarr, Bazarr, Jellyfin, AdGuard Home | Indexing, Subtitles, Media Server, DNS |\n\n#### **Key Features**\n\n- **Automatic Authentication** - Support for API keys, basic auth, and session-based authentication\n- **Retry Mechanisms** - Exponential backoff with network-aware retry conditions\n- **Comprehensive Error Handling** - Structured error feedback with VPN-specific diagnostics\n- **OpenAPI Integration** - Automatic client schema generation from service specifications\n- **Connection Health Monitoring** - Real-time service status with automatic recovery\n\n### Advanced Widget System\n\n#### **Widget Architecture**\n\nThe widget system provides runtime-configurable dashboard components:\n\n```typescript\ninterface WidgetConfig {\n  id: string;\n  type: WidgetType;\n  instanceId: string;\n  config: Record\u003cstring, any\u003e;\n  position: WidgetPosition;\n}\n```\n\n#### **Available Widget Types**\n\n- **BookmarksWidget** - Custom navigation shortcuts with icon picker\n- **WeatherWidget** - Animated weather with gradient backgrounds\n- **ServiceStatusWidget** - Real-time service health monitoring\n- **DownloadProgressWidget** - Active download tracking\n- **CalendarPreviewWidget** - Upcoming releases preview\n- **StatisticsWidget** - Media library statistics\n- **RssWidget** - RSS feed consumption\n- **Social Widgets** - Reddit, Twitch, YouTube, Hacker News integration\n\n#### **Widget Features**\n\n- **Dynamic Configuration** - Runtime widget creation and configuration\n- **Per-Instance Settings** - Individual configuration for each widget instance\n- **Global Widget Drawer** - Contextual access to all widgets\n- **Animated Transitions** - Smooth enter/exit animations with spring physics\n- **Responsive Layouts** - Adaptive sizing and positioning\n\n### Performance Optimization\n\n#### **Image Caching System**\n\n- **Multi-Layer Caching** - Expo Image cache + direct download fallback\n- **Smart Prefetching** - Concurrent background processing with configurable limits\n- **Memory Management** - Automatic cleanup with size and age-based eviction\n- **Authenticated Requests** - Automatic API key injection for protected images\n\n#### **Network Optimization**\n\n- **Battery-Aware Updates** - Configurable refresh intervals (5-120 minutes)\n- **Offline-First Architecture** - Mutation queuing and intelligent synchronization\n- **Request Deduplication** - Automatic duplicate request prevention\n- **VPN-Aware Behavior** - Special handling for VPN connectivity issues\n\n#### **Rendering Performance**\n\n- **FlashList Integration** - High-performance list rendering for large datasets\n- **React Compiler** - Experimental optimization with performance hints\n- **Component Memoization** - Strategic use of React.memo and useMemo\n- **Lazy Loading** - Progressive loading of images and components\n\n## Contributing\n\nWe welcome contributions from the community! UniArr is a complex project with many moving parts, and we appreciate any help improving it.\n\n### How to Contribute\n\n#### **1. Fork and Clone**\n\n```bash\ngit clone https://github.com/yourusername/uniarr.git\ncd uniarr\n```\n\n#### **2. Create a Feature Branch**\n\n```bash\ngit checkout -b feature/your-feature-name\n```\n\n#### **3. Development Workflow**\n\n- Follow the existing code patterns and architecture\n- Use TypeScript strict mode - no `any` types allowed\n- Add comprehensive JSDoc comments for complex functions\n- Ensure all linting and type checks pass before committing\n\n#### **4. Testing**\n\n- Add tests for new functionality using existing patterns\n- Test with multiple service configurations when applicable\n- Verify offline behavior and error handling\n- Test on iOS, Android, and Web platforms when possible\n\n#### **5. Submit Your Contribution**\n\n```bash\ngit commit -m \"feat: add your feature description\"\ngit push origin feature/your-feature-name\n# Open a Pull Request with detailed description\n```\n\n### Development Guidelines\n\n#### **Code Standards**\n\n- **TypeScript Strict Mode**: All code must pass strict type checking\n- **Component Patterns**: Follow existing component structure and prop patterns\n- **Service Integration**: Use the BaseConnector pattern for new services\n- **State Management**: Use TanStack Query for server state, Zustand for client state\n- **Error Handling**: Implement comprehensive error boundaries and user feedback\n\n#### **Adding New Services**\n\n1. **Create Connector**: Extend `BaseConnector` in `src/connectors/implementations/`\n2. **Register Service**: Add to `ConnectorFactory.connectorRegistry`\n3. **Add Types**: Include service types in `src/models/`\n4. **Test Integration**: Add service-specific tests following existing patterns\n5. **Update Documentation**: Document service capabilities and configuration\n\n#### **UI/UX Guidelines**\n\n- **Theme Awareness**: All components must use `useTheme()` from React Native Paper\n- **Responsive Design**: Ensure layouts work on phones, tablets, and web\n- **Accessibility**: Include accessibility labels and screen reader support\n- **Performance**: Use FlashList for large datasets, implement lazy loading\n- **Animations**: Use Reanimated for smooth, 60fps animations\n- **Haptic Feedback**: Use HapticService for consistent tactile interactions\n- **Frosted Glass Effects**: Implement blur effects using theme-aware glassmorphism patterns\n- **Widget Development**: Follow widget container patterns and configuration forms\n\n#### **Development Workflow**\n\n```bash\n# Before committing, ensure all checks pass\nnpm run lint          # Code formatting and linting\nnpm run typecheck     # TypeScript strict mode checking\nnpm test              # Run all tests\n\n# For service integrations\nnpm run generate:client-schemas  # Generate OpenAPI types if needed\n```\n\n### Areas for Contribution\n\n#### High Priority\n\n- **Additional Service Connectors**: Expand support for more media management tools (currently 15+ supported)\n- **Additional Service Connectors**: Expand support for more media management tools (currently 12+ implemented; additional connectors such as NZBGet and rTorrent are referenced in the codebase but not registered in `ConnectorFactory` yet)\n- **Enhanced Error Handling**: Improve error reporting and user feedback with better diagnostics\n- **Performance Optimizations**: Battery life improvements and memory usage optimization\n- **Test Coverage**: Expand test suites for better reliability (currently comprehensive unit + integration tests)\n- **Voice Assistant Expansion**: Enhance Siri/Google Assistant integration with NLP improvements\n- **Backup System Enhancement**: Cloud integration and automated backup scheduling\n- **Analytics Dashboard**: Expand analytics capabilities with custom metrics and reporting\n\n#### UI/UX Improvements\n\n- **Widget Development**: Create new widget types and configurations (currently 13 types available)\n- **Theme Enhancements**: Develop additional theme presets (currently 6+ presets including Netflix, Disney+, Max)\n- **Animation Polish**: Improve transitions and micro-interactions using Reanimated 3\n- **Haptic Feedback**: Expand haptic feedback system with 9+ feedback types\n- **Frosted Glass Effects**: Enhance glassmorphism effects and blur implementations\n- **Accessibility**: Enhanced screen reader support and accessibility features\n\n#### Platform Features\n\n- **Voice Assistant Integration**: Expand Siri/Google Assistant command recognition and NLP capabilities\n- **Webhook System**: Enhanced webhook processing with more event types and integrations\n- **Notification System**: Advanced push notifications with rich media and interactive actions\n- **Backup/Restore**: Enhanced backup encryption and cloud integration\n- **Analytics Dashboard**: Expand analytics capabilities with custom metrics and reporting\n- **Localization**: Multi-language support implementation with RTL support\n\n#### Platform Support\n\n- **Desktop Applications**: Electron or Tauri desktop versions with full feature parity\n- **Watch Integration**: Wear OS or watchOS companion apps with glanceable widgets\n- **TV Apps**: Android TV or Apple TV applications with remote control support\n- **Web Enhancements**: PWA features, offline web support, and desktop web optimizations\n- **Cross-Platform Sync**: Real-time synchronization across all platforms\n\n#### Advanced Integrations\n\n- **Additional Service Connectors**: Expand support for more media management tools (currently 15+ services)\n- **Smart Home Integration**: Integration with HomeKit, Google Home, and Alexa\n- **Media Server Extensions**: Enhanced Jellyfin/Emby/Plex integration with transcoding controls\n- **Network Tools**: Advanced network monitoring and diagnostic capabilities\n- **API Extensions**: Public API for third-party integrations and automation\n\n#### Experimental Features\n\n- **AI-Powered Recommendations**: Machine learning for media recommendations and automation\n- **Advanced Analytics**: Predictive analytics for storage planning and usage patterns\n- **Performance Optimizations**: React Compiler optimizations and advanced caching strategies\n- **Security Enhancements**: Biometric authentication and advanced encryption methods\n- **Developer Tools**: Plugin system for custom extensions and third-party plugins\n\n### Code Review Process\n\n#### **Before Submitting PR**\n\n- [ ] All tests pass (`npm test`)\n- [ ] Type checking passes (`npm run typecheck`)\n- [ ] Linting passes (`npm run lint`)\n- [ ] Code is properly formatted\n- [ ] Documentation is updated\n- [ ] Breaking changes are documented\n\n#### **PR Guidelines**\n\n- Provide clear, concise descriptions of changes\n- Include screenshots for UI changes\n- Document any breaking changes or migration steps\n- Link to relevant issues or discussions\n- Ensure PR is focused and atomic\n\n### Community Guidelines\n\n#### **Getting Help**\n\n- **Discussions**: Use GitHub Discussions for questions and ideas\n- **Issues**: Report bugs with detailed reproduction steps\n- **Documentation**: Suggest improvements to existing documentation\n- **Code Review**: Participate in reviewing other contributors' PRs\n\n#### **Code of Conduct**\n\n- Be respectful and inclusive in all interactions\n- Provide constructive feedback and suggestions\n- Help newcomers learn the codebase and patterns\n- Focus on what's best for the community and project\n\n### Recognition\n\nContributors are recognized in:\n\n- **README.md**: Contributors section with acknowledgments\n- **Release Notes**: Credits for new features and improvements\n- **Commit Messages**: Proper attribution for all contributions\n- **Community**: Recognition in Discord/Slack communities\n\nThank you for contributing to UniArr!\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support \u0026 Getting Help\n\n### **Troubleshooting**\n\n#### **Common Issues**\n\n- **Connection Problems**: Check VPN diagnostics in Settings → Network\n- **Service Authentication**: Verify API keys and service URLs in Settings → Services\n- **Performance Issues**: Enable battery optimization and adjust refresh intervals\n- **Sync Problems**: Use Settings → Advanced → Force Sync to resynchronize data\n\n#### **Getting Help**\n\n1. **GitHub Issues**: [Report bugs and request features](https://github.com/yourusername/uniarr/issues)\n2. **GitHub Discussions**: [Ask questions and share ideas](https://github.com/yourusername/uniarr/discussions)\n3. **Documentation**: Check [CLAUDE.md](./CLAUDE.md) for development guidelines\n4. **Community**: Join our Discord/Slack communities (links in GitHub profile)\n\n### **Bug Reports**\n\nWhen reporting bugs, please include:\n\n- **Environment**: iOS/Android/Web version, app version\n- **Services Affected**: Which services are experiencing the issue\n- **Reproduction Steps**: Detailed steps to reproduce the problem\n- **Expected vs Actual**: What you expected vs what actually happened\n- **Logs**: Error messages or logs if available\n- **Network Info**: VPN status and connection details\n\n### **Feature Requests**\n\nWe love feature requests! Please include:\n\n- **Use Case**: Describe the problem you're trying to solve\n- **Proposed Solution**: How you envision the feature working\n- **Alternatives**: Any alternative solutions you've considered\n- **Priority**: How important this feature is to you\n\n## Acknowledgments\n\n### **Core Technologies \u0026 Frameworks**\n\n- **Expo Team** - For the incredible React Native development platform\n- **React Native Community** - For the amazing ecosystem and libraries\n- **TypeScript Team** - For making JavaScript development safe and enjoyable\n- **Meta (Facebook)** - For creating and maintaining React Native\n\n### **UI \u0026 Design**\n\n- **React Native Paper** - Beautiful Material Design 3 components\n- **React Navigation** - Powerful routing and navigation solutions\n- **React Native Reanimated** - Smooth 60fps animations and gestures\n\n### **Data \u0026 Services**\n\n- **The Movie Database (TMDB)** - Comprehensive movie and TV data\n- **MyAnimeList (Jikan API)** - Detailed anime information and tracking\n- **OpenAPI Initiative** - Standardized API specifications\n\n### **Media Management Services**\n\nSpecial thanks to all the open-source media management projects that make this app possible:\n\n- **Sonarr** - TV series management automation\n- **Radarr** - Movie collection management\n- **Jellyfin** - Free software media system\n- **qBittorrent** - Advanced torrent client\n- **Prowlarr** - Index manager for various services\n- **Bazarr** - Subtitle management\n- And all other supported services\n\n### **Development Tools**\n\n- **Microsoft** - TypeScript and VS Code\n- **GitHub** - Code hosting and collaboration platform\n- **Vercel** - Web hosting and deployment services\n- **ESLint \u0026 Prettier** - Code quality and formatting tools\n\n### **Community Contributors**\n\n- All the beta testers and early adopters\n- Contributors who report bugs and suggest improvements\n- The media management community for feedback and ideas\n- Open source developers who make this ecosystem possible\n\n---\n\n**Built with ❤️ for the media management community**\n\n_UniArr © 2025 - Unify your media automation experience_\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraulshma%2Funiarr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fraulshma%2Funiarr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraulshma%2Funiarr/lists"}