# itsahadun/macat architecture

> Architecture diagram of the GitHub repository itsahadun/macat, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/itsahadun/macat
- Repository: https://github.com/itsahadun/macat

## Overview

#### 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/`

Main entry points: [`app/src/main/java/com/ahad/macat/Navigation.kt`](https://github.com/itsahadun/macat/blob/main/app/src/main/java/com/ahad/macat/Navigation.kt) (Navigation), [`app/src/main/java/com/ahad/macat/ui/CatalogueViewModel.kt`](https://github.com/itsahadun/macat/blob/main/app/src/main/java/com/ahad/macat/ui/CatalogueViewModel.kt) (Catalogue view model), [`app/src/main/java/com/ahad/macat/ui/add/AddItemScreen.kt`](https://github.com/itsahadun/macat/blob/main/app/src/main/java/com/ahad/macat/ui/add/AddItemScreen.kt) (Add item), [`app/src/main/java/com/ahad/macat/ui/add/BulkAddScreen.kt`](https://github.com/itsahadun/macat/blob/main/app/src/main/java/com/ahad/macat/ui/add/BulkAddScreen.kt) (Bulk add)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Android app"]
  node_manifest["Android manifest<br/>entry config"]
  node_main_activity["Main activity<br/>Compose host<br/>[MainActivity.kt]"]
  node_app_root["MaCat app<br/>root composition<br/>[MaCatApp.kt]"]
  node_navigation["Navigation<br/>route coordinator<br/>[Navigation.kt]"]
  node_theme["Theme<br/>Compose styling<br/>[Theme.kt]"]
  node_browse["Feed and grid<br/>catalogue browsers"]
end

subgraph group_catalogue["Catalogue data"]
  node_catalogue_vm["Catalogue view model<br/>UI state boundary"]
  node_repository["Item repository<br/>data abstraction<br/>[ItemRepository.kt]"]
  node_item_dao["Item DAO<br/>persistence access<br/>[ItemDao.kt]"]
  node_database[("Catalogue database<br/>Room database")]
  node_item["Item<br/>catalogue entity<br/>[Item.kt]"]
  node_photo_store["Photo store<br/>local file storage<br/>[PhotoStore.kt]"]
end

subgraph group_acquisition["Item acquisition"]
  node_add_item["Add item<br/>single-item flow<br/>[AddItemScreen.kt]"]
  node_bulk_add["Bulk add<br/>multi-item flow<br/>[BulkAddScreen.kt]"]
  node_camera["Camera capture<br/>device capability"]
end

subgraph group_release["Distribution"]
  node_gradle["Gradle build<br/>Android build setup<br/>[build.gradle.kts]"]
  node_fdroid_recipe["F-Droid recipe<br/>release metadata<br/>[com.ahad.macat.yml]"]
  node_store_metadata["Fastlane metadata<br/>store metadata"]
end

node_manifest -->|"launches"| node_main_activity
node_main_activity -->|"hosts"| node_app_root
node_app_root -->|"installs"| node_navigation
node_app_root -->|"applies"| node_theme
node_navigation -->|"routes to"| node_browse
node_navigation -->|"routes to"| node_add_item
node_navigation -->|"routes to"| node_bulk_add
node_navigation -->|"routes to"| node_camera
node_browse -->|"reads and filters"| node_catalogue_vm
node_add_item -->|"creates item"| node_catalogue_vm
node_bulk_add -->|"creates items"| node_catalogue_vm
node_camera -->|"hands off photo"| node_add_item
node_camera -->|"hands off photos"| node_bulk_add
node_add_item -->|"stores image"| node_photo_store
node_bulk_add -->|"stores images"| node_photo_store
node_catalogue_vm -->|"uses"| node_repository
node_catalogue_vm -->|"coordinates file lifecycle"| node_photo_store
node_repository -->|"persists through"| node_item_dao
node_item_dao -->|"accesses"| node_database
node_database -->|"stores"| node_item
node_gradle -->|"builds app"| node_manifest
node_fdroid_recipe -->|"builds tagged source"| node_gradle
node_store_metadata -.->|"supports release"| node_fdroid_recipe

click node_manifest "https://github.com/itsahadun/macat/blob/main/app/src/main/AndroidManifest.xml"
click node_main_activity "https://github.com/itsahadun/macat/blob/main/app/src/main/java/com/ahad/macat/MainActivity.kt"
click node_app_root "https://github.com/itsahadun/macat/blob/main/app/src/main/java/com/ahad/macat/MaCatApp.kt"
click node_navigation "https://github.com/itsahadun/macat/blob/main/app/src/main/java/com/ahad/macat/Navigation.kt"
click node_theme "https://github.com/itsahadun/macat/blob/main/app/src/main/java/com/ahad/macat/theme/Theme.kt"
click node_catalogue_vm "https://github.com/itsahadun/macat/blob/main/app/src/main/java/com/ahad/macat/ui/CatalogueViewModel.kt"
click node_repository "https://github.com/itsahadun/macat/blob/main/app/src/main/java/com/ahad/macat/data/ItemRepository.kt"
click node_item_dao "https://github.com/itsahadun/macat/blob/main/app/src/main/java/com/ahad/macat/data/ItemDao.kt"
click node_database "https://github.com/itsahadun/macat/blob/main/app/src/main/java/com/ahad/macat/data/CatalogueDatabase.kt"
click node_item "https://github.com/itsahadun/macat/blob/main/app/src/main/java/com/ahad/macat/data/Item.kt"
click node_photo_store "https://github.com/itsahadun/macat/blob/main/app/src/main/java/com/ahad/macat/data/PhotoStore.kt"
click node_add_item "https://github.com/itsahadun/macat/blob/main/app/src/main/java/com/ahad/macat/ui/add/AddItemScreen.kt"
click node_bulk_add "https://github.com/itsahadun/macat/blob/main/app/src/main/java/com/ahad/macat/ui/add/BulkAddScreen.kt"
click node_camera "https://github.com/itsahadun/macat/blob/main/app/src/main/java/com/ahad/macat/ui/add/CameraCaptureScreen.kt"
click node_gradle "https://github.com/itsahadun/macat/blob/main/app/build.gradle.kts"
click node_fdroid_recipe "https://github.com/itsahadun/macat/blob/main/metadata/com.ahad.macat.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_manifest,node_main_activity,node_app_root,node_navigation,node_theme,node_browse toneBlue
class node_catalogue_vm,node_repository,node_item_dao,node_database,node_item,node_photo_store toneAmber
class node_add_item,node_bulk_add,node_camera toneMint
class node_gradle,node_fdroid_recipe,node_store_metadata toneRose
```

## Components

### Android app

- [Android manifest](https://github.com/itsahadun/macat/blob/main/app/src/main/AndroidManifest.xml): entry config · `app/src/main/AndroidManifest.xml`
- [Main activity](https://github.com/itsahadun/macat/blob/main/app/src/main/java/com/ahad/macat/MainActivity.kt): Compose host · `app/src/main/java/com/ahad/macat/MainActivity.kt`
- [MaCat app](https://github.com/itsahadun/macat/blob/main/app/src/main/java/com/ahad/macat/MaCatApp.kt): root composition · `app/src/main/java/com/ahad/macat/MaCatApp.kt`
- [Navigation](https://github.com/itsahadun/macat/blob/main/app/src/main/java/com/ahad/macat/Navigation.kt): route coordinator · Centralizes routes and route arguments. · `app/src/main/java/com/ahad/macat/Navigation.kt`
- [Theme](https://github.com/itsahadun/macat/blob/main/app/src/main/java/com/ahad/macat/theme/Theme.kt): Compose styling · `app/src/main/java/com/ahad/macat/theme/Theme.kt`
- **Feed and grid**: catalogue browsers · Shared state drives vertical feed and compact grid views.

### Catalogue data

- [Catalogue view model](https://github.com/itsahadun/macat/blob/main/app/src/main/java/com/ahad/macat/ui/CatalogueViewModel.kt): UI state boundary · Owns shared catalogue state, filtering, and mutations. · `app/src/main/java/com/ahad/macat/ui/CatalogueViewModel.kt`
- [Item repository](https://github.com/itsahadun/macat/blob/main/app/src/main/java/com/ahad/macat/data/ItemRepository.kt): data abstraction · `app/src/main/java/com/ahad/macat/data/ItemRepository.kt`
- [Item DAO](https://github.com/itsahadun/macat/blob/main/app/src/main/java/com/ahad/macat/data/ItemDao.kt): persistence access · `app/src/main/java/com/ahad/macat/data/ItemDao.kt`
- [Catalogue database](https://github.com/itsahadun/macat/blob/main/app/src/main/java/com/ahad/macat/data/CatalogueDatabase.kt): Room database · Owns schema and database construction. · `app/src/main/java/com/ahad/macat/data/CatalogueDatabase.kt`
- [Item](https://github.com/itsahadun/macat/blob/main/app/src/main/java/com/ahad/macat/data/Item.kt): catalogue entity · Structured metadata including a photo reference. · `app/src/main/java/com/ahad/macat/data/Item.kt`
- [Photo store](https://github.com/itsahadun/macat/blob/main/app/src/main/java/com/ahad/macat/data/PhotoStore.kt): local file storage · Stores owned image files separately from item records. · `app/src/main/java/com/ahad/macat/data/PhotoStore.kt`

### Item acquisition

- [Add item](https://github.com/itsahadun/macat/blob/main/app/src/main/java/com/ahad/macat/ui/add/AddItemScreen.kt): single-item flow · `app/src/main/java/com/ahad/macat/ui/add/AddItemScreen.kt`
- [Bulk add](https://github.com/itsahadun/macat/blob/main/app/src/main/java/com/ahad/macat/ui/add/BulkAddScreen.kt): multi-item flow · Acquires photos before per-item metadata entry. · `app/src/main/java/com/ahad/macat/ui/add/BulkAddScreen.kt`
- [Camera capture](https://github.com/itsahadun/macat/blob/main/app/src/main/java/com/ahad/macat/ui/add/CameraCaptureScreen.kt): device capability · Handles permission, lifecycle, and output-photo handoff. · `app/src/main/java/com/ahad/macat/ui/add/CameraCaptureScreen.kt`

### Distribution

- [Gradle build](https://github.com/itsahadun/macat/blob/main/app/build.gradle.kts): Android build setup · `app/build.gradle.kts`
- [F-Droid recipe](https://github.com/itsahadun/macat/blob/main/metadata/com.ahad.macat.yml): release metadata · Coordinates immutable-tag F-Droid distribution. · `metadata/com.ahad.macat.yml`
- **Fastlane metadata**: store metadata

## Connections

- Android manifest → Main activity: launches
- Main activity → MaCat app: hosts
- MaCat app → Navigation: installs
- MaCat app → Theme: applies
- Navigation → Feed and grid: routes to
- Navigation → Add item: routes to
- Navigation → Bulk add: routes to
- Navigation → Camera capture: routes to
- Feed and grid → Catalogue view model: reads and filters
- Add item → Catalogue view model: creates item
- Bulk add → Catalogue view model: creates items
- Camera capture → Add item: hands off photo
- Camera capture → Bulk add: hands off photos
- Add item → Photo store: stores image
- Bulk add → Photo store: stores images
- Catalogue view model → Item repository: uses
- Catalogue view model → Photo store: coordinates file lifecycle
- Item repository → Item DAO: persists through
- Item DAO → Catalogue database: accesses
- Catalogue database → Item: stores
- Gradle build → Android manifest: builds app
- F-Droid recipe → Gradle build: builds tagged source
- Fastlane metadata → F-Droid recipe: supports release