Arcile

An advanced, powerful, fast, and smooth Android file manager built with Kotlin and Material Design 3.

Important

Beta Status 🧪 Arcile is currently in Beta. Development has slowed down as i only get time on sundays now.

Note

Personal Project 🎯 Built to create a fast, clean, and modern file manager for Android — prioritizing smooth UX, Material You theming, and a native Kotlin-first approach.

---

✨ Features

Feature	Description
📂 Multi-Volume Support	Seamlessly manage Internal Storage, SD Cards, and USB OTG devices
🗂️ Breadcrumb Navigation	Visual path breadcrumbs with auto-scroll and tap-to-navigate
✅ Batch Operations	Multi-select files for copy, cut, move, or permanent delete
🎛️ Unified Browser Controls	Adjust sort order, list/grid mode, list zoom, and adaptive grid sizing from one expressive browser sheet
📊 Instant Folder Metadata	Browser folder rows show a subtitle immediately, then upgrade to best-effort file counts and total size in the background without flashing loading text
ℹ️ Selection Properties	Open a dedicated Properties dialog from the browser 3-dot selection menu for single or multi-select file and folder metadata
🛡️ Conflict Resolution	Intelligent handling of file conflicts (skip, overwrite, rename) during copy/move operations
🏠 Home Dashboard	Volume-scoped storage summary, category shortcuts, and recent files
🎨 Material You Theming	Dynamic wallpaper colors, custom accent colors, light/dark/OLED modes
🌈 Dynamic Colors	Powered by MaterialKolor for harmonious, accessible custom palettes
🌍 Localization Base	130+ string resources are already extracted, with a smaller set of remaining hardcoded strings.
🗑️ Trash Subsystem	Safely remove files with metadata-aware restoration
⚙️ Settings & About	Theme customization and comprehensive app information

---

🚀 Quick Start

Prerequisites

Tool	Version	Install
Android Studio	Latest (Ladybug+)	developer.android.com
JDK	11+	Bundled with Android Studio
Android SDK	API 36	Via SDK Manager

Setup

# Clone the repository
git clone https://github.com/qtremors/arcile.git

# Open in Android Studio
# File → Open → select the arcile-app directory

Or build from the command line (run from inside arcile-app/):

./gradlew assembleDebug

Install on a connected device:

  adb install app/build/outputs/apk/debug/Arcile-0.6.0-debug.apk

Release Signing

Release builds are signed using credentials stored in local.properties (not committed). To configure signing:

1. Generate a keystore (or use an existing one):

   keytool -genkeypair -v -keystore my-release-key.jks -keyalg RSA -keysize 2048 -validity 10000 -alias my-key-alias

2. Add the following to arcile-app/local.properties:

   signing.storeFile=/absolute/path/to/my-release-key.jks
   signing.storePassword=your_store_password
   signing.keyAlias=your_key_alias
   signing.keyPassword=your_key_password

3. Build the release APK:

   ./gradlew assembleRelease

Note: The app requires All Files Access (MANAGE_EXTERNAL_STORAGE) permission on Android 11+ for full file-system access.

---

🛠️ Tech Stack

Layer	Technology
Language	Kotlin 2.2.10
UI Framework	Jetpack Compose with Material 3
Architecture	MVVM (Feature-Scoped ViewModels + StateFlow) with Hilt DI
Navigation	Navigation Compose
Async	Kotlin Coroutines
Build System	Gradle (Kotlin DSL) with Version Catalogs
Min SDK	30 (Android 11.0)
Target SDK	36

---

📁 Project Structure

arcile/
├── arcile-app/                          # Android project root
│   ├── app/src/main/
│   │   ├── java/dev/qtremors/arcile/
│   │   │   ├── ArcileApp.kt             # Application class (Coil image loader, Hilt app)
│   │   │   ├── MainActivity.kt          # Entry point, permissions, nav shell
│   │   │   ├── data/                    # Repository Implementations
│   │   │   ├── di/                      # Dependency Injection (Hilt)
│   │   │   ├── domain/                  # Core Models & Repository Interfaces
│   │   │   ├── image/                   # Coil custom fetchers
│   │   │   ├── navigation/              # Route string constants
│   │   │   ├── presentation/            # Feature-Scoped ViewModels & UI
│   │   │   │   ├── browser/
│   │   │   │   ├── home/
│   │   │   │   ├── recentfiles/
│   │   │   │   ├── settings/
│   │   │   │   ├── trash/
│   │   │   │   └── ui/                  # Compose UI Screens & Components
│   │   │   ├── ui/theme/                # Theme, colors, typography, shapes
│   │   │   └── utils/                   # Formatting & color utilities
│   │   └── res/                         # Android resources
│   ├── build.gradle.kts
│   └── gradle/libs.versions.toml        # Version catalog
├── DEVELOPMENT.md                       # Developer documentation
├── CHANGELOG.md                         # Version history
├── TASKS.md                             # Audit findings and planned work
├── LICENSE.md
└── README.md

---

🧪 Testing

Run these commands from inside the arcile-app/ directory:

# Unit tests
./gradlew :app:testDebugUnitTest

# Instrumented tests (requires device/emulator)
./gradlew :app:connectedDebugAndroidTest

Note: The project includes an expanded layered JVM test suite covering domain logic, data-layer business rules, cached folder-stat behavior, ViewModel state machines, DataStore-backed browser preferences, and Robolectric-backed Compose browser/component tests.

---

📚 Documentation

Document	Description
DEVELOPMENT.md	Developer guide, architecture, and conventions
CHANGELOG.md	Version history and release notes
TASKS.md	Audit findings, planned features, and known issues
PRIVACY.md	Privacy policy
LICENSE.md	License terms and attribution

---

📄 License

Tremors Source License (TSL) - Source-available license allowing viewing, forking, and derivative works with mandatory attribution. Commercial use requires written permission.

Web Version: github.com/qtremors/license

See LICENSE.md for full terms.

---

Made with ❤️ by Tremors