Grid - Android Server File Browser

A modern Android application for browsing and managing files on remote servers through SFTP and SMB protocols. Built with Clean Architecture principles and the latest Android development technologies.

Current Status

✅ Working Features

• SMB/CIFS: Successfully connects to Windows shares and SMB servers with full file browsing
• SFTP: SSH File Transfer Protocol with secure authentication and full functionality
• File Browser: Complete file browser with list and grid view modes
• File Upload: Functional file upload with Material 3 expressive wavy progress indicators
• File Opening: Open text, image, PDF, audio, video, archive, code, and ebook files with built-in viewers (text editor with smooth keyboard scrolling, image viewer with pinch-to-zoom, PDF viewer with pinch-to-zoom, audio player, video player, archive viewer, code viewer with syntax highlighting, ebook viewer with chapter navigation)
• APK Install: Opening an .apk downloads it and hands it to the system installer, prompting once to allow Grid to install unknown apps if needed
• Archive Viewer: Browse and extract ZIP, RAR, 7-Zip, TAR, and GZIP archives with hierarchical tree navigation, file metadata display, and one-click extraction with progress tracking
• Offline Files: Every file you open, download or stream is kept once, in Downloads/Grid/<connection>/<server path>, and listed in Offline Files from there (no second copy). Audio and video save as they play, the player reading its own download; leaving playback lets the save finish in the background, and an interrupted one resumes next time
• System Integration: DocumentsProvider integration allows Grid to appear in other apps' file pickers for seamless file access. Each connection opens at its SFTP starting directory or SMB share; a picked file is read from its offline copy when there is one, and otherwise streamed to the app as it reads (Android 8+), resuming after a dropped connection, so uploads from other apps start at once instead of waiting for a full download
• PDF Viewer: Native PDF viewing with page navigation, enhanced text rendering, pinch-to-zoom, and pan support
• Ebook Viewer: Advanced EPUB ebook reader with HorizontalPager chapter navigation, swipe gestures, reading position persistence with scroll preservation, comprehensive text formatting (bold, italic, underline, strikethrough, superscript, subscript, code highlighting), working images with native rendering, and immersive reading experience with auto-hiding controls
• Markdown Viewer: Rich markdown rendering with proper formatting, headers, links, and theme-aware styling
• Code Viewer: Advanced code viewer with syntax highlighting for 20+ programming languages (Kotlin, Java, JavaScript, TypeScript, Python, C++, C, C#, Go, Rust, PHP, Ruby, Swift, Dart, HTML, CSS, XML, JSON, YAML, Shell, SQL), line numbers with overflow detection, language detection from file extensions, edit mode support, and theme-aware color schemes
• Audio Player: Enhanced audio player with responsive album art sizing, material color themes extracted from album art, metadata display (title, album, artist, year), wavy scrubbing progress bar with smooth animations, circular play button, auto-play functionality, and Android media notifications with monochrome app icon and seamless notification-to-app transitions
• Video Player: Custom video player with ExoPlayer integration, wavy progress bar scrubbing with pause animation control, auto-hiding controls, pinch-to-zoom support, and Android media notifications with monochrome app icon and seamless playback state preservation
• Animated GIFs: Full animated GIF support with automatic playback and pinch-to-zoom functionality
• File Downloads: Download selected files into their offline copies in Downloads/Grid, with batch support and real-time progress tracking
• Multi-Select: File selection mode with multi-select capabilities and batch operations (auto-exits on download start)
• File Operations: Delete, rename, and create directory functionality with proper SMB directory handling and recursive directory deletion for non-empty folders
• File Sorting: Sort files by name, type, or last modified date with session persistence
• Long Press: Enter selection mode with haptic feedback (works in both list and grid views)
• Path Display: Windows-style path formatting for SMB connections (\SHARENAME\PATH)
• Navigation: Home button for quick return to connections, back swipe gesture for directory navigation that stops at the connection's starting directory (SFTP) or share (SMB)
• Progress Animation: Real-time wavy progress indicators showing actual download progress with unified track design (wavy progress + flat remaining)
• File Type Icons: Intelligent file icons based on extension (PDF, images, audio, video, text files)
• Pull-to-Refresh: Material 3 pull-to-refresh functionality for refreshing file listings
• Biometric Authentication: Secure biometric unlock for connections with auto-authentication
• Connection Reordering: Move up/down buttons in connection menu for custom ordering
• Settings System: Persistent settings with theme switching and view mode preferences
• UI Framework: Material 3 interface with expressive floating toolbars and navigation
• System UI: Adaptive status bar colors that automatically adjust to light/dark theme
• Architecture: Clean Architecture implementation with Hilt DI
• Secure Storage: Android Keystore encryption for credentials
• Connection Management: Add, edit, test, and manage server connections with configurable starting directories for SFTP, and a non-blocking warning when a hostname, username, share or starting directory starts or ends with a space
• About Section: Developer information with clickable website link and version info

⚠️ Known Issues

• Directory Downloads: Directory downloads are skipped (files only for now)

Features

Protocol Support

• SMB - Server Message Block for Windows file sharing (✅ Fully functional)
• SFTP - SSH File Transfer Protocol with secure authentication (✅ Fully functional)

Security & Storage

• Encrypted Credentials - Android Keystore integration for secure credential storage
• Biometric Authentication - Optional biometric unlock for stored credentials
• Session Management - Secure connection handling with automatic cleanup

Modern Android Stack

• Material 3 Design - Expressive UI following Google's latest design system
• Jetpack Compose - Modern declarative UI framework
• Clean Architecture - Separation of concerns with data/domain/presentation layers
• Dependency Injection - Hilt for scalable dependency management

Technical Architecture

Project Structure

app/src/main/java/com/grid/app/
├── data/
│   ├── local/          # Local storage and encryption
│   ├── remote/         # Network clients (SFTP, SMB)
│   └── repository/     # Repository implementations
├── domain/
│   ├── model/          # Domain entities
│   ├── repository/     # Repository interfaces
│   └── usecase/        # Business logic use cases
├── presentation/
│   ├── theme/          # Material 3 theming
│   └── ui/             # Compose UI components
└── di/                 # Dependency injection modules

Key Technologies

• Kotlin 2.3 (AGP built-in Kotlin) with Coroutines for asynchronous programming
• Android Gradle Plugin 9.4 with Gradle 9.6 (compileSdk 37, targetSdk 36)
• Jetpack Compose 1.12 with Material 3 Expressive (material3 1.5)
• Hilt 2.60 for dependency injection
• DataStore for preferences storage
• Android Keystore for credential encryption

Network Libraries

• Apache MINA SSHD - SFTP client with SSH support
• SMBJ - SMB/CIFS client for Windows file sharing

Media Libraries

• ExoPlayer - Advanced media playback with custom controls and notification integration
• Coil - Modern image loading with gesture support

Archive Libraries

• Apache Commons Compress - Multi-format archive processing (ZIP, TAR, GZIP)
• Junrar - RAR archive support
• XZ for Java - LZMA/XZ compression support

Document & Content Libraries

• JSoup - HTML parsing and processing for EPUB content and image extraction
• Markwon - Markdown rendering with HTML support for rich markdown viewing

Getting Started

Prerequisites

• Android Studio Arctic Fox (2020.3.1) or later
• Android SDK API 24 (Android 7.0) minimum
• JDK 11 or later

Installation

1. Clone the repository:

   git clone <repository-url>
   cd grid

2. Open the project in Android Studio

3. Sync the project and install dependencies:

   ./gradlew build

4. Run the application:

   • Connect an Android device or start an emulator
   • Click "Run" in Android Studio or use:

   ./gradlew installDebug

Building

# Debug build
./gradlew assembleDebug

# Release build
./gradlew assembleRelease

# Run tests
./gradlew test

# Run lint checks
./gradlew lint

Git hooks (version bump + signed bundle)

A tracked pre-commit hook in .githooks/ keeps the release version from being forgotten. On any commit that touches the app (anything under app/, or a Gradle build file) it:

1. Increments the patch of appVersionName in app/build.gradle.kts and re-stages it (versionCode is derived from it), and
2. Builds and signs the release AAB for the new version. A build/lint failure aborts the commit and rolls the bump back, so no version is skipped.

Commits that don't touch the app (docs, tooling) skip both steps. The signed-bundle step needs keystore.properties at the repo root; without it the bump still happens and the build is skipped.

Activate the hooks once per clone (Git doesn't track core.hooksPath):

git config core.hooksPath .githooks

Bypass for a single commit with git commit --no-verify.

Configuration

Network Permissions

The app requires network permissions to connect to remote servers. These are declared in the AndroidManifest.xml:

• android.permission.INTERNET
• android.permission.ACCESS_NETWORK_STATE

Biometric Permissions

For biometric authentication (optional):

• android.permission.USE_BIOMETRIC
• android.permission.USE_FINGERPRINT

Usage

Adding a Server Connection

1. Open the Grid application
2. Tap "Add Connection"
3. Select protocol (SFTP or SMB)
4. Enter server details:
   • Hostname/IP address
   • Port (optional, uses protocol defaults)
   • Username and password/SSH key
   • Starting directory (optional, for SFTP only)
5. Test the connection to verify settings
6. Save the connection

Note: SMB connection testing works reliably and accurately reflects connection status.

Managing Credentials

• Credentials are automatically encrypted using Android Keystore
• Enable biometric authentication in settings for additional security
• Credentials are stored locally and never transmitted unencrypted

File Operations

• Browse remote directories with pull-to-refresh functionality
• Download files to local storage (Downloads/Grid/<connection>/…, also listed in Offline Files)
• Upload files from device with real-time progress indicators
• Create, rename, and delete files/folders with confirmation dialogs (includes recursive deletion of non-empty directories)
• Multi-select mode for batch operations
• Open text, image, PDF, audio, video, archive, code, ebook, and markdown files with built-in viewers featuring smooth keyboard scrolling for text editing, pinch-to-zoom and pan gestures, advanced EPUB ebook reading with swipe navigation, rich text formatting, image support, scroll position preservation, code syntax highlighting with line numbers, and rich markdown rendering
• Extract archive files (ZIP, RAR, 7-Zip, TAR, GZIP) with real-time progress tracking and automatic server upload
• Play animated GIFs with automatic animation and zoom support
• Access Grid files through other apps' file pickers via DocumentsProvider integration
• Sort files by name, type, or modification date

Development

Code Style

• Follow Kotlin coding conventions
• Use ktlint for code formatting
• Maintain test coverage for business logic

Architecture Guidelines

• Keep domain layer pure Kotlin (no Android dependencies)
• Use Repository pattern for data access
• Implement use cases for business logic
• Follow MVVM pattern in presentation layer

Adding New Protocols

1. Create a new client class implementing NetworkClient interface
2. Add protocol enum value in Protocol.kt
3. Update NetworkClientFactory to handle the new protocol
4. Add corresponding UI elements for protocol-specific settings

Security Considerations

Credential Storage

• All credentials are encrypted using Android Keystore
• Encryption keys are hardware-backed when available
• Credentials are automatically wiped on app uninstall

Network Security

• Connections use protocol-native security (SSH for SFTP, etc.)
• Certificate validation is enforced for secure connections
• No credentials are logged or transmitted in plain text

Permissions

• Minimal permission model - only required permissions are requested
• Biometric authentication is optional and can be disabled
• Network access is restricted to user-configured servers

Contributing

Development Setup

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-feature
3. Make your changes following the coding standards
4. Add tests for new functionality
5. Run the full test suite: ./gradlew test
6. Submit a pull request

Pull Request Guidelines

• Include a clear description of changes
• Add tests for new features
• Update documentation as needed
• Ensure all existing tests pass
• Follow the existing code style

Acknowledgments

• Apache MINA SSHD for SFTP connectivity
• SMBJ for SMB/CIFS protocol support
• Android Jetpack for modern Android development components
• Material Design for UI/UX guidelines

Support

For issues, feature requests, or questions:

• Open an issue on the project repository
• Follow the issue template for bug reports
• Include device information and logs for troubleshooting

---

Grid - Bringing remote file management to Android with security and modern design.