CleverFerret

Universal Media Library for Android
Manage books, music, movies, and more — all on your device

Features • Quick Start • Requirements • Documentation

---

📖 About

CleverFerret is a comprehensive, self-contained Android app for managing your complete media library directly on your device. No external servers or desktop applications required — everything works offline with a modern, Material You interface.

🎯 Key Features

• 📚 Universal Library - Books, comics, music, movies, podcasts in one place
• 📥 Calibre Import - Seamlessly import your existing Calibre library
• 🎨 Material You - Modern Android design with dynamic theming
• 💾 Local-First - All data stored on your device with Room database
• 🔧 Extensible - Architecture designed to support any media type

---

🚀 Quick Start

For Users

1. Download the latest APK from Releases
   • Choose CleverFerret-vX.X-release.apk for the optimized version
   • Or CleverFerret-vX.X-debug.apk for the debug version
2. Install following the instructions in docs/INSTALL.md
3. Verify the APK checksum (optional but recommended) - see installation guide
4. Launch the app and create your first library or import from Calibre

Note: CleverFerret is not yet available on Google Play Store. Direct APK installation is required.

For Developers

# Clone the repository
git clone https://github.com/Kaleaon/CleverFerret.git
cd CleverFerret

# Build the project
./gradlew clean assembleDebug

# Run tests
./gradlew testDebugUnitTest

See docs/DEVELOPMENT.md for complete setup instructions.

---

📱 System Requirements

• Android: 8.0+ (API level 26 or higher)
• Storage: 100 MB for app + space for your media
• RAM: 2GB minimum (4GB recommended)

---

🏗️ Architecture

CleverFerret uses modern Android development practices:

• Language: Kotlin
• UI: Jetpack Compose with Material 3
• Architecture: MVVM with Hilt dependency injection
• Database: Room (SQLite)
• Async: Kotlin Coroutines and Flow

See docs/ARCHITECTURE.md for detailed architecture information.

---

📚 Documentation

• Installation Guide - Installing the app on your device
• Development Guide - Building, testing, and contributing
• Architecture Guide - Technical architecture details
• Resources - External APIs, tools, and references
• Release Process - Creating and publishing releases
• Import Logic - Calibre import technical details

For a complete documentation index, see docs/README.md.

---

🤝 Contributing

We welcome contributions! Please read CONTRIBUTING.md for:

• Code style guidelines
• Development workflow
• Pull request process
• Issue reporting

---

📊 Project Status

CleverFerret is in active development. Current implementation status:

✅ Core database layer (Room)
✅ Calibre import functionality
✅ Modern Jetpack Compose UI
✅ Basic library management
⏳ Advanced metadata fetching
⏳ In-app media players
⏳ Multi-format support expansion

For detailed status and roadmap, see PROJECT_ROADMAP.md.

---

📝 License

This project is Free and Open Source Software (FOSS). See LICENSE for details.

---

🙏 Acknowledgments

Built with modern Android technologies and inspired by the best media management tools. Special thanks to the open source community for libraries and tools that make this possible.

---

_{Made with ❤️ for the Android community}