Treeger - Design Doc

The original Treeger MVP problem statement, scope, architecture, decisions, and milestones.

This document records the original view-only MVP baseline. Treeger has since delivered file operations, search, multiple views, Trash, and Spaces. See the user guide for current user-visible behavior and the roadmap for the evolving product direction.

Problem Statement

Existing Android file managers provide fixed or semi-fixed home views: tabs such as Local/Library/Network, or categories such as Downloads/Photos/Videos. treeger starts from a smaller idea: the app’s own landing screen should be shaped around the folders the user actually cares about.

The MVP is a view-only file browser with a customizable home screen. Later, this could grow into a general-purpose file explorer with content-oriented defaults for books, photos, and other user-defined views.

Scope

In Scope

View-only local file browsing
User-defined pinned folders on the app home screen
Add, remove, and reorder pinned folders
Quick access to standard public folders: Downloads, DCIM, Pictures, Documents, and Movies
Folder detail screen with breadcrumbs and sorting
File handoff to external viewer apps
Settings and About routes
Neutral light/dark visual system with Canopy and Bloom identity colors

Out of Scope

The following features are not in scope for the MVP, but may be added later:

Copy, move, rename, delete
Search
Archive handling
Cloud or network storage
In-app file rendering
3D/zoom visualization

Architecture

Storage Access

The current MVP uses Android all-files access (MANAGE_EXTERNAL_STORAGE) on Android 11 and newer. This was chosen because quick access should open standard folders directly and pinned-folder creation should not require a separate system permission grant for every folder.

The app requests all-files access only when it needs to browse local shared storage. If access is not granted, quick access shows an explicit action that sends the user to the system all-files access settings screen.

Android 10 does not provide MANAGE_EXTERNAL_STORAGE, and a modern target SDK is subject to scoped storage there. On API 29, treeger requests the legacy media read permission for MediaStore features and then asks the user to grant the primary storage root through ACTION_OPEN_DOCUMENT_TREE. The persisted read/write tree URI becomes the Device Storage root for browsing, search, catalogue scans, and pins.

The browser layer supports those SAF content:// tree URIs through DocumentFile. Android 11 and newer continue to use local file browsing through all-files access.

Data Model

Pinned folder entity:

URI
Display name
Order index

Sort preferences are also stored locally.

Persistence: DataStore.

UI

Detailed mock screens and user flows are provided in docs/mocks/.

Toolkit: Jetpack Compose
Navigation: Compose Navigation
Home screen: pinned folders plus fixed quick access section
Folder picker: in-app local folder picker
Folder detail screen: local/DocumentFile listing with name, size, modified date, type, and sorting
File opening: ACTION_VIEW intent via FileProvider for local files

Platform

Minimum SDK: Android 10 / API 29.

Decision Log

Decision Choice Rationale

Decision	Choice	Rationale
Storage access	All-files access for MVP	Quick access folders should open directly, and a file-manager-style app is one of the permitted categories for this access on Google Play when it is core functionality and declared properly.
SAF support	Keep browser support for `content://` tree URIs	Allows a future privacy-friendlier fallback without rewriting the listing layer.
Local persistence	DataStore	Pinned folders, theme, and sort preferences are simple app configuration, not relational data.
UI toolkit	Jetpack Compose	Good fit for a small modern Android app with direct state-driven UI.
Minimum SDK	API 29 (Android 10)	Avoids very old storage behavior and supports the current adaptive icon path.
Visual identity	Neutral foundation with selectable Canopy and Bloom identity colors	Quiet working surfaces keep file browsing comfortable while the selected identity supplies recognisable treeger landmarks.

Storage access

All-files access for MVP

Quick access folders should open directly, and a file-manager-style app is one of the permitted categories for this access on Google Play when it is core functionality and declared properly.

SAF support

Keep browser support for content:// tree URIs

Allows a future privacy-friendlier fallback without rewriting the listing layer.

Local persistence

DataStore

Pinned folders, theme, and sort preferences are simple app configuration, not relational data.

UI toolkit

Jetpack Compose

Good fit for a small modern Android app with direct state-driven UI.

Minimum SDK

API 29 (Android 10)

Avoids very old storage behavior and supports the current adaptive icon path.

Visual identity

Neutral foundation with selectable Canopy and Bloom identity colors

Quiet working surfaces keep file browsing comfortable while the selected identity supplies recognisable treeger landmarks.

Milestones

Package/name/template cleanup
Home, folder listing, settings, and about routes
All-files access flow
Quick access auto-population
In-app folder picker for pins
Light/dark theme support
Startup phase smoothing

Open Questions

Whether Play review accepts all-files access for the MVP as-is. The app’s store description and Permissions Declaration Form must clearly present file management as the core purpose.
Whether to add a SAF-only mode later for users who do not want all-files access.
Folder row metadata now comes from a persistent bottom-up catalogue rather than recursive reads performed by visible rows. Physical-device performance verification remains pending.