Skip to content
sysout.dev

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) as the primary storage model. 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.

The browser layer still supports SAF content:// tree URIs through DocumentFile. That is retained as a compatibility path and possible future fallback, but the MVP user flow is 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

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

  1. Package/name/template cleanup

  2. Home, folder listing, settings, and about routes

  3. All-files access flow

  4. Quick access auto-population

  5. In-app folder picker for pins

  6. Light/dark theme support

  7. 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.

  • Whether folder row metadata should include item counts. It is intentionally omitted for now to avoid slow recursive reads.