itsahadun/macat

Purpose and Runtime

maCat is an offline Android personal wardrobe catalogue. Users photograph or import clothing, shoes, and jewellery, categorize items, and browse them in a full-screen vertical feed or grid. It is a native Kotlin Android app built with Gradle, requiring JDK 17 and Android compileSdk 36. The application has no accounts, network services, tracking, or server backend.

Core Android entry configuration is in app/src/main/AndroidManifest.xml; Gradle application/version setup is in app/build.gradle.kts.

Application Bootstrap and Navigation

MainActivity hosts the Compose application, while MaCatApp establishes the root app composition/theme. Navigation routes and route arguments are centralized separately, allowing feed, grid, add-item, bulk-add, and camera flows to transition without screens directly owning app-level routing.

Paths:

• app/src/main/java/com/ahad/macat/MainActivity.kt

• app/src/main/java/com/ahad/macat/MaCatApp.kt

• app/src/main/java/com/ahad/macat/Navigation.kt

• app/src/main/java/com/ahad/macat/NavigationKeys.kt

Catalogue State Boundary

CatalogueViewModel is the UI-facing state and action boundary. Screens consume its catalogue data and invoke mutations through it rather than interacting directly with persistence. It coordinates filtering/category selection and item lifecycle actions across feed, grid, and item creation flows.

Path:

• app/src/main/java/com/ahad/macat/ui/CatalogueViewModel.kt

Persistent Catalogue Data

The local Room-style database layer models wardrobe records and isolates SQL/database access. Item is the catalogue entity, ItemDao provides persistence operations, and ItemRepository is the abstraction used above the storage layer. CatalogueDatabase owns database construction and schema access.

Paths:

• app/src/main/java/com/ahad/macat/data/Item.kt

• app/src/main/java/com/ahad/macat/data/ItemDao.kt

• app/src/main/java/com/ahad/macat/data/ItemRepository.kt

• app/src/main/java/com/ahad/macat/data/CatalogueDatabase.kt

Local Photo Storage

Images are stored on-device outside the item database through PhotoStore. This separates binary photo-file handling from structured item metadata: capture/import produces a local photo reference, then item persistence records the associated catalogue data. Deletion/update flows must preserve consistency between database records and owned image files.

Path:

• app/src/main/java/com/ahad/macat/data/PhotoStore.kt

Item Acquisition Flows

Single-item addition supports camera capture or gallery selection, followed by item naming/categorization. Bulk addition separates acquisition from metadata entry: users capture/import multiple photos first, then identify each item. The camera screen is a platform/device capability boundary and must handle lifecycle, permission, and output-photo handoff into the add flows.

Paths:

• app/src/main/java/com/ahad/macat/ui/add/AddItemScreen.kt

• app/src/main/java/com/ahad/macat/ui/add/BulkAddScreen.kt

• app/src/main/java/com/ahad/macat/ui/add/CameraCaptureScreen.kt

Browsing and Presentation

The feed is the primary consumption surface: a full-screen, vertically swiped, looping item experience. The grid provides a compact overview. Both operate over the shared view-model state and category filters, avoiding duplicate data ownership. Shared Compose visual styling is defined in the theme package.

Paths:

• app/src/main/java/com/ahad/macat/ui/feed/FeedScreen.kt

• app/src/main/java/com/ahad/macat/ui/grid/GridScreen.kt

• app/src/main/java/com/ahad/macat/theme/Theme.kt

Distribution Boundary

The app is distributed through F-Droid from immutable git tags, with scanner-compatible dependency constraints: no proprietary dependencies, trackers, or build-time fetched prebuilt binaries. Store metadata/changelogs are maintained under Fastlane, while the F-Droid recipe is represented locally for release coordination.

Paths:

• app/build.gradle.kts

• metadata/com.ahad.macat.yml

• fastlane/metadata/android/en-US/